Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PEP 773: Textual tweaks and clarifications #4249

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

PEP 773: Textual tweaks and clarifications #4249

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8d61cc8
PEP 773: Textual tweaks and clarifications
zooba Feb 4, 2025
b200efd
Rename displayName key to display-name
zooba Feb 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 27 additions & 24 deletions peps/pep-0773.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -532,12 +532,8 @@ prefixes, preferring a full match over a prefix, and tags use case-insensitive,
number-aware matches, with dotted numbers treated as versions. Tags must match
one of the listed "install for" tags, and entries list multiple such tags to
handle abbreviated requests. The special tag ``default`` resolves to the user's
configured default (typically ``3``).

For example, the ``3.10.5`` entry would list all of ``3``, ``3.10`` and
``3.10.5`` as tags to be installed for. A request for ``3.10`` would match one
of these and so the entry is selected. Due to the number-aware matches, a
request for ``03.0010`` would also match, and ``3.10.50`` would not.
configured default (typically ``3``; see Configuration later for details on
configuring settings).

Tags may also be specified as a constraint, using ``>``, ``>=``, ``<``, ``<=``
or ``!=`` followed by the ``Company\\Tag`` or ``Tag`` value. When matching a
Expand All @@ -553,12 +549,14 @@ Users are expected to use shorter tags for convenience, rather than ranges.

The default index file is hosted on python.org, and contains install information
including package URLs and hashes for all installable versions. An alternate
index may be specified by the user or their administrator (see Configuration
below). Entries in the index file list the full set of tags they should be
installed for, and if an exact match is found the package will be selected. In
the case of no exact match, a prefix match will be used. In both cases, numbers
in the tag are treated logically - that is, ``3.1`` is a prefix of ``3.1.2`` but
not of ``3.10``.
index may be specified by the user using a configuration file or the
``--source`` command line option, or their administrator through a configuration
file. The requested tag is matched against the index file, and if an exact match
is found the package will be selected. In the case of no exact match, a prefix
match will be used. In both cases, numbers in the tag are treated logically -
that is, ``3.1`` is a prefix of ``3.1.2`` but not of ``3.10``. See Index Schema
below for information on exactly how install tags are specified in the index
file.

If a tag is already satisfied by an existing install, nothing will be installed.
The user must pass an ``--upgrade`` or ``--force`` option to replace the
Expand All @@ -581,10 +579,11 @@ install (or generating aliases or shortcuts). This is intended to cover
embedding cases, or downloading the files for incompatible platforms. Passing
multiple tags with ``--target`` is an error.

If the ``--download <DIR>`` option is passed, runtimes will be downloaded to the
specified directory as their source packages, and an ``index.json`` will be
created referencing these files. This index can be referenced later to perform
offline installs with ``python install --source <index.json> [tag ...]``.
If the ``--download <DIR>`` option is passed, runtime packages are downloaded
but not installed. They are stored in the specified directory as their source
packages, and an ``index.json`` is created that references these files. This
index can be used later to perform offline installs with ``python install
--source <index.json> [tag ...]``.


Uninstall subcommand
Expand All @@ -600,14 +599,15 @@ inspect existing installs. Unless the ``--yes`` option is passed, the user will
be prompted before uninstalling each runtime.

If the ``--purge`` option is passed with no tags, then (after confirmation) all
runtimes will be removed, along with shortcuts and any cached files.
runtimes will be removed, along with shortcuts and any cached files. Passing any
tags with ``--purge`` will produce an error.

Uninstalling PyManager does not uninstall any runtimes that were installed. For
technical reasons, this would not be reliably possible (we cannot run arbitrary
code at uninstall time), and so instead we deliberately ensure that anything
that has been installed will continue to work. Reinstalling PyManager allows
management of these installs to resume. Running ``py uninstall --purge`` before uninstalling
PyManager will perform a complete uninstall.
management of these installs to resume. Running ``py uninstall --purge`` before
uninstalling PyManager will perform a complete uninstall.


List subcommand
Expand All @@ -625,7 +625,7 @@ PyManager (including an active virtual environment) may be listed separately.

The default format is user-friendly. Other formats will include machine-readable
and single string formats (e.g. ``--format=prefix`` simply prints ``sys.prefix``
on a line by itself). The exact list of formats is left to implementation.
on a line by itself). The exact list of formats is left to the implementation.

If ``--one`` is provided, only the best result is listed. This is to assist
shell scripts that want to locate the default (or a suitable) runtime without
Expand Down Expand Up @@ -815,7 +815,7 @@ The initial schema is shown below:
"id": str,

# Name to display in the UI
"displayName": str,
"display-name": str,

# Version used to sort packages. Also determines prerelease status.
# Should follow Python's format, but is only compared among releases
Expand All @@ -837,6 +837,9 @@ The initial schema is shown below:

# List of tags to install this package for. This does not have to be
# unique across all installs; the first match will be selected.
# For example, the 3.10.5 package may list '3', '3.10' and
# '3.10.5' so that any of those may be specified to install it.
# Matches are number aware, so that 3.1 is not a prefix of 3.10.
"install-for": [str],

# List of tags to run this package for. Does not have to be unique
Expand Down Expand Up @@ -877,7 +880,7 @@ The initial schema is shown below:
}
],

# Full or partial URL to the next index file
# URL (or relative path) to the next index file
"next": str,
}

Expand Down Expand Up @@ -1309,8 +1312,8 @@ We suggest an explanation like this:
This will remove all installs and any shortcuts that would otherwise be left
behind. If you already removed the manager, you can reinstall it and run the
above uninstall command again to clean up. Individual runtimes can be
uninstalled by replacing the ``--purge`` option with the tag, found by looking
at ``python list``.
uninstalled by specifying the tag instead of ``--purge``. Tags can be found
by looking at ``python list``.


Configuration
Expand Down
Loading