pystand 1.2__py3-none-any.whl → 1.4__py3-none-any.whl

{pystand-1.2.dist-info → pystand-1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pystand
-Version: 1.2
+Version: 1.4
 Summary: Install Python versions from python-build-standalone project
 Author-email: Mark Blakeney <mark.blakeney@bullet-systems.net>
 License: GPLv3
@@ -33,7 +33,7 @@ provided:
 |`path`   |Show path prefix to installed version base directory                  |
 
 By default, Python versions are sourced from the latest
-`python-build-standalone` [release][pbs-rel] available but you can
+`python-build-standalone` [release][pbs-rel] available (e.g. "`20240415`") but you can
 optionally specify any older release. The required
 [distribution](https://gregoryszorc.com/docs/python-build-standalone/main/running.html)
 for your machine architecture is normally auto-detected but can be
@@ -99,8 +99,8 @@ $ pipx install --python $(pystand path -p 3.12) cowsay
 See detailed usage information in the [Usage](#usage) section that
 follows.
 
-Note that unlike nearly all similar tools such as [`pyenv`][pyenv], [`pdm
-python`][pdmpy], and [`hatch python`][hatchpy], `pystand` directly
+Note that unlike nearly all similar tools such as [`pyenv`][pyenv],
+[`pdm python`][pdmpy], and [`hatch python`][hatchpy], `pystand` directly
 checks the [`python-build-standalone`][pbs] github site to fetch for new
 [releases][pbs-rel] but those other tools require a software update
 before they can see new releases. This means that Python updates are
@@ -117,7 +117,8 @@ Type `pystand` or `pystand -h` to view the usage summary:
 
 ```
 usage: pystand [-h] [-D DISTRIBUTION] [-B BASE_DIR] [-C CACHE_MINUTES]
-                  [--purge-days PURGE_DAYS] [-V]
+                  [--purge-days PURGE_DAYS]
+                  [--github-access-token GITHUB_ACCESS_TOKEN] [-V]
                   {install,update,remove,list,show,path} ...
 
 Command line tool to download, install, and update pre-built Python versions
@@ -135,12 +136,16 @@ options:
                         specify pystand base dir for storing versions and
                         metadata. Default is "$HOME/.local/share/pystand"
   -C CACHE_MINUTES, --cache-minutes CACHE_MINUTES
-                        cache latest release tag fetch for this many minutes,
-                        before rechecking for latest. Default is 60 minutes
+                        cache latest YYYYMMDD release tag fetch for this many
+                        minutes, before rechecking for latest. Default is 60
+                        minutes
   --purge-days PURGE_DAYS
-                        cache release file lists for this number of days after
-                        last version referencing it is removed. Default is 30
-                        days
+                        cache YYYYMMDD release file lists for this number of
+                        days after last version referencing it is removed.
+                        Default is 90 days
+  --github-access-token GITHUB_ACCESS_TOKEN
+                        Optional Github access token. Can specify to reduce
+                        rate limiting.
   -V                    show pystand version
 
 Commands:
@@ -174,8 +179,9 @@ positional arguments:
 options:
   -h, --help            show this help message and exit
   -r RELEASE, --release RELEASE
-                        install from specified python-build-standalone release
-                        (e.g. 20240415), default is latest release
+                        install from specified python-build-standalone
+                        YYYYMMDD release (e.g. 20240415), default is latest
+                        release
   -f, --force           force install even if already installed
 ```
 
@@ -192,8 +198,8 @@ positional arguments:
 options:
   -h, --help            show this help message and exit
   -r RELEASE, --release RELEASE
-                        update to specified release (e.g. 20240415), default
-                        is latest release
+                        update to specified YYYMMDD release (e.g. 20240415),
+                        default is latest release
   -a, --all             update ALL versions
   --skip                skip the specified versions when updating all (only
                         can be specified with --all)
@@ -217,8 +223,8 @@ options:
   --skip                skip the specified versions when removing all (only
                         can be specified with --all)
   -r RELEASE, --release RELEASE
-                        only remove versions if from specified release (e.g.
-                        20240415)
+                        only remove versions if from specified YYYMMDD release
+                        (e.g. 20240415)
 ```
 
 ### Command `list`
@@ -236,8 +242,8 @@ options:
   -v, --verbose         explicitly report why a version is not eligible for
                         update
   -r RELEASE, --release RELEASE
-                        use specified release (e.g. 20240415) for verbose
-                        compare, default is latest release
+                        use specified YYYYMMDD release (e.g. 20240415) for
+                        verbose compare, default is latest release
 ```
 
 ### Command `show`
@@ -248,7 +254,7 @@ usage: pystand show [-h] [-d] [release]
 Show versions available from a release.
 
 positional arguments:
-  release              python-build-standalone release to show (e.g.
+  release              python-build-standalone YYYYMMDD release to show (e.g.
                        20240415), default is latest release
 
 options:
@@ -302,8 +308,8 @@ $ pipx uninstall pystand
 `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
+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
@@ -333,8 +339,8 @@ anything after on a line) are ignored. Type `pystand` to see all
 supported options.
 
 The global options: `--distribution`, `--base-dir`, `--cache-minutes`,
-`--purge-days` are the only sensible candidates to consider setting as
-defaults.
+`--purge-days`, `--github-access-token` are the only sensible candidates
+to consider setting as defaults.
 
 ## Command Line Tab Completion
 

pystand-1.4.dist-info/RECORD

@@ -0,0 +1,6 @@
+pystand.py,sha256=ZwryYWIROt0rscb3vQTx9uE8eZus4x7iUOhHeJBC3SA,28134
+pystand-1.4.dist-info/METADATA,sha256=D-nGRE3vUfZFEJb-NsD74DgROuSzM2E_kcbmBQVvNBc,14679
+pystand-1.4.dist-info/WHEEL,sha256=cpQTJ5IWu9CdaPViMhC9YzF8gZuS5-vlfoFihTBC86A,91
+pystand-1.4.dist-info/entry_points.txt,sha256=DG4ps3I3nni1bubV1tXs6u8FARgkdbAYaEAzZD4RAo8,41
+pystand-1.4.dist-info/top_level.txt,sha256=NoWUh19UQymAJLHTCdxMnVwV6Teftef5fzyF3OWLyNY,8
+pystand-1.4.dist-info/RECORD,,

{pystand-1.2.dist-info → pystand-1.4.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.43.0)
+Generator: setuptools (70.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

pystand.py

@@ -18,6 +18,7 @@ import time
 import urllib.request
 from argparse import ArgumentParser, Namespace
 from collections import defaultdict
+from datetime import date
 from pathlib import Path
 from typing import Any, Iterable, Iterator, Optional
 
@@ -31,6 +32,16 @@ GITHUB_REPO = f'{REPO_OWNER}/{REPO}'
 LATEST_RELEASE_URL = f'https://raw.githubusercontent.com/{GITHUB_REPO}'\
         '/latest-release/latest-release.json'
 
+# The following release is the first one that supports "install_only"
+# builds so this tool does not support any releases before this.
+FIRST_RELEASE = '20210724'
+
+# Sample release tag for documentation/usage examples
+SAMPL_RELEASE = '20240415'
+
+# The following regexp pattern is used to match the end of a release file name
+ENDPAT = r'-install_only[-\dT]*.tar.gz$'
+
 PROG = Path(__file__).stem
 CNFFILE = platformdirs.user_config_path(f'{PROG}-flags.conf')
 
@@ -99,7 +110,14 @@ def get_gh(args: Namespace) -> Any:
         return get_gh_handle
 
     from github import Github
-    get_gh_handle = Github()  # type: ignore
+    if args.github_access_token:
+        from github import Auth
+        auth = Auth.Token(args.github_access_token)
+    else:
+        auth = None
+
+    # Save this handle globally for future use
+    get_gh_handle = Github(auth=auth)  # type: ignore
     return get_gh_handle
 
 def rm_path(path: Path) -> None:
@@ -169,8 +187,30 @@ def get_version_names(args: Namespace) -> list[str]:
     return sorted(all_names - given, key=parse_version) \
             if args.all else versions
 
-def get_latest_release_tag(args: Namespace) -> str:
-    'Return the latest release tag'
+def check_release_tag(release: str, *,
+                      check_first: bool = True) -> Optional[str]:
+    'Check the specified release tag is valid'
+    if not release.isdigit() or len(release) != len(FIRST_RELEASE):
+        return 'Release must be a YYYYMMDD string.'
+
+    try:
+        _ = date.fromisoformat(f'{release[:4]}-{release[4:6]}-{release[6:]}')
+    except Exception:
+        return 'Release must be a YYYYMMDD date string.'
+
+    if check_first and release < FIRST_RELEASE:
+        return f'Releases before "{FIRST_RELEASE}" do not include '\
+                '"*-install_only" builds so are not supported.'
+    return None
+
+def get_release_tag(args: Namespace) -> str:
+    'Return the release tag, or latest if not specified'
+    if release := args.release:
+        if err := check_release_tag(release):
+            sys.exit(err)
+
+        return release
+
     if args._latest_release.exists():
         stat = args._latest_release.stat()
         if time.time() < (stat.st_mtime + int(args.cache_minutes * 60)):
@@ -183,16 +223,25 @@ def get_latest_release_tag(args: Namespace) -> str:
         with urllib.request.urlopen(LATEST_RELEASE_URL) as url:
             data = json.load(url)
     except Exception:
-        sys.exit('Failed to fetch latest release tag.')
+        sys.exit('Failed to fetch latest YYYYMMDD release tag.')
 
     tag = data.get('tag')
 
     if not tag:
-        sys.exit('Latest release tag timestamp file is corrupted.')
+        sys.exit('Latest YYYYMMDD release tag timestamp file is corrupted.')
 
     args._latest_release.write_text(tag + '\n')
     return tag
 
+def get_release_name(filename: str) -> Optional[str]:
+    'Search for and strip the release name from the file name'
+    if not (m := re.search(ENDPAT, filename)):
+        return None
+
+    # Strip of end of file name and also strip any +8 digit embedded
+    # release date
+    return re.sub(r'\+\d{8}', '', filename[:m.start()])
+
 def get_release_files(args, tag, implementation: Optional[str] = None) -> dict:
     'Return the release files for the given tag'
     # Look for tag data in our release cache
@@ -212,17 +261,11 @@ def get_release_files(args, tag, implementation: Optional[str] = None) -> dict:
 
         # Iterate over the release assets and store the files in a dict to
         # return
-        end = '-install_only.tar.gz'
         for file in release.get_assets():
-            name = file.name
-            if not name.endswith(end):
+            if not (name := get_release_name(file.name)):
                 continue
 
-            name = name[:-len(end)]
-            impl_ver, rest = name.split('+', maxsplit=1)
-            impl, ver = impl_ver.split('-', maxsplit=1)
-            rest = rest.split('-', maxsplit=1)[1]
-
+            impl, ver, rest = name.split('-', maxsplit=2)
             if impl not in files:
                 files[impl] = defaultdict(dict)
 
@@ -265,15 +308,13 @@ def update_version_symlinks(args: Namespace) -> None:
     for name, tgt in oldlinks.items():
         new_tgt = newlinks.get(name)
         if not new_tgt or new_tgt != tgt:
-            path = Path(base / name)
-            path.unlink()
+            Path(base / name).unlink()
 
     # Create all needed new links
     for name, tgt in newlinks.items():
         old_tgt = oldlinks.get(name)
         if not old_tgt or old_tgt != tgt:
-            path = Path(base / name)
-            path.symlink_to(tgt, target_is_directory=True)
+            Path(base / name).symlink_to(tgt, target_is_directory=True)
 
 def purge_unused_releases(args: Namespace) -> None:
     'Purge old releases that are no longer needed and have expired'
@@ -286,10 +327,11 @@ def purge_unused_releases(args: Namespace) -> None:
         if (release := get_json(version / args._data).get('release')):
             keep.add(release)
 
-    for release in releases - keep:
+    now_secs = time.time()
+    end_secs = args.purge_days * 86400
+    for release in (releases - keep):
         rdir = args._releases / release
-        stat = rdir.stat()
-        if time.time() > (stat.st_mtime + args.purge_days * 86400):
+        if (rdir.stat().st_mtime + end_secs) < now_secs:
             rdir.unlink()
 
 class COMMAND:
@@ -381,13 +423,16 @@ def main() -> Optional[str]:
                      help=f'specify {PROG} base dir for storing '
                      'versions and metadata. Default is "%(default)s"')
     opt.add_argument('-C', '--cache-minutes', default=60, type=float,
-                     help='cache latest release tag fetch for this many '
-                     'minutes, before rechecking for latest. '
+                     help='cache latest YYYYMMDD release tag fetch for this '
+                     'many minutes, before rechecking for latest. '
                      'Default is %(default)d minutes')
-    opt.add_argument('--purge-days', default=30, type=int,
-                     help='cache release file lists for this number '
+    opt.add_argument('--purge-days', default=90, type=int,
+                     help='cache YYYYMMDD release file lists for this number '
                      'of days after last version referencing it is removed. '
                      'Default is %(default)d days')
+    opt.add_argument('--github-access-token',
+                     help='Optional Github access token. Can specify to reduce '
+                     'rate limiting.')
     opt.add_argument('-V', action='store_true',
                      help=f'show {PROG} version')
     cmd = opt.add_subparsers(title='Commands', dest='cmdname')
@@ -466,7 +511,7 @@ class _install(COMMAND):
     def init(parser: ArgumentParser) -> None:
         parser.add_argument('-r', '--release',
                             help=f'install from specified {REPO} '
-                            'release (e.g. 20240415), '
+                            f'YYYYMMDD release (e.g. {SAMPL_RELEASE}), '
                             'default is latest release')
         parser.add_argument('-f', '--force', action='store_true',
                             help='force install even if already installed')
@@ -475,7 +520,7 @@ class _install(COMMAND):
 
     @staticmethod
     def run(args: Namespace) -> Optional[str]:
-        release = args.release or get_latest_release_tag(args)
+        release = get_release_tag(args)
         files = get_release_files(args, release, 'cpython')
         if not files:
             return f'Release "{release}" not found, or has no compatible files.'
@@ -503,8 +548,8 @@ class _update(COMMAND):
     @staticmethod
     def init(parser: ArgumentParser) -> None:
         parser.add_argument('-r', '--release',
-                            help='update to specified release (e.g. 20240415), '
-                            'default is latest release')
+                            help='update to specified YYYMMDD release (e.g. '
+                            f'{SAMPL_RELEASE}), default is latest release')
         parser.add_argument('-a', '--all', action='store_true',
                             help='update ALL versions')
         parser.add_argument('--skip', action='store_true',
@@ -519,7 +564,7 @@ class _update(COMMAND):
 
     @staticmethod
     def run(args: Namespace) -> Optional[str]:
-        release_target = args.release or get_latest_release_tag(args)
+        release_target = get_release_tag(args)
         files = get_release_files(args, release_target, 'cpython')
         if not files:
             return f'Release "{release_target}" not found.'
@@ -571,18 +616,23 @@ class _remove(COMMAND):
                             help='skip the specified versions when '
                             'removing all (only can be specified with --all)')
         parser.add_argument('-r', '--release',
-                            help='only remove versions if from '
-                            'specified release (e.g. 20240415)')
+                            help='only remove versions if from specified '
+                            f'YYYMMDD release (e.g. {SAMPL_RELEASE})')
         parser.add_argument('version', nargs='*',
                             help='version to remove (or to skip for '
                             '--all --skip)')
 
     @staticmethod
     def run(args: Namespace) -> Optional[str]:
+        release_del = args.release
+        if release_del and \
+                (err := check_release_tag(release_del, check_first=False)):
+            return err
+
         for version in get_version_names(args):
             dfile = args._versions / version / args._data
             release = get_json(dfile).get('release') or '?'
-            if not args.release or release == args.release:
+            if not release_del or release == release_del:
                 remove(args, version)
                 print(f'Version {fmt(version, release)} removed.')
 
@@ -595,14 +645,15 @@ class _list(COMMAND):
                             help='explicitly report why a version is '
                             'not eligible for update')
         parser.add_argument('-r', '--release',
-                            help='use specified release (e.g. 20240415) for '
-                            'verbose compare, default is latest release')
+                            help='use specified YYYYMMDD release '
+                            f'(e.g. {SAMPL_RELEASE}) for verbose compare, '
+                            'default is latest release')
         parser.add_argument('version', nargs='*',
                             help='only list specified version, else all')
 
     @staticmethod
     def run(args: Namespace) -> Optional[str]:
-        release_target = args.release or get_latest_release_tag(args)
+        release_target = get_release_tag(args)
         files = get_release_files(args, release_target, 'cpython')
         if not files:
             return f'Release "{release_target}" not found.'
@@ -651,12 +702,12 @@ class _show(COMMAND):
                             help='also show all available distributions for '
                             'each version from the release')
         parser.add_argument('release', nargs='?',
-                            help=f'{REPO} release to show (e.g. 20240415), '
-                            'default is latest release')
+                            help=f'{REPO} YYYYMMDD release to show (e.g. '
+                            f'{SAMPL_RELEASE}), default is latest release')
 
     @staticmethod
     def run(args: Namespace) -> None:
-        release = args.release or get_latest_release_tag(args)
+        release = get_release_tag(args)
         files = get_release_files(args, release, 'cpython')
         if not files:
             sys.exit(f'Error: release "{release}" not found.')

pystand-1.2.dist-info/RECORD

@@ -1,6 +0,0 @@
-pystand.py,sha256=5X--S1zNpaEauP4FkubSe9J5FM3qQ1OO92ZcPlk__4I,26248
-pystand-1.2.dist-info/METADATA,sha256=V72dn_zsBb0W0ym4lYh3EljiaOqY0s2l9fuszbK_EFg,14304
-pystand-1.2.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-pystand-1.2.dist-info/entry_points.txt,sha256=DG4ps3I3nni1bubV1tXs6u8FARgkdbAYaEAzZD4RAo8,41
-pystand-1.2.dist-info/top_level.txt,sha256=NoWUh19UQymAJLHTCdxMnVwV6Teftef5fzyF3OWLyNY,8
-pystand-1.2.dist-info/RECORD,,