pystand 2.2__py3-none-any.whl → 2.4__py3-none-any.whl

{pystand-2.2.dist-info → pystand-2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pystand
-Version: 2.2
+Version: 2.4
 Summary: Install Python versions from python-build-standalone project
 Author-email: Mark Blakeney <mark.blakeney@bullet-systems.net>
 License: GPLv3
@@ -92,16 +92,16 @@ Here are some examples showing how to use an installed version ..
 
 ```sh
 # Use uv to create a virtual environment to be run with latest pystand
-# installed python:
-$ uv venv -p $(pystand path) myenv
+# installed python 3.12:
+$ uv venv -p $(pystand path 3.12) myenv
 
 # Create a regular virtual environment to be run with latest pystand
-# installed python:
-$ $(pystand path -p) -m venv myenv
+# installed python 3.12:
+$ $(pystand path -p 3.12) -m venv myenv
 
 # Use pipx to install a package to be run with pystand installed python
-# specific version:
-$ pipx install --python $(pystand path -p 3.11) cowsay
+# specific version 3.11.1:
+$ pipx install --python $(pystand path -p 3.11.1) cowsay
 ```
 
 See detailed usage information in the [Usage](#usage) section that
@@ -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"
@@ -264,34 +264,38 @@ 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`
 
 ```
-usage: pystand path [-h] [-p] [-c | version]
+usage: pystand path [-h] [-p] [-r] [-c | version]
 
 Show path prefix to installed version base directory.
 
 positional arguments:
-  version             print resolved path for specified version
+  version            version number to show path for
 
 options:
-  -h, --help          show this help message and exit
-  -p, --python-path   show full path to python executable
-  -c, --cache-prefix  print path to cache dir
+  -h, --help         show this help message and exit
+  -p, --python-path  add path to python executable
+  -r, --resolve      fully resolve given version
+  -c, --cache-path   just show path to cache dir
 ```
 
 ## Installation and Upgrade
@@ -319,19 +323,78 @@ To uninstall:
 $ pipx uninstall pystand
 ```
 
+## Extrapolation of Python Versions
+
+For all commands except the `path` command, `pystand` extrapolates
+version text you specify on the command line to the latest available
+corresponding installed or release version. For example, if you specify
+`pystand install 3.12` then `pystand` will look in the release files to
+find the latest (i.e. highest) available version of `3.12`, e.g.
+`3.12.3` (at the time of writing), and will install that. Of course you
+can specify the exact version if you wish, e.g. `3.12.3` but generally
+you don't need to bother. This is true for any command that takes a
+version argument so be aware that this may be confusing if there are
+multiple same Python minor versions, e.g. `3.12.1` and `3.12.3`,
+installed from different releases. So in that case you should specify
+the exact version because e.g. `pystand remove 3.12` will remove
+`3.12.3` which may not be what you want.
+
+Note, consistent with this, you actually don't need to specify a
+minor version, e.g. `pystand install 3` would also install `3.12.3`
+(assuming `3.12.3` is the latest available version for Python 3).
+
+After installs or updates or removals,`pystand` also maintains symbolic
+links to each latest installed version in it's version directory, e.g. a
+symlink `~/.local/share/pystand/versions/3.12` will be created pointing
+to `~/.local/share/pystand/versions/3.12.3` so that you can optionally
+hard code the symlink directory in places where it can not be set
+dynamically (i.e. where using `pystand path` is not an option).
+
+You can exploit these symlinks when you create virtual environments
+using the `pystand path` command (or just hard code the actual link/path
+for your environment/platform). E.g. The following creates a virtual
+environment which runs with whatever the currently latest installed
+Python 3.12 version is:
+
+```sh
+# Use uv to create a virtual environment to be run with a symlink to
+# currently latest installed python 3.12:
+$ uv venv -p $(pystand path 3.12)
+```
+
+So if you then update to a new version of Python 3.12 using `pystand`,
+e.g. from 3.12.3 to 3.12.4, the virtual environment will automatically
+use the new Python version. However, if you for some reason want to
+create the virtual environment with a specific version of Python that is
+never changed, then just specify that exact version when you create the
+virtual environment, e.g.:
+
+```sh
+# Use uv to create a virtual environment to be run with specific pystand
+# installed python 3.12.2:
+$ uv venv -p $(pystand path 3.12.2)
+
+# If you can't be bothered to look up the current latest version, then
+# the following command will do the same thing as above because it
+# resolves the symlink to the current latest 3.12 version at the time
+# you run this command:
+$ uv venv -p $(pystand path -r 3.12)
+```
+
 ## Installing Other Builds/Distributions
 
-The _`install_only_stripped`_ build of each distribution is installed by
-default. See description of distributions/builds
+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. 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, 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. You can install this to a different directory, e.g.
+3.13 build, installed to a different directory. E.g.:
 
 ```sh
 $ mkdir ./3.13-freethreaded
@@ -345,35 +408,122 @@ $ 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).
+Note you can set a different default distribution by specifying
+`--distribution` as a [default option](#command-default-options).
 
-## Extrapolation of Python Versions
+### Searching for Available Versions and Distributions
 
-`pystand` extrapolates any version text you specify on the command line
-to the latest available corresponding installed or release version. For
-example, if you specify `pystand install 3.12` then `pystand` will look
-in the release files to find the latest (i.e. highest) available version
-of `3.12`, e.g. `3.12.3` (at the time of writing), and will install
-that. Of course you can specify the exact version if you wish, e.g.
-`3.12.3` but generally you don't need to bother. This is true for any
-command that takes a version argument so be aware that this may be
-confusing if there are multiple same Python minor versions, e.g.
-`3.12.1` and `3.12.3`, installed from different releases. So in that
-case you should specify the exact version because e.g. `pystand remove
-3.12` will remove `3.12.3` which may not be what you want.
+The `show` command can be used to search for distributions as seen in the
+following examples.
 
-Note, consistent with this, you actually don't need to specify a
-minor version, e.g. `pystand install 3` would also install `3.12.3`
-(assuming `3.12.3` is the latest available version for Python 3).
+```sh
 
-After installs or updates or removals,`pystand` also maintains symbolic
-links to each latest installed version in it's version directory, e.g. a
-symlink `~/.local/share/pystand/versions/3.12` will be created pointing
-to `~/.local/share/pystand/versions/3.12.3` so that you can optionally
-hard code the symlink directory in places where it can not be set
-dynamically (i.e. where using `pystand path` is not an option).
+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
 
@@ -391,11 +541,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.4.dist-info/RECORD

@@ -0,0 +1,6 @@
+pystand.py,sha256=DGbYpdOu54cMuasq0hpcSfhn8vNhT-dDll4Xx6Xx628,33340
+pystand-2.4.dist-info/METADATA,sha256=GdWm913Z7KD50Wq7gsHPR5COHU1fZhSuONSYFBf_H5c,24353
+pystand-2.4.dist-info/WHEEL,sha256=R06PA3UVYHThwHvxuRWMqaGcr-PuniXahwjmQRFMEkY,91
+pystand-2.4.dist-info/entry_points.txt,sha256=DG4ps3I3nni1bubV1tXs6u8FARgkdbAYaEAzZD4RAo8,41
+pystand-2.4.dist-info/top_level.txt,sha256=NoWUh19UQymAJLHTCdxMnVwV6Teftef5fzyF3OWLyNY,8
+pystand-2.4.dist-info/RECORD,,

pystand.py

@@ -529,8 +529,8 @@ def main() -> str | None:
     # 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"')
@@ -827,12 +827,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 +862,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}".')
@@ -871,47 +877,40 @@ class _path(COMMAND):
     @staticmethod
     def init(parser: ArgumentParser) -> None:
         parser.add_argument('-p', '--python-path', action='store_true',
-                            help='show full path to python executable')
+                            help='add path to python executable')
+        parser.add_argument('-r', '--resolve', action='store_true',
+                            help='fully resolve given version')
         group = parser.add_mutually_exclusive_group()
-        group.add_argument('-c', '--cache-prefix', action='store_true',
-                           help='print path to cache dir')
+        group.add_argument('-c', '--cache-path', action='store_true',
+                           help='just show path to cache dir')
         group.add_argument('version', nargs='?',
-                           help='print resolved path for specified version')
+                           help='version number to show path for')
 
     @staticmethod
     def run(args: Namespace) -> str | None:
-        if args.cache_prefix:
+        version = args.version
+        if args.cache_path or not version:
             if args.python_path:
                 args.parser.error('Can not specify --python-path.')
-            print(args._downloads.parent)
-            return
 
-        if not args.version:
-            if args.python_path:
-                args.parser.error('Can not specify --python-path.')
-            print(args._versions)
-            return
+            print(args._downloads.parent if args.cache_path else args._versions)
+        else:
+            path = args._versions / version
+            if not path.is_symlink() or not path.exists():
+                return f'Version "{version}" is not installed.'
 
-        matcher = VersionMatcher([f.name for f in iter_versions(args)])
-        version = matcher.match(args.version)
-        if not version:
-            return 'No Python version installed.'
+            if args.resolve:
+                path = path.resolve()
 
-        path = args._versions / version
-        if not path.is_dir():
-            return f'Version "{version}" is not installed.'
+            if args.python_path:
+                basepath = path
+                path = basepath / 'bin' / 'python'
+                if not path.exists():
+                    path = basepath / 'python.exe'
+                    if not path.exists():
+                        return 'Error: Can not find python executable in '\
+                                f'"{basepath}"'
 
-        if args.python_path:
-            subpath = path / 'bin' / 'python'
-            if subpath.exists():
-                print(subpath)
-            else:
-                subpath = path / 'python.exe'
-                if subpath.exists():
-                    print(subpath)
-                else:
-                    return f'Error: Can not find python executable in "{path}"'
-        else:
             print(path)
 
 if __name__ == '__main__':

pystand-2.2.dist-info/RECORD

@@ -1,6 +0,0 @@
-pystand.py,sha256=tOQ4SxeqAtz3Tc-kd9jt_v-Hbx_vXnatHPkT5f1pdAA,33114
-pystand-2.2.dist-info/METADATA,sha256=45hYFkXnngYMEDtsQ_lciU38qxK-Jl98ZxXyjvhhd2I,17403
-pystand-2.2.dist-info/WHEEL,sha256=R06PA3UVYHThwHvxuRWMqaGcr-PuniXahwjmQRFMEkY,91
-pystand-2.2.dist-info/entry_points.txt,sha256=DG4ps3I3nni1bubV1tXs6u8FARgkdbAYaEAzZD4RAo8,41
-pystand-2.2.dist-info/top_level.txt,sha256=NoWUh19UQymAJLHTCdxMnVwV6Teftef5fzyF3OWLyNY,8
-pystand-2.2.dist-info/RECORD,,