pystand 1.8__tar.gz → 1.10__tar.gz

{pystand-1.8/pystand.egg-info → pystand-1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pystand
-Version: 1.8
+Version: 1.10
 Summary: Install Python versions from python-build-standalone project
 Author-email: Mark Blakeney <mark.blakeney@bullet-systems.net>
 License: GPLv3
@@ -86,14 +86,17 @@ $ pystand list
 Here are some examples showing how to use an installed version ..
 
 ```sh
-# Use uv to create a virtual environment to be run with pystand installed python:
-$ uv venv -p $(pystand path 3.12) myenv
+# Use uv to create a virtual environment to be run with latest pystand
+# installed python:
+$ uv venv -p $(pystand path) myenv
 
-# Create a regular virtual environment to be run with pystand installed python:
-$ $(pystand path -p 3.12) -m venv myenv
+# Create a regular virtual environment to be run with latest pystand
+# installed python:
+$ $(pystand path -p) -m venv myenv
 
-# Use pipx to install a package to be run with pystand installed python:
-$ pipx install --python $(pystand path -p 3.12) cowsay
+# Use pipx to install a package to be run with pystand installed python
+# specific version:
+$ pipx install --python $(pystand path -p 3.11) cowsay
 ```
 
 See detailed usage information in the [Usage](#usage) section that
@@ -255,29 +258,30 @@ options:
 ### Command `show`
 
 ```
-usage: pystand show [-h] [-d] [release]
+usage: pystand show [-h] [-D] [release]
 
 Show versions available from a release.
 
 positional arguments:
-  release              python-build-standalone YYYYMMDD release to show (e.g.
-                       20240415), default is latest release
+  release             python-build-standalone YYYYMMDD release to show (e.g.
+                      20240415), default is latest release
 
 options:
-  -h, --help           show this help message and exit
-  -d, --distributions  also show all available distributions for each version
-                       from the release
+  -h, --help          show this help message and exit
+  -D, --distribution  also show all available distributions for each version
+                      from the release
 ```
 
 ### Command `path`
 
 ```
-usage: pystand path [-h] [-p] version
+usage: pystand path [-h] [-p] [version]
 
 Show path prefix to installed version base directory.
 
 positional arguments:
-  version            version to return path for
+  version            version to return path for, or latest release version if
+                     not specified
 
 options:
   -h, --help         show this help message and exit
@@ -291,7 +295,7 @@ from the AUR](https://aur.archlinux.org/packages/pystand) and skip this
 section.
 
 The easiest way to install [`pystand`][pystand] is to use [`pipx`][pipx]
-(or [`pipxu`][pipxu]).
+(or [`pipxu`][pipxu], or [`uv tool`][uvtool]).
 
 ```sh
 $ pipx install pystand
@@ -349,6 +353,18 @@ The global options: `--distribution`, `--base-dir`, `--cache-minutes`,
 `--no-extra-strip` are the only sensible candidates to consider setting
 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
+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
+[default option](#command-default-options).
+
 ## Command Line Tab Completion
 
 Command line shell [tab
@@ -375,6 +391,7 @@ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License at
 [pbs-rel]: https://github.com/indygreg/python-build-standalone/releases
 [pipx]: https://github.com/pypa/pipx
 [pipxu]: https://github.com/bulletmark/pipxu
+[uvtool]: https://docs.astral.sh/uv/guides/tools/#installing-tools
 [pyenv]: https://github.com/pyenv/pyenv
 [pdm]: https://pdm-project.org/
 [pdmpy]: https://pdm-project.org/en/latest/usage/project/#install-python-interpreters-with-pdm

{pystand-1.8 → pystand-1.10}/README.md

@@ -70,14 +70,17 @@ $ pystand list
 Here are some examples showing how to use an installed version ..
 
 ```sh
-# Use uv to create a virtual environment to be run with pystand installed python:
-$ uv venv -p $(pystand path 3.12) myenv
+# Use uv to create a virtual environment to be run with latest pystand
+# installed python:
+$ uv venv -p $(pystand path) myenv
 
-# Create a regular virtual environment to be run with pystand installed python:
-$ $(pystand path -p 3.12) -m venv myenv
+# Create a regular virtual environment to be run with latest pystand
+# installed python:
+$ $(pystand path -p) -m venv myenv
 
-# Use pipx to install a package to be run with pystand installed python:
-$ pipx install --python $(pystand path -p 3.12) cowsay
+# Use pipx to install a package to be run with pystand installed python
+# specific version:
+$ pipx install --python $(pystand path -p 3.11) cowsay
 ```
 
 See detailed usage information in the [Usage](#usage) section that
@@ -239,29 +242,30 @@ options:
 ### Command `show`
 
 ```
-usage: pystand show [-h] [-d] [release]
+usage: pystand show [-h] [-D] [release]
 
 Show versions available from a release.
 
 positional arguments:
-  release              python-build-standalone YYYYMMDD release to show (e.g.
-                       20240415), default is latest release
+  release             python-build-standalone YYYYMMDD release to show (e.g.
+                      20240415), default is latest release
 
 options:
-  -h, --help           show this help message and exit
-  -d, --distributions  also show all available distributions for each version
-                       from the release
+  -h, --help          show this help message and exit
+  -D, --distribution  also show all available distributions for each version
+                      from the release
 ```
 
 ### Command `path`
 
 ```
-usage: pystand path [-h] [-p] version
+usage: pystand path [-h] [-p] [version]
 
 Show path prefix to installed version base directory.
 
 positional arguments:
-  version            version to return path for
+  version            version to return path for, or latest release version if
+                     not specified
 
 options:
   -h, --help         show this help message and exit
@@ -275,7 +279,7 @@ from the AUR](https://aur.archlinux.org/packages/pystand) and skip this
 section.
 
 The easiest way to install [`pystand`][pystand] is to use [`pipx`][pipx]
-(or [`pipxu`][pipxu]).
+(or [`pipxu`][pipxu], or [`uv tool`][uvtool]).
 
 ```sh
 $ pipx install pystand
@@ -333,6 +337,18 @@ The global options: `--distribution`, `--base-dir`, `--cache-minutes`,
 `--no-extra-strip` are the only sensible candidates to consider setting
 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
+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
+[default option](#command-default-options).
+
 ## Command Line Tab Completion
 
 Command line shell [tab
@@ -359,6 +375,7 @@ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License at
 [pbs-rel]: https://github.com/indygreg/python-build-standalone/releases
 [pipx]: https://github.com/pypa/pipx
 [pipxu]: https://github.com/bulletmark/pipxu
+[uvtool]: https://docs.astral.sh/uv/guides/tools/#installing-tools
 [pyenv]: https://github.com/pyenv/pyenv
 [pdm]: https://pdm-project.org/
 [pdmpy]: https://pdm-project.org/en/latest/usage/project/#install-python-interpreters-with-pdm

{pystand-1.8 → pystand-1.10/pystand.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pystand
-Version: 1.8
+Version: 1.10
 Summary: Install Python versions from python-build-standalone project
 Author-email: Mark Blakeney <mark.blakeney@bullet-systems.net>
 License: GPLv3
@@ -86,14 +86,17 @@ $ pystand list
 Here are some examples showing how to use an installed version ..
 
 ```sh
-# Use uv to create a virtual environment to be run with pystand installed python:
-$ uv venv -p $(pystand path 3.12) myenv
+# Use uv to create a virtual environment to be run with latest pystand
+# installed python:
+$ uv venv -p $(pystand path) myenv
 
-# Create a regular virtual environment to be run with pystand installed python:
-$ $(pystand path -p 3.12) -m venv myenv
+# Create a regular virtual environment to be run with latest pystand
+# installed python:
+$ $(pystand path -p) -m venv myenv
 
-# Use pipx to install a package to be run with pystand installed python:
-$ pipx install --python $(pystand path -p 3.12) cowsay
+# Use pipx to install a package to be run with pystand installed python
+# specific version:
+$ pipx install --python $(pystand path -p 3.11) cowsay
 ```
 
 See detailed usage information in the [Usage](#usage) section that
@@ -255,29 +258,30 @@ options:
 ### Command `show`
 
 ```
-usage: pystand show [-h] [-d] [release]
+usage: pystand show [-h] [-D] [release]
 
 Show versions available from a release.
 
 positional arguments:
-  release              python-build-standalone YYYYMMDD release to show (e.g.
-                       20240415), default is latest release
+  release             python-build-standalone YYYYMMDD release to show (e.g.
+                      20240415), default is latest release
 
 options:
-  -h, --help           show this help message and exit
-  -d, --distributions  also show all available distributions for each version
-                       from the release
+  -h, --help          show this help message and exit
+  -D, --distribution  also show all available distributions for each version
+                      from the release
 ```
 
 ### Command `path`
 
 ```
-usage: pystand path [-h] [-p] version
+usage: pystand path [-h] [-p] [version]
 
 Show path prefix to installed version base directory.
 
 positional arguments:
-  version            version to return path for
+  version            version to return path for, or latest release version if
+                     not specified
 
 options:
   -h, --help         show this help message and exit
@@ -291,7 +295,7 @@ from the AUR](https://aur.archlinux.org/packages/pystand) and skip this
 section.
 
 The easiest way to install [`pystand`][pystand] is to use [`pipx`][pipx]
-(or [`pipxu`][pipxu]).
+(or [`pipxu`][pipxu], or [`uv tool`][uvtool]).
 
 ```sh
 $ pipx install pystand
@@ -349,6 +353,18 @@ The global options: `--distribution`, `--base-dir`, `--cache-minutes`,
 `--no-extra-strip` are the only sensible candidates to consider setting
 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
+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
+[default option](#command-default-options).
+
 ## Command Line Tab Completion
 
 Command line shell [tab
@@ -375,6 +391,7 @@ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License at
 [pbs-rel]: https://github.com/indygreg/python-build-standalone/releases
 [pipx]: https://github.com/pypa/pipx
 [pipxu]: https://github.com/bulletmark/pipxu
+[uvtool]: https://docs.astral.sh/uv/guides/tools/#installing-tools
 [pyenv]: https://github.com/pyenv/pyenv
 [pdm]: https://pdm-project.org/
 [pdmpy]: https://pdm-project.org/en/latest/usage/project/#install-python-interpreters-with-pdm

{pystand-1.8 → pystand-1.10}/pystand.py

@@ -21,7 +21,7 @@ from argparse import ArgumentParser, Namespace
 from collections import defaultdict
 from datetime import date
 from pathlib import Path
-from typing import Any, Iterable, Iterator, Optional
+from typing import Any, Iterable, Iterator
 
 import argcomplete
 import platformdirs
@@ -92,7 +92,7 @@ def get_json(file: Path) -> dict:
 
     return {}
 
-def set_json(file: Path, data: dict) -> Optional[str]:
+def set_json(file: Path, data: dict) -> str | None:
     'Set JSON data to given file'
     try:
         with file.open('w') as fp:
@@ -132,26 +132,47 @@ def rm_path(path: Path) -> None:
     elif path.exists():
         path.unlink()
 
+def is_release_version(version: str) -> bool:
+    'Check if a string is a formal Python release tag'
+    return version.replace('.', '').isdigit()
+
 class VersionMatcher:
     'Match a version string to a list of versions'
     def __init__(self, seq: Iterable[str]) -> None:
         self.seq = sorted(seq, key=parse_version, reverse=True)
 
-    def match(self, version: str, *,
-              upconvert_minor: bool = False) -> Optional[str]:
+    def match(self, version: str | None, *,
+              upgrade: bool = False) -> str | None:
         'Return full version string given a [possibly] part version prefix'
+
+        # If no version specified, return the latest release version
+        if not version:
+            for version in self.seq:
+                if is_release_version(version):
+                    return version
+            return None
+
         if version in self.seq:
             return version
 
-        if upconvert_minor:
+        is_release = is_release_version(version)
+        major_only = '.' not in version
+
+        if major_only:
+            upgrade = True
+        elif upgrade:
             version = version.rsplit('.', 1)[0]
 
         if not version.endswith('.'):
             version += '.'
 
+        # Only allow upgrade of formal release to another formal
+        # release, or alpha/beta release to another alpha/beta release.
         for full_version in self.seq:
             if full_version.startswith(version):
-                return full_version
+                if not upgrade \
+                        or is_release_version(full_version) == is_release:
+                    return full_version
 
         return None
 
@@ -191,7 +212,7 @@ def get_version_names(args: Namespace) -> list[str]:
             if args.all else versions
 
 def check_release_tag(release: str, *,
-                      check_first: bool = True) -> Optional[str]:
+                      check_first: bool = True) -> str | None:
     'Check the specified release tag is valid'
     if not release.isdigit() or len(release) != len(FIRST_RELEASE):
         return 'Release must be a YYYYMMDD string.'
@@ -253,7 +274,7 @@ def merge(files: dict, name: str, url: str, stripped: bool) -> None:
     else:
         files[impl][ver][distrib] = ('', url) if stripped else url
 
-def get_release_files(args, tag, implementation: Optional[str] = None) -> dict:
+def get_release_files(args, tag, implementation: str | None = None) -> dict:
     'Return the release files for the given tag'
     # Look for tag data in our release cache
     jfile = args._releases / tag
@@ -295,7 +316,7 @@ def update_version_symlinks(args: Namespace) -> None:
     if not base.exists():
         return
 
-    # Record of all the existing symlinks and version dirs
+    # Record all the existing symlinks and version dirs
     oldlinks = {}
     vers = []
     for path in base.iterdir():
@@ -303,19 +324,30 @@ def update_version_symlinks(args: Namespace) -> None:
             if path.is_symlink():
                 oldlinks[path.name] = os.readlink(str(path))
             else:
-                vers.append(path)
+                vers.append(path.name)
 
     # Create a map of all the new major version links
-    newlinks_all = defaultdict(list)
-    for path in vers:
-        namevers = path.name
+    newlinks_all = defaultdict(set)
+    pre_releases = set(v for v in vers if not is_release_version(v))
+    for namevers in vers:
         while '.' in namevers[:-1]:
             namevers_major = namevers.rsplit('.', maxsplit=1)[0]
-            newlinks_all[namevers_major].append(namevers)
+            newlinks_all[namevers_major].add(namevers)
+
+            if namevers in pre_releases:
+                pre_releases.add(namevers_major)
+
             namevers = namevers_major
 
-    newlinks = {k: sorted(v, key=parse_version)[-1] for k, v in
-                newlinks_all.items()}
+    # Find the latest version for each major version, but ensure we
+    # don't link a major release to pre-released version, if it also can
+    # point to released versions.
+    newlinks = {}
+    for ver, cands in newlinks_all.items():
+        if ver in pre_releases and (rels := (cands - pre_releases)):
+            cands = rels
+
+        newlinks[ver] = sorted(cands, key=parse_version)[-1]
 
     # Remove all old or invalid existing links
     for name, tgt in oldlinks.items():
@@ -403,7 +435,7 @@ def strip_binaries(vdir: Path, distribution: str) -> bool:
     return was_stripped
 
 def install(args: Namespace, vdir: Path, release: str, distribution: str,
-            files: dict) -> Optional[str]:
+            files: dict) -> str | None:
     'Install a version'
     version = vdir.name
 
@@ -460,7 +492,7 @@ def install(args: Namespace, vdir: Path, release: str, distribution: str,
     shutil.rmtree(tmpdir)
     return error
 
-def main() -> Optional[str]:
+def main() -> str | None:
     'Main code'
     distro_default = DISTRIBUTIONS.get((platform.system(), platform.machine()))
     distro_help = distro_default or '?unknown?'
@@ -583,7 +615,7 @@ class _install(COMMAND):
                             help='version to install. E.g. 3.12 or 3.12.3')
 
     @staticmethod
-    def run(args: Namespace) -> Optional[str]:
+    def run(args: Namespace) -> str | None:
         release = get_release_tag(args)
         files = get_release_files(args, release, 'cpython')
         if not files:
@@ -627,7 +659,7 @@ class _update(COMMAND):
                             '--all --skip)')
 
     @staticmethod
-    def run(args: Namespace) -> Optional[str]:
+    def run(args: Namespace) -> str | None:
         release_target = get_release_tag(args)
         files = get_release_files(args, release_target, 'cpython')
         if not files:
@@ -642,7 +674,7 @@ class _update(COMMAND):
             if release == release_target:
                 continue
 
-            nextver = matcher.match(version, upconvert_minor=True)
+            nextver = matcher.match(version, upgrade=True)
 
             distribution = data.get('distribution')
             if not distribution or distribution not in files.get(nextver, {}):
@@ -687,7 +719,7 @@ class _remove(COMMAND):
                             '--all --skip)')
 
     @staticmethod
-    def run(args: Namespace) -> Optional[str]:
+    def run(args: Namespace) -> str | None:
         release_del = args.release
         if release_del and \
                 (err := check_release_tag(release_del, check_first=False)):
@@ -716,7 +748,7 @@ class _list(COMMAND):
                             help='only list specified version, else all')
 
     @staticmethod
-    def run(args: Namespace) -> Optional[str]:
+    def run(args: Namespace) -> str | None:
         release_target = get_release_tag(args)
         files = get_release_files(args, release_target, 'cpython')
         if not files:
@@ -735,7 +767,7 @@ class _list(COMMAND):
             upd = ''
             app = ''
             if release_target and release != release_target:
-                nextver = matcher.match(version, upconvert_minor=True)
+                nextver = matcher.match(version, upgrade=True)
                 new_vdir = args._versions / nextver
                 if nextver != version and new_vdir.exists():
                     if args.verbose:
@@ -762,7 +794,7 @@ class _show(COMMAND):
     'Show versions available from a release.'
     @staticmethod
     def init(parser: ArgumentParser) -> None:
-        parser.add_argument('-d', '--distributions', action='store_true',
+        parser.add_argument('-D', '--distribution', action='store_true',
                             help='also show all available distributions for '
                             'each version from the release')
         parser.add_argument('release', nargs='?',
@@ -789,7 +821,7 @@ class _show(COMMAND):
             for distribution in files[version]:
                 app = ' (installed)' \
                         if distribution == installed_distribution else ''
-                if args.distributions or app \
+                if args.distribution or app \
                         or distribution == args._distribution:
                     if distribution == args._distribution:
                         installable = True
@@ -807,10 +839,12 @@ class _path(COMMAND):
     def init(parser: ArgumentParser) -> None:
         parser.add_argument('-p', '--python-path', action='store_true',
                             help='return full path to python executable')
-        parser.add_argument('version', help='version to return path for')
+        parser.add_argument('version', nargs='?',
+                            help='version to return path for, or latest '
+                            'release version if not specified')
 
     @staticmethod
-    def run(args: Namespace) -> Optional[str]:
+    def run(args: Namespace) -> str | None:
         matcher = VersionMatcher([f.name for f in iter_versions(args)])
         version = matcher.match(args.version) or args.version
         path = args._versions / version