pystand 2.3__tar.gz → 2.5__tar.gz

{pystand-2.3 → pystand-2.5}/Makefile

@@ -13,7 +13,7 @@ upload: build
 	twine3 upload dist/*
 
 doc:
-	update-readme-usage
+	update-readme-usage -A
 
 clean:
 	@rm -vrf *.egg-info build/ dist/ __pycache__

{pystand-2.3/pystand.egg-info → pystand-2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pystand
-Version: 2.3
+Version: 2.5
 Summary: Install Python versions from python-build-standalone project
 Author-email: Mark Blakeney <mark.blakeney@bullet-systems.net>
 License: GPLv3
@@ -131,7 +131,7 @@ usage: pystand [-h] [-D DISTRIBUTION] [-P PREFIX_DIR] [-C CACHE_DIR]
                   [-M CACHE_MINUTES] [--purge-days PURGE_DAYS]
                   [--github-access-token GITHUB_ACCESS_TOKEN] [--no-strip]
                   [-V]
-                  {install,update,remove,list,show,path} ...
+                  {install,update,upgrade,remove,uninstall,list,show,path} ...
 
 Command line tool to download, install, and update pre-built Python versions
 from the python-build-standalone project at
@@ -140,9 +140,9 @@ https://github.com/indygreg/python-build-standalone.
 options:
   -h, --help            show this help message and exit
   -D DISTRIBUTION, --distribution DISTRIBUTION
-                        python-build-standalone distribution. Default is auto-
-                        detected (detected as "x86_64-unknown-linux-gnu-
-                        install_only_stripped" for this current host).
+                        python-build-standalone distribution. Default is
+                        "x86_64-unknown-linux-gnu-install_only_stripped" for
+                        this host.
   -P PREFIX_DIR, --prefix-dir PREFIX_DIR
                         specify prefix dir for storing versions. Default is
                         "$HOME/.local/share/pystand"
@@ -164,18 +164,18 @@ options:
   -V, --version         just show pystand version
 
 Commands:
-  {install,update,remove,list,show,path}
+  {install,update,upgrade,remove,uninstall,list,show,path}
     install             Install one or more versions from a python-build-
                         standalone release.
-    update              Update one, more, or all versions to another release.
-    remove              Remove/uninstall one, more, or all versions.
+    update (upgrade)    Update one, more, or all versions to another release.
+    remove (uninstall)  Remove/uninstall one, more, or all versions.
     list                List installed versions and show which have an update
                         available.
     show                Show versions available from a release.
     path                Show path prefix to installed version base directory.
 
-Note you can set default starting global options in
-$HOME/.config/pystand-flags.conf.
+Some commands offer aliases as shown in brackets above. Note you can set
+default starting global options in $HOME/.config/pystand-flags.conf.
 ```
 
 Type `pystand <command> -h` to see specific help/usage for any
@@ -184,7 +184,7 @@ individual command:
 ### Command `install`
 
 ```
-usage: pystand install [-h] [-r RELEASE] [-f] version [version ...]
+usage: pystand install [-h] [-r RELEASE] [-f] [-s] version [version ...]
 
 Install one or more versions from a python-build-standalone release.
 
@@ -198,6 +198,8 @@ options:
                         YYYYMMDD release (e.g. 20240415), default is latest
                         release
   -f, --force           force install even if already installed
+  -s, --include-source  also install source files if available in distribution
+                        download
 ```
 
 ### Command `update`
@@ -220,6 +222,8 @@ options:
                         can be specified with --all)
   -k, --keep            keep old version after updating (but only if different
                         version number)
+
+aliases: upgrade
 ```
 
 ### Command `remove`
@@ -240,6 +244,8 @@ options:
   -r RELEASE, --release RELEASE
                         only remove versions if from specified YYYMMDD release
                         (e.g. 20240415)
+
+aliases: uninstall
 ```
 
 ### Command `list`
@@ -264,18 +270,21 @@ options:
 ### Command `show`
 
 ```
-usage: pystand show [-h] [-a] [release]
+usage: pystand show [-h] [-r RELEASE] [-a] [re_match]
 
 Show versions available from a release.
 
 positional arguments:
-  release     python-build-standalone YYYYMMDD release to show (e.g.
-              20240415), default is latest release
+  re_match              show only versions+distributions matching this regular
+                        expression pattern
 
 options:
-  -h, --help  show this help message and exit
-  -a, --all   also show all available distributions for each version from the
-              release
+  -h, --help            show this help message and exit
+  -r RELEASE, --release RELEASE
+                        python-build-standalone YYYYMMDD release to show (e.g.
+                        20240415), default is latest release
+  -a, --all             show all available distributions for each version from
+                        the release
 ```
 
 ### Command `path`
@@ -320,35 +329,6 @@ To uninstall:
 $ pipx uninstall pystand
 ```
 
-## Installing Other Builds/Distributions
-
-The _`install_only_stripped`_ build of each distribution is installed by
-default. See description of distributions/builds
-[here](https://gregoryszorc.com/docs/python-build-standalone/main/running.html#obtaining-distributions).
-However, you can choose to install other distributions/builds. E.g. If
-we use a standard modern Linux x86_64 machine as an example, the default
-distribution is _`x86_64-unknown-linux-gnu-install_only_stripped`_ and
-the versions for these are installed by default at
-`~/.local/share/pystand/<version>`.
-
-However, let's say you want to experiment with the new free-threaded
-3.13 build, installed to a different directory. E.g.:
-
-```sh
-$ mkdir ./3.13-freethreaded
-$ cd ./3.13-freethreaded
-
-$ pystand -P. -D x86_64-unknown-linux-gnu-freethreaded+lto-full install 3.13
-$ ./3.13/bin/python -V
-Python 3.13.0
-
-$ pystand -P . list
-3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+lto-full"
-```
-
-Note you can set a different default distribution by specifying
-`--distribution` as a [default option](#command-default-options).
-
 ## Extrapolation of Python Versions
 
 For all commands except the `path` command, `pystand` extrapolates
@@ -407,6 +387,150 @@ $ uv venv -p $(pystand path 3.12.2)
 $ uv venv -p $(pystand path -r 3.12)
 ```
 
+## Installing Other Builds/Distributions
+
+The _`install_only_stripped`_ distribution build is installed by default
+for your running machine architecture. See description of
+distributions/builds
+[here](https://gregoryszorc.com/docs/python-build-standalone/main/running.html#obtaining-distributions).
+However, you can choose to install other distributions/builds (even for
+other architectures). E.g. If we use a standard modern Linux x86_64
+machine as an example, the default distribution is
+_`x86_64-unknown-linux-gnu-install_only_stripped`_ and the versions for
+these are installed by default at `~/.local/share/pystand/<version>`.
+
+However, let's say you want to experiment with the new free-threaded
+3.13 build, installed to a different directory. E.g.:
+
+```sh
+$ mkdir ./3.13-freethreaded
+$ cd ./3.13-freethreaded
+
+$ pystand -P. -D x86_64-unknown-linux-gnu-freethreaded+lto-full install 3.13
+$ ./3.13/bin/python -V
+Python 3.13.0
+
+$ pystand -P . list
+3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+lto-full"
+```
+
+Note you can set a different default distribution by specifying
+`--distribution` as a [default option](#command-default-options).
+
+### Searching for Available Versions and Distributions
+
+The `show` command can be used to search for distributions as seen in the
+following examples.
+
+```sh
+
+List all the versions installed on this system (at the default location):
+
+```sh
+$ pystand list
+3.8.20 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.9.20 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+```
+
+The above shows versions 3.9, 3.12, and 3.13 are installed from the latest
+release 20241016. Version 3.8 is installed from the previous release
+20241002 (and is not available in the latest release otherwise it would
+be shown with an update message).
+
+Now show all available versions from the latest release:
+
+```sh
+$ pystand show
+3.9.20 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.10.15 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.11.10 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+```
+
+We can see that versions 3.9, 3.12, and 3.13 are already installed (as
+we also knew from list output), and that 3.10 and 3.11 are also available.
+
+What is available from the previous release 20241002?
+
+```sh
+$ pystand show -r 20241002
+3.8.20 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.9.20 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.10.15 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.11.10 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.13.0rc3 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+```
+
+Let's install one of the threaded builds of Python 3.13. We can use the
+`-a/-all` option to show all available distributions and then give the
+`show` command a [regular
+expression](https://en.wikipedia.org/wiki/Regular_expression) to filter
+the output (this is really just a shorthand for piping the output of
+`show -a` to grep). E.g.:
+
+```sh
+$ pystand show -a 3.13.*x86_64.*unknown-linux-gnu.*thread
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-freethreaded+debug-full"
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-freethreaded+pgo+lto-full"
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-freethreaded+pgo-full"
+3.13.0 @ 20241016 distribution="x86_64_v2-unknown-linux-gnu-freethreaded+debug-full"
+3.13.0 @ 20241016 distribution="x86_64_v2-unknown-linux-gnu-freethreaded+pgo+lto-full"
+3.13.0 @ 20241016 distribution="x86_64_v2-unknown-linux-gnu-freethreaded+pgo-full"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+debug-full"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+pgo-full"
+3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+debug-full"
+3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+lto-full"
+3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+noopt-full"
+```
+
+So let's install the
+`x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full` build of Python
+3.13 (to the default location):
+
+```sh
+$ pystand -D x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full install 3.13
+Version "3.13.0" is already installed.
+```
+
+An error is given because the version is already installed. We can
+overwrite that with the `-f/--force` option:
+
+```sh
+$ pystand -D x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full install -f 3.13
+Version 3.13.0 @ 20241016 installed.
+```
+
+Now we can see the new version distribution is installed:
+
+```sh
+
+$ pystand list
+3.8.20 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.9.20 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full"
+
+$ pystand show
+3.9.20 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.10.15 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.11.10 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full" (installed)
+```
+
+Note that `pystand` caches all downloaded files (at least for a period
+specified by `--purge-days`) so you can easily switch between different
+versions/distributions quite quickly. You can also choose to install any
+distribution/build in a specific directory using the `-P/--prefix-dir`
+global option if you want to keep different distributions separate and
+available in parallel.
+
 ## Command Default Options
 
 You can add default global options to a personal configuration file
@@ -423,11 +547,11 @@ as defaults.
 
 ## Github API Rate Limiting
 
-This tool minimises and caches Github API responses from the
-[`python-build-standalone`][pbs] repository. However, if you install
-many different versions particularly across various releases, you may
-get rate limited by Github so the command will block and you will see
-"backoff" messages reported. You can create a Github access token to
+This tool minimises and caches Github API responses and file downloads
+from the [`python-build-standalone`][pbs] repository. However, if you
+install many different versions particularly across various releases,
+you may get rate limited by Github so the command can block and you will
+see "backoff" messages reported. You can create a Github access token to
 gain increased rate limits. Create a token in your Github account under
 `Settings -> Developer settings -> Personal access tokens`. Specify the
 token on the command line with `--github-access-token`, or set that as a

{pystand-2.3 → pystand-2.5}/README.md

@@ -114,7 +114,7 @@ usage: pystand [-h] [-D DISTRIBUTION] [-P PREFIX_DIR] [-C CACHE_DIR]
                   [-M CACHE_MINUTES] [--purge-days PURGE_DAYS]
                   [--github-access-token GITHUB_ACCESS_TOKEN] [--no-strip]
                   [-V]
-                  {install,update,remove,list,show,path} ...
+                  {install,update,upgrade,remove,uninstall,list,show,path} ...
 
 Command line tool to download, install, and update pre-built Python versions
 from the python-build-standalone project at
@@ -123,9 +123,9 @@ https://github.com/indygreg/python-build-standalone.
 options:
   -h, --help            show this help message and exit
   -D DISTRIBUTION, --distribution DISTRIBUTION
-                        python-build-standalone distribution. Default is auto-
-                        detected (detected as "x86_64-unknown-linux-gnu-
-                        install_only_stripped" for this current host).
+                        python-build-standalone distribution. Default is
+                        "x86_64-unknown-linux-gnu-install_only_stripped" for
+                        this host.
   -P PREFIX_DIR, --prefix-dir PREFIX_DIR
                         specify prefix dir for storing versions. Default is
                         "$HOME/.local/share/pystand"
@@ -147,18 +147,18 @@ options:
   -V, --version         just show pystand version
 
 Commands:
-  {install,update,remove,list,show,path}
+  {install,update,upgrade,remove,uninstall,list,show,path}
     install             Install one or more versions from a python-build-
                         standalone release.
-    update              Update one, more, or all versions to another release.
-    remove              Remove/uninstall one, more, or all versions.
+    update (upgrade)    Update one, more, or all versions to another release.
+    remove (uninstall)  Remove/uninstall one, more, or all versions.
     list                List installed versions and show which have an update
                         available.
     show                Show versions available from a release.
     path                Show path prefix to installed version base directory.
 
-Note you can set default starting global options in
-$HOME/.config/pystand-flags.conf.
+Some commands offer aliases as shown in brackets above. Note you can set
+default starting global options in $HOME/.config/pystand-flags.conf.
 ```
 
 Type `pystand <command> -h` to see specific help/usage for any
@@ -167,7 +167,7 @@ individual command:
 ### Command `install`
 
 ```
-usage: pystand install [-h] [-r RELEASE] [-f] version [version ...]
+usage: pystand install [-h] [-r RELEASE] [-f] [-s] version [version ...]
 
 Install one or more versions from a python-build-standalone release.
 
@@ -181,6 +181,8 @@ options:
                         YYYYMMDD release (e.g. 20240415), default is latest
                         release
   -f, --force           force install even if already installed
+  -s, --include-source  also install source files if available in distribution
+                        download
 ```
 
 ### Command `update`
@@ -203,6 +205,8 @@ options:
                         can be specified with --all)
   -k, --keep            keep old version after updating (but only if different
                         version number)
+
+aliases: upgrade
 ```
 
 ### Command `remove`
@@ -223,6 +227,8 @@ options:
   -r RELEASE, --release RELEASE
                         only remove versions if from specified YYYMMDD release
                         (e.g. 20240415)
+
+aliases: uninstall
 ```
 
 ### Command `list`
@@ -247,18 +253,21 @@ options:
 ### Command `show`
 
 ```
-usage: pystand show [-h] [-a] [release]
+usage: pystand show [-h] [-r RELEASE] [-a] [re_match]
 
 Show versions available from a release.
 
 positional arguments:
-  release     python-build-standalone YYYYMMDD release to show (e.g.
-              20240415), default is latest release
+  re_match              show only versions+distributions matching this regular
+                        expression pattern
 
 options:
-  -h, --help  show this help message and exit
-  -a, --all   also show all available distributions for each version from the
-              release
+  -h, --help            show this help message and exit
+  -r RELEASE, --release RELEASE
+                        python-build-standalone YYYYMMDD release to show (e.g.
+                        20240415), default is latest release
+  -a, --all             show all available distributions for each version from
+                        the release
 ```
 
 ### Command `path`
@@ -303,35 +312,6 @@ To uninstall:
 $ pipx uninstall pystand
 ```
 
-## Installing Other Builds/Distributions
-
-The _`install_only_stripped`_ build of each distribution is installed by
-default. See description of distributions/builds
-[here](https://gregoryszorc.com/docs/python-build-standalone/main/running.html#obtaining-distributions).
-However, you can choose to install other distributions/builds. E.g. If
-we use a standard modern Linux x86_64 machine as an example, the default
-distribution is _`x86_64-unknown-linux-gnu-install_only_stripped`_ and
-the versions for these are installed by default at
-`~/.local/share/pystand/<version>`.
-
-However, let's say you want to experiment with the new free-threaded
-3.13 build, installed to a different directory. E.g.:
-
-```sh
-$ mkdir ./3.13-freethreaded
-$ cd ./3.13-freethreaded
-
-$ pystand -P. -D x86_64-unknown-linux-gnu-freethreaded+lto-full install 3.13
-$ ./3.13/bin/python -V
-Python 3.13.0
-
-$ pystand -P . list
-3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+lto-full"
-```
-
-Note you can set a different default distribution by specifying
-`--distribution` as a [default option](#command-default-options).
-
 ## Extrapolation of Python Versions
 
 For all commands except the `path` command, `pystand` extrapolates
@@ -390,6 +370,150 @@ $ uv venv -p $(pystand path 3.12.2)
 $ uv venv -p $(pystand path -r 3.12)
 ```
 
+## Installing Other Builds/Distributions
+
+The _`install_only_stripped`_ distribution build is installed by default
+for your running machine architecture. See description of
+distributions/builds
+[here](https://gregoryszorc.com/docs/python-build-standalone/main/running.html#obtaining-distributions).
+However, you can choose to install other distributions/builds (even for
+other architectures). E.g. If we use a standard modern Linux x86_64
+machine as an example, the default distribution is
+_`x86_64-unknown-linux-gnu-install_only_stripped`_ and the versions for
+these are installed by default at `~/.local/share/pystand/<version>`.
+
+However, let's say you want to experiment with the new free-threaded
+3.13 build, installed to a different directory. E.g.:
+
+```sh
+$ mkdir ./3.13-freethreaded
+$ cd ./3.13-freethreaded
+
+$ pystand -P. -D x86_64-unknown-linux-gnu-freethreaded+lto-full install 3.13
+$ ./3.13/bin/python -V
+Python 3.13.0
+
+$ pystand -P . list
+3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+lto-full"
+```
+
+Note you can set a different default distribution by specifying
+`--distribution` as a [default option](#command-default-options).
+
+### Searching for Available Versions and Distributions
+
+The `show` command can be used to search for distributions as seen in the
+following examples.
+
+```sh
+
+List all the versions installed on this system (at the default location):
+
+```sh
+$ pystand list
+3.8.20 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.9.20 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+```
+
+The above shows versions 3.9, 3.12, and 3.13 are installed from the latest
+release 20241016. Version 3.8 is installed from the previous release
+20241002 (and is not available in the latest release otherwise it would
+be shown with an update message).
+
+Now show all available versions from the latest release:
+
+```sh
+$ pystand show
+3.9.20 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.10.15 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.11.10 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+```
+
+We can see that versions 3.9, 3.12, and 3.13 are already installed (as
+we also knew from list output), and that 3.10 and 3.11 are also available.
+
+What is available from the previous release 20241002?
+
+```sh
+$ pystand show -r 20241002
+3.8.20 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.9.20 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.10.15 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.11.10 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.13.0rc3 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+```
+
+Let's install one of the threaded builds of Python 3.13. We can use the
+`-a/-all` option to show all available distributions and then give the
+`show` command a [regular
+expression](https://en.wikipedia.org/wiki/Regular_expression) to filter
+the output (this is really just a shorthand for piping the output of
+`show -a` to grep). E.g.:
+
+```sh
+$ pystand show -a 3.13.*x86_64.*unknown-linux-gnu.*thread
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-freethreaded+debug-full"
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-freethreaded+pgo+lto-full"
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-freethreaded+pgo-full"
+3.13.0 @ 20241016 distribution="x86_64_v2-unknown-linux-gnu-freethreaded+debug-full"
+3.13.0 @ 20241016 distribution="x86_64_v2-unknown-linux-gnu-freethreaded+pgo+lto-full"
+3.13.0 @ 20241016 distribution="x86_64_v2-unknown-linux-gnu-freethreaded+pgo-full"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+debug-full"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+pgo-full"
+3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+debug-full"
+3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+lto-full"
+3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+noopt-full"
+```
+
+So let's install the
+`x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full` build of Python
+3.13 (to the default location):
+
+```sh
+$ pystand -D x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full install 3.13
+Version "3.13.0" is already installed.
+```
+
+An error is given because the version is already installed. We can
+overwrite that with the `-f/--force` option:
+
+```sh
+$ pystand -D x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full install -f 3.13
+Version 3.13.0 @ 20241016 installed.
+```
+
+Now we can see the new version distribution is installed:
+
+```sh
+
+$ pystand list
+3.8.20 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.9.20 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full"
+
+$ pystand show
+3.9.20 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.10.15 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.11.10 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full" (installed)
+```
+
+Note that `pystand` caches all downloaded files (at least for a period
+specified by `--purge-days`) so you can easily switch between different
+versions/distributions quite quickly. You can also choose to install any
+distribution/build in a specific directory using the `-P/--prefix-dir`
+global option if you want to keep different distributions separate and
+available in parallel.
+
 ## Command Default Options
 
 You can add default global options to a personal configuration file
@@ -406,11 +530,11 @@ as defaults.
 
 ## Github API Rate Limiting
 
-This tool minimises and caches Github API responses from the
-[`python-build-standalone`][pbs] repository. However, if you install
-many different versions particularly across various releases, you may
-get rate limited by Github so the command will block and you will see
-"backoff" messages reported. You can create a Github access token to
+This tool minimises and caches Github API responses and file downloads
+from the [`python-build-standalone`][pbs] repository. However, if you
+install many different versions particularly across various releases,
+you may get rate limited by Github so the command can block and you will
+see "backoff" messages reported. You can create a Github access token to
 gain increased rate limits. Create a token in your Github account under
 `Settings -> Developer settings -> Personal access tokens`. Specify the
 token on the command line with `--github-access-token`, or set that as a

{pystand-2.3 → pystand-2.5/pystand.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pystand
-Version: 2.3
+Version: 2.5
 Summary: Install Python versions from python-build-standalone project
 Author-email: Mark Blakeney <mark.blakeney@bullet-systems.net>
 License: GPLv3
@@ -131,7 +131,7 @@ usage: pystand [-h] [-D DISTRIBUTION] [-P PREFIX_DIR] [-C CACHE_DIR]
                   [-M CACHE_MINUTES] [--purge-days PURGE_DAYS]
                   [--github-access-token GITHUB_ACCESS_TOKEN] [--no-strip]
                   [-V]
-                  {install,update,remove,list,show,path} ...
+                  {install,update,upgrade,remove,uninstall,list,show,path} ...
 
 Command line tool to download, install, and update pre-built Python versions
 from the python-build-standalone project at
@@ -140,9 +140,9 @@ https://github.com/indygreg/python-build-standalone.
 options:
   -h, --help            show this help message and exit
   -D DISTRIBUTION, --distribution DISTRIBUTION
-                        python-build-standalone distribution. Default is auto-
-                        detected (detected as "x86_64-unknown-linux-gnu-
-                        install_only_stripped" for this current host).
+                        python-build-standalone distribution. Default is
+                        "x86_64-unknown-linux-gnu-install_only_stripped" for
+                        this host.
   -P PREFIX_DIR, --prefix-dir PREFIX_DIR
                         specify prefix dir for storing versions. Default is
                         "$HOME/.local/share/pystand"
@@ -164,18 +164,18 @@ options:
   -V, --version         just show pystand version
 
 Commands:
-  {install,update,remove,list,show,path}
+  {install,update,upgrade,remove,uninstall,list,show,path}
     install             Install one or more versions from a python-build-
                         standalone release.
-    update              Update one, more, or all versions to another release.
-    remove              Remove/uninstall one, more, or all versions.
+    update (upgrade)    Update one, more, or all versions to another release.
+    remove (uninstall)  Remove/uninstall one, more, or all versions.
     list                List installed versions and show which have an update
                         available.
     show                Show versions available from a release.
     path                Show path prefix to installed version base directory.
 
-Note you can set default starting global options in
-$HOME/.config/pystand-flags.conf.
+Some commands offer aliases as shown in brackets above. Note you can set
+default starting global options in $HOME/.config/pystand-flags.conf.
 ```
 
 Type `pystand <command> -h` to see specific help/usage for any
@@ -184,7 +184,7 @@ individual command:
 ### Command `install`
 
 ```
-usage: pystand install [-h] [-r RELEASE] [-f] version [version ...]
+usage: pystand install [-h] [-r RELEASE] [-f] [-s] version [version ...]
 
 Install one or more versions from a python-build-standalone release.
 
@@ -198,6 +198,8 @@ options:
                         YYYYMMDD release (e.g. 20240415), default is latest
                         release
   -f, --force           force install even if already installed
+  -s, --include-source  also install source files if available in distribution
+                        download
 ```
 
 ### Command `update`
@@ -220,6 +222,8 @@ options:
                         can be specified with --all)
   -k, --keep            keep old version after updating (but only if different
                         version number)
+
+aliases: upgrade
 ```
 
 ### Command `remove`
@@ -240,6 +244,8 @@ options:
   -r RELEASE, --release RELEASE
                         only remove versions if from specified YYYMMDD release
                         (e.g. 20240415)
+
+aliases: uninstall
 ```
 
 ### Command `list`
@@ -264,18 +270,21 @@ options:
 ### Command `show`
 
 ```
-usage: pystand show [-h] [-a] [release]
+usage: pystand show [-h] [-r RELEASE] [-a] [re_match]
 
 Show versions available from a release.
 
 positional arguments:
-  release     python-build-standalone YYYYMMDD release to show (e.g.
-              20240415), default is latest release
+  re_match              show only versions+distributions matching this regular
+                        expression pattern
 
 options:
-  -h, --help  show this help message and exit
-  -a, --all   also show all available distributions for each version from the
-              release
+  -h, --help            show this help message and exit
+  -r RELEASE, --release RELEASE
+                        python-build-standalone YYYYMMDD release to show (e.g.
+                        20240415), default is latest release
+  -a, --all             show all available distributions for each version from
+                        the release
 ```
 
 ### Command `path`
@@ -320,35 +329,6 @@ To uninstall:
 $ pipx uninstall pystand
 ```
 
-## Installing Other Builds/Distributions
-
-The _`install_only_stripped`_ build of each distribution is installed by
-default. See description of distributions/builds
-[here](https://gregoryszorc.com/docs/python-build-standalone/main/running.html#obtaining-distributions).
-However, you can choose to install other distributions/builds. E.g. If
-we use a standard modern Linux x86_64 machine as an example, the default
-distribution is _`x86_64-unknown-linux-gnu-install_only_stripped`_ and
-the versions for these are installed by default at
-`~/.local/share/pystand/<version>`.
-
-However, let's say you want to experiment with the new free-threaded
-3.13 build, installed to a different directory. E.g.:
-
-```sh
-$ mkdir ./3.13-freethreaded
-$ cd ./3.13-freethreaded
-
-$ pystand -P. -D x86_64-unknown-linux-gnu-freethreaded+lto-full install 3.13
-$ ./3.13/bin/python -V
-Python 3.13.0
-
-$ pystand -P . list
-3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+lto-full"
-```
-
-Note you can set a different default distribution by specifying
-`--distribution` as a [default option](#command-default-options).
-
 ## Extrapolation of Python Versions
 
 For all commands except the `path` command, `pystand` extrapolates
@@ -407,6 +387,150 @@ $ uv venv -p $(pystand path 3.12.2)
 $ uv venv -p $(pystand path -r 3.12)
 ```
 
+## Installing Other Builds/Distributions
+
+The _`install_only_stripped`_ distribution build is installed by default
+for your running machine architecture. See description of
+distributions/builds
+[here](https://gregoryszorc.com/docs/python-build-standalone/main/running.html#obtaining-distributions).
+However, you can choose to install other distributions/builds (even for
+other architectures). E.g. If we use a standard modern Linux x86_64
+machine as an example, the default distribution is
+_`x86_64-unknown-linux-gnu-install_only_stripped`_ and the versions for
+these are installed by default at `~/.local/share/pystand/<version>`.
+
+However, let's say you want to experiment with the new free-threaded
+3.13 build, installed to a different directory. E.g.:
+
+```sh
+$ mkdir ./3.13-freethreaded
+$ cd ./3.13-freethreaded
+
+$ pystand -P. -D x86_64-unknown-linux-gnu-freethreaded+lto-full install 3.13
+$ ./3.13/bin/python -V
+Python 3.13.0
+
+$ pystand -P . list
+3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+lto-full"
+```
+
+Note you can set a different default distribution by specifying
+`--distribution` as a [default option](#command-default-options).
+
+### Searching for Available Versions and Distributions
+
+The `show` command can be used to search for distributions as seen in the
+following examples.
+
+```sh
+
+List all the versions installed on this system (at the default location):
+
+```sh
+$ pystand list
+3.8.20 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.9.20 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+```
+
+The above shows versions 3.9, 3.12, and 3.13 are installed from the latest
+release 20241016. Version 3.8 is installed from the previous release
+20241002 (and is not available in the latest release otherwise it would
+be shown with an update message).
+
+Now show all available versions from the latest release:
+
+```sh
+$ pystand show
+3.9.20 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.10.15 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.11.10 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+```
+
+We can see that versions 3.9, 3.12, and 3.13 are already installed (as
+we also knew from list output), and that 3.10 and 3.11 are also available.
+
+What is available from the previous release 20241002?
+
+```sh
+$ pystand show -r 20241002
+3.8.20 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.9.20 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.10.15 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.11.10 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.13.0rc3 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+```
+
+Let's install one of the threaded builds of Python 3.13. We can use the
+`-a/-all` option to show all available distributions and then give the
+`show` command a [regular
+expression](https://en.wikipedia.org/wiki/Regular_expression) to filter
+the output (this is really just a shorthand for piping the output of
+`show -a` to grep). E.g.:
+
+```sh
+$ pystand show -a 3.13.*x86_64.*unknown-linux-gnu.*thread
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-freethreaded+debug-full"
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-freethreaded+pgo+lto-full"
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-freethreaded+pgo-full"
+3.13.0 @ 20241016 distribution="x86_64_v2-unknown-linux-gnu-freethreaded+debug-full"
+3.13.0 @ 20241016 distribution="x86_64_v2-unknown-linux-gnu-freethreaded+pgo+lto-full"
+3.13.0 @ 20241016 distribution="x86_64_v2-unknown-linux-gnu-freethreaded+pgo-full"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+debug-full"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+pgo-full"
+3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+debug-full"
+3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+lto-full"
+3.13.0 @ 20241016 distribution="x86_64_v4-unknown-linux-gnu-freethreaded+noopt-full"
+```
+
+So let's install the
+`x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full` build of Python
+3.13 (to the default location):
+
+```sh
+$ pystand -D x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full install 3.13
+Version "3.13.0" is already installed.
+```
+
+An error is given because the version is already installed. We can
+overwrite that with the `-f/--force` option:
+
+```sh
+$ pystand -D x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full install -f 3.13
+Version 3.13.0 @ 20241016 installed.
+```
+
+Now we can see the new version distribution is installed:
+
+```sh
+
+$ pystand list
+3.8.20 @ 20241002 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.9.20 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full"
+
+$ pystand show
+3.9.20 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.10.15 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.11.10 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.12.7 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped" (installed)
+3.13.0 @ 20241016 distribution="x86_64-unknown-linux-gnu-install_only_stripped"
+3.13.0 @ 20241016 distribution="x86_64_v3-unknown-linux-gnu-freethreaded+pgo+lto-full" (installed)
+```
+
+Note that `pystand` caches all downloaded files (at least for a period
+specified by `--purge-days`) so you can easily switch between different
+versions/distributions quite quickly. You can also choose to install any
+distribution/build in a specific directory using the `-P/--prefix-dir`
+global option if you want to keep different distributions separate and
+available in parallel.
+
 ## Command Default Options
 
 You can add default global options to a personal configuration file
@@ -423,11 +547,11 @@ as defaults.
 
 ## Github API Rate Limiting
 
-This tool minimises and caches Github API responses from the
-[`python-build-standalone`][pbs] repository. However, if you install
-many different versions particularly across various releases, you may
-get rate limited by Github so the command will block and you will see
-"backoff" messages reported. You can create a Github access token to
+This tool minimises and caches Github API responses and file downloads
+from the [`python-build-standalone`][pbs] repository. However, if you
+install many different versions particularly across various releases,
+you may get rate limited by Github so the command can block and you will
+see "backoff" messages reported. You can create a Github access token to
 gain increased rate limits. Create a token in your Github account under
 `Settings -> Developer settings -> Personal access tokens`. Specify the
 token on the command line with `--github-access-token`, or set that as a

{pystand-2.3 → pystand-2.5}/pystand.py

@@ -163,9 +163,19 @@ def fetch(args: Namespace, release: str, url: str, tdir: Path) -> str | None:
         except Exception as e:
             error = f'Failed to unpack "{url}": {e}'
         else:
-            pdir = tmpdir / 'python' / 'install'
-            if not pdir.exists():
-                pdir = pdir.parent
+            pdir = tmpdir / 'python'
+            idir = pdir / 'install'
+            if idir.exists():
+                # This is a source distribution, copy the source if
+                # requested
+                if args.include_source:
+                    srcdir = idir / 'src'
+                    for subpath in pdir.iterdir():
+                        if subpath.name != idir.name:
+                            srcdir.mkdir(parents=True, exist_ok=True)
+                            subpath.replace(srcdir / subpath.name)
+
+                pdir = idir
 
             pdir.replace(tdir)
 
@@ -523,14 +533,15 @@ def main() -> str | None:
 
     # Parse arguments
     opt = ArgumentParser(description=__doc__,
-              epilog='Note you can set default starting global options '
-                         f'in {CNFFILE}.')
+            epilog='Some commands offer aliases as shown in brackets above. '
+                'Note you can set default starting global options in '
+                f'{CNFFILE}.')
 
     # Set up main/global arguments
     opt.add_argument('-D', '--distribution',
                      help=f'{REPO} distribution. '
-                     f'Default is auto-detected (detected as "{distro_help}" '
-                     'for this current host).')
+                     f'Default is "{distro_help}" '
+                     'for this host.')
     opt.add_argument('-P', '--prefix-dir', default=prefix_dir,
                      help='specify prefix dir for storing '
                      'versions. Default is "%(default)s"')
@@ -565,8 +576,10 @@ def main() -> str | None:
         else:
             return f'Must define a docstring for command class "{name}".'
 
+        aliases = cls.aliases if hasattr(cls, 'aliases') else []
         title = get_title(desc)
-        cmdopt = cmd.add_parser(name, description=desc, help=title)
+        cmdopt = cmd.add_parser(name, description=desc, help=title,
+                                aliases=aliases)
 
         # Set up this commands own arguments, if it has any
         if hasattr(cls, 'init'):
@@ -636,6 +649,9 @@ class _install(COMMAND):
                             'default is latest release')
         parser.add_argument('-f', '--force', action='store_true',
                             help='force install even if already installed')
+        parser.add_argument('-s', '--include-source', action='store_true',
+                            help='also install source files if available in '
+                            'distribution download')
         parser.add_argument('version', nargs='+',
                             help='version to install. E.g. 3.12 or 3.12.3')
 
@@ -666,6 +682,8 @@ class _install(COMMAND):
 @COMMAND.add
 class _update(COMMAND):
     'Update one, more, or all versions to another release.'
+    aliases = ['upgrade']
+
     @staticmethod
     def init(parser: ArgumentParser) -> None:
         parser.add_argument('-r', '--release',
@@ -692,7 +710,8 @@ class _update(COMMAND):
 
         matcher = VersionMatcher(files)
         for version in get_version_names(args):
-            if not (data := get_json(args._versions / version / args._data)):
+            vdir = args._versions / version
+            if not (data := get_json(vdir / args._data)):
                 continue
 
             if (release := data.get('release')) == release_target:
@@ -719,6 +738,10 @@ class _update(COMMAND):
                   f'{fmt(nextver, release_target)} '
                   f'distribution="{distribution}" ..')
 
+            # If the source was originally included, then include it in
+            # the update.
+            args.include_source = (vdir / 'src').is_dir()
+
             if error := install(args, new_vdir, release_target, distribution,
                                 files):
                 return error
@@ -729,6 +752,8 @@ class _update(COMMAND):
 @COMMAND.add
 class _remove(COMMAND):
     'Remove/uninstall one, more, or all versions.'
+    aliases = ['uninstall']
+
     @staticmethod
     def init(parser: ArgumentParser) -> None:
         parser.add_argument('-a', '--all', action='store_true',
@@ -827,12 +852,15 @@ class _show(COMMAND):
     'Show versions available from a release.'
     @staticmethod
     def init(parser: ArgumentParser) -> None:
-        parser.add_argument('-a', '--all', action='store_true',
-                            help='also show all available distributions for '
-                            'each version from the release')
-        parser.add_argument('release', nargs='?',
+        parser.add_argument('-r', '--release',
                             help=f'{REPO} YYYYMMDD release to show (e.g. '
                             f'{SAMPL_RELEASE}), default is latest release')
+        parser.add_argument('-a', '--all', action='store_true',
+                            help='show all available distributions for '
+                            'each version from the release')
+        parser.add_argument('re_match', nargs='?',
+                            help='show only versions+distributions '
+                            'matching this regular expression pattern')
 
     @staticmethod
     def run(args: Namespace) -> None:
@@ -859,8 +887,11 @@ class _show(COMMAND):
                     if distribution == args._distribution:
                         installable = True
 
-                    print(f'{fmt(version, release)} '
-                          f'distribution="{distribution}"{app}')
+                    if not args.re_match or \
+                            re.search(args.re_match,
+                                      f'{version}+{distribution}'):
+                        print(f'{fmt(version, release)} '
+                            f'distribution="{distribution}"{app}')
         if not installable:
             print(f'Warning: no distribution="{args._distribution}" '
                   'versions found in ' f'release "{release}".')