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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pystand
-Version: 1.3
+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
@@ -136,12 +136,13 @@ 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 90
-                        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.
@@ -178,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
 ```
 
@@ -196,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)
@@ -221,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`
@@ -240,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`
@@ -252,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:
@@ -306,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

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.3.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
 
@@ -35,6 +36,9 @@ LATEST_RELEASE_URL = f'https://raw.githubusercontent.com/{GITHUB_REPO}'\
 # 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$'
 
@@ -183,15 +187,27 @@ def get_version_names(args: Namespace) -> list[str]:
     return sorted(all_names - given, key=parse_version) \
             if args.all else versions
 
+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 not release.isdigit() or len(release) != len(FIRST_RELEASE):
-            sys.exit('Release must be a YYYYMMDD string.')
-        if release < FIRST_RELEASE:
-            sys.exit(f'Releases before "{FIRST_RELEASE}" do not '
-                     'include "*-install_only" builds so are '
-                     'not supported.')
+        if err := check_release_tag(release):
+            sys.exit(err)
 
         return release
 
@@ -207,12 +223,12 @@ def get_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
@@ -292,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'
@@ -313,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:
@@ -408,11 +423,11 @@ 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=90, type=int,
-                     help='cache release file lists for this number '
+                     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',
@@ -496,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')
@@ -533,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',
@@ -601,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.')
 
@@ -625,8 +645,9 @@ 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')
 
@@ -681,8 +702,8 @@ 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:

pystand-1.3.dist-info/RECORD

@@ -1,6 +0,0 @@
-pystand.py,sha256=OI2SWREnCD8Hyu8Xk6z6FZqPDM6NfRtku_Djb6nJ7gM,27357
-pystand-1.3.dist-info/METADATA,sha256=aXLnhaYuWDwnbWEbo5eZb2mzAOklpihUEuWuAzoaztk,14550
-pystand-1.3.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-pystand-1.3.dist-info/entry_points.txt,sha256=DG4ps3I3nni1bubV1tXs6u8FARgkdbAYaEAzZD4RAo8,41
-pystand-1.3.dist-info/top_level.txt,sha256=NoWUh19UQymAJLHTCdxMnVwV6Teftef5fzyF3OWLyNY,8
-pystand-1.3.dist-info/RECORD,,