Release v0.2.0

Author: sco1

.bumper.toml

@@ -1,5 +1,5 @@
 [tool.bumper]
-current_version = "0.1.0"
+current_version = "0.2.0"
 versioning_type = "semver"
 
 [[tool.bumper.files]]

.pre-commit-config.yaml

@@ -36,10 +36,10 @@ repos:
       -  id: python-check-blanket-type-ignore
       -  id: python-use-type-annotations
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.9
+    rev: v0.12.11
     hooks:
       - id: ruff-check
   - repo: https://github.com/rvben/rumdl-pre-commit
-    rev: v0.0.120
+    rev: v0.0.130
     hooks:
       - id: rumdl

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) (`<major>`.`<minor>`.`<patch>`)
 
+## `[v0.2.0]`
+
+### Changed
+* (Internal) Query Gallery API for latest release version prior to download & use for explicit download target
+* (Internal) Move CLI from `argparse` to `typer`
+
+### Added
+* Add extension version to download filename (e.g. `ms-python.python_2025.13.2025082601.vsix`)
+* #2 Add extension cache & management interface
+
 ## `[v0.1.0]`
 
 Initial release 🎉

README.md

@@ -23,27 +23,53 @@ cog.out(
 
 ```text
 $ dl_vsix --help
-usage: dl_VSIX [-h] [-s SPEC_FILE] [-o OUT_DIR] [-f] [-z] [extension]
+Usage: dl_vsix [OPTIONS] COMMAND [ARGS]...
 
-Download VSIX bundles for offline extension installation.
+  Download VSIX bundles for offline extension installation.
+
+Options:
+  --help  Show this message and exit.
 
-positional arguments:
-  extension             Single extension by ID
-
-options:
-  -h, --help            show this help message and exit
-  -s, --spec_file SPEC_FILE
-                        JSON-specified collection of extensions
-  -o, --out_dir OUT_DIR
-                        Download directory (default: ./vsix)
-  -f, --follow_deps     Trace extension's dependencies.
-  -z, --zip             Zip the download extension(s)
+Commands:
+  download  Download VSIX extension packages.
+  cache     Package cache utilities
 ```
 
 <!-- [[[end]]] -->
 
 ## Usage
 
+Extension downloads are accomplished using the `dl_vsix download` command:
+<!-- [[[cog
+import cog
+from subprocess import PIPE, run
+out = run(["dl_vsix", "download", "--help"], stdout=PIPE, encoding="ascii")
+cog.out(
+    f"\n```text\n$ dl_vsix download --help\n{out.stdout.rstrip()}\n```\n\n"
+)
+]]] -->
+
+```text
+$ dl_vsix download --help
+Usage: dl_vsix download [OPTIONS] [EXTENSION_ID]
+
+  Download VSIX extension packages.
+
+  NOTE: `extension_id` and `spec_file` are mutually exclusive.
+
+Arguments:
+  [EXTENSION_ID]  Single extension by ID
+
+Options:
+  -s, --spec_file FILE     JSON-specified collection of extensions
+  -o, --out_dir DIRECTORY  Download directory  [default: vsix]
+  -f, --follow_deps        Trace extension's dependencies
+  -z, --zip                Zip the download extension(s)
+  --help                   Show this message and exit.
+```
+
+<!-- [[[end]]] -->
+
 ### Extension Specification
 
 `dl-vsix` provides two methods for identifying extension(s) to download. Note that these options are mutually exclusive.
@@ -70,3 +96,41 @@ Multiple packages may be specified using a JSON file. Extension IDs are assumed
 Each VSIX package should have an `extension/package.json` detailing extension information; if an extension has additional dependencies, they should be declared in an `"extensionDependencies"` field as a list of extension ID strings.
 
 By default, `dl-vsix` will not trace these dependencies. To enable dependency tracing, use the `-f/--follow_deps` flag to trace the dependencies for each download extension & add them to the download queue if any are found.
+
+## Download Caching
+
+`dl-vsix` implements a simple download cache to help prevent repeated downloads of the latest version of an extension. The cache is FIFO based on file modification date, as creation date is not available on all platforms.
+
+By default, this is located in the user's cache directory, as defined by [`platformdirs`](https://platformdirs.readthedocs.io/en/latest/). OS specific location information can be found under the [Platforms API documentation](https://platformdirs.readthedocs.io/en/latest/api.html#platforms). The cache directory can be overridden using the `DL_VSIX_CACHE_DIR` environment variable; note that changing this directory location does not erase existing contents, nor are existing contents transferred to this location.
+
+Cache size defaults to `512` MB, and is configurable using the `DL_VSIX_CACHE_SIZE` environment variable. Cache pruning is only conducted either when the tool initializes, or a new download is inserted into the cache.
+
+### CLI Interface
+
+Cache utilities are accessible via the `dl_vsix cache` command:
+<!-- [[[cog
+import cog
+from subprocess import PIPE, run
+out = run(["dl_vsix", "cache", "--help"], stdout=PIPE, encoding="ascii")
+cog.out(
+    f"\n```text\n$ dl_vsix cache --help\n{out.stdout.rstrip()}\n```\n\n"
+)
+]]] -->
+
+```text
+$ dl_vsix cache --help
+Usage: dl_vsix cache [OPTIONS] COMMAND [ARGS]...
+
+  Package cache utilities
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  info    Show cache information.
+  list    List cache contents.
+  remove  Remove extension(s) from cache.
+  purge   Clear package cache.
+```
+
+<!-- [[[end]]] -->

dl_vsix/__init__.py

@@ -0,0 +1 @@
+APPNAME = "dl-vsix"

dl_vsix/cli.py

@@ -1,9 +1,30 @@
-import argparse
 import json
+import os
 import shutil
 from pathlib import Path
 
+import typer
+
 from dl_vsix.dl import Extension, download_extensions
+from dl_vsix.extension_cache import DEFAULT_CACHE_MAXSIZE_MB, ExtensionCache
+
+# Initialize package cache in the global scope so we have access to a single instance for the CLI
+_cache_path_env = os.getenv("DL_VSIX_CACHE_DIR")
+_cache_path_override: Path | None
+if _cache_path_env is not None:
+    _cache_path_override = Path(_cache_path_env)
+else:
+    _cache_path_override = None
+
+_cache_maxsize_env = os.getenv("DL_VSIX_CACHE_DIR")
+if _cache_maxsize_env is not None:
+    _cache_maxsize_override = int(_cache_maxsize_env)
+else:
+    _cache_maxsize_override = DEFAULT_CACHE_MAXSIZE_MB
+
+PACKAGE_CACHE = ExtensionCache(
+    path_override=_cache_path_override, cache_maxsize_mb=_cache_maxsize_override
+)
 
 
 def _parse_extensions(spec_json: Path) -> list[Extension]:
@@ -30,39 +51,82 @@ def _parse_extensions(spec_json: Path) -> list[Extension]:
     return [Extension.from_id(s) for s in spec.get("extensions", [])]
 
 
-def main() -> None:  # noqa: D103
-    parser = argparse.ArgumentParser(
-        "dl_VSIX", description="Download VSIX bundles for offline extension installation."
-    )
-    source_group = parser.add_mutually_exclusive_group()
-    source_group.add_argument("extension", nargs="?", type=str, help="Single extension by ID")
-    source_group.add_argument(
-        "-s", "--spec_file", type=Path, help="JSON-specified collection of extensions"
-    )
-    parser.add_argument(
-        "-o",
-        "--out_dir",
-        type=Path,
-        default=Path("./vsix"),
-        help="Download directory (default: ./vsix)",
-    )
-    parser.add_argument(
-        "-f", "--follow_deps", action="store_false", help="Trace extension's dependencies."
-    )
-    parser.add_argument("-z", "--zip", action="store_true", help="Zip the download extension(s)")
-    args = parser.parse_args()
+dl_vsix_cli = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    help="Download VSIX bundles for offline extension installation.",
+)
+
+
+@dl_vsix_cli.command(no_args_is_help=True)
+def download(
+    extension_id: str = typer.Argument("", help="Single extension by ID"),
+    spec_file: Path = typer.Option(
+        None, "-s", "--spec_file", help="JSON-specified collection of extensions", dir_okay=False
+    ),
+    out_dir: Path = typer.Option(
+        Path("./vsix"), "--out_dir", "-o", help="Download directory", file_okay=False
+    ),
+    follow_deps: bool = typer.Option(
+        False, "--follow_deps", "-f", help="Trace extension's dependencies"
+    ),
+    zip_result: bool = typer.Option(False, "--zip", "-z", help="Zip the download extension(s)"),
+) -> None:
+    """
+    Download VSIX extension packages.
+
+    NOTE: `extension_id` and `spec_file` are mutually exclusive.
+    """
+    if (not extension_id) and (spec_file is None):
+        raise ValueError("Either extension_id or spec_file must be specified.")
 
-    # Since we have a mutually exclusive group, only one of these can be specified
-    if args.extension is not None:
-        extensions = [Extension.from_id(args.extension)]
+    if extension_id and spec_file:
+        raise ValueError("Cannot specify both an extension_id and spec file.")
+
+    # Options are mutually exclusive, which should be enforced at this point
+    if extension_id:
+        extensions = [Extension.from_id(extension_id)]
     else:
-        extensions = _parse_extensions(args.spec_file)
+        extensions = _parse_extensions(spec_file)
+
+    download_extensions(
+        extensions, out_dir=out_dir, package_cache=PACKAGE_CACHE, follow_dependencies=follow_deps
+    )
+    if zip_result:
+        zip_filepath = out_dir.parent / "zipped_extensions"
+        shutil.make_archive(base_name=str(zip_filepath), format="zip", root_dir=out_dir)
+
+
+cache_sub = typer.Typer(
+    name="cache", no_args_is_help=True, add_completion=False, help="Package cache utilities"
+)
+dl_vsix_cli.add_typer(cache_sub)
+
+
+@cache_sub.command("info")
+def cache_info() -> None:
+    """Show cache information."""
+    PACKAGE_CACHE.info()
+
+
+@cache_sub.command("list")
+def cache_list() -> None:
+    """List cache contents."""
+    PACKAGE_CACHE.list()
+
+
+@cache_sub.command("remove")
+def cache_remove(extensions: list[str]) -> None:
+    """Remove extension(s) from cache."""
+    for e in extensions:
+        PACKAGE_CACHE.remove(Extension.from_id(e))
+
 
-    download_extensions(extensions, out_dir=args.out_dir, follow_dependencies=args.follow_deps)
-    if args.zip:
-        zip_filepath = args.out_dir.parent / "zipped_extensions"
-        shutil.make_archive(base_name=zip_filepath, format="zip", root_dir=args.out_dir)
+@cache_sub.command("purge")
+def cache_purge() -> None:
+    """Clear package cache."""
+    PACKAGE_CACHE.purge()
 
 
 if __name__ == "__main__":
-    main()
+    dl_vsix_cli()

dl_vsix/dl.py

@@ -8,12 +8,20 @@
 
 import httpx
 
+from dl_vsix.extension_cache import ExtensionCache
+from dl_vsix.extension_query import query_latest_version
+
 
 class Extension(t.NamedTuple):  # noqa: D101
     publisher: str
     extension: str
 
     def __str__(self) -> str:
+        return self.pID
+
+    @property
+    def pID(self) -> str:
+        """Build the full extension ID, as `'<publisher>.<package>'`."""
         return f"{self.publisher}.{self.extension}"
 
     @classmethod
@@ -27,13 +35,12 @@ def from_id(cls, extension_id: str) -> Extension:
         publisher, extension = extension_id.split(".")
         return cls(publisher=publisher, extension=extension)
 
-    @property
-    def vsix_query(self) -> str:
+    def vsix_query(self, version: str = "latest") -> str:
         """Build query URL for the extension's latest VSIX package."""
         api_base = f"https://{self.publisher}.gallery.vsassets.io/_apis/public/gallery"
         publisher_comp = f"publisher/{self.publisher}"
         extension_comp = f"extension/{self.extension}"
-        suffix = "latest/assetbyname/Microsoft.VisualStudio.Services.VSIXPackage"
+        suffix = f"{version}/assetbyname/Microsoft.VisualStudio.Services.VSIXPackage"
 
         return f"{api_base}/{publisher_comp}/{extension_comp}/{suffix}"
 
@@ -65,11 +72,15 @@ def extract_dependencies(vsix_zip: Path, target: str = "extension/package.json")
 def download_extensions(
     extensions: list[Extension],
     out_dir: Path,
+    package_cache: ExtensionCache,
     follow_dependencies: bool = True,
 ) -> None:
     """
     Download VSIX packages for the specified extension(s) from the VS marketplace Gallery API.
 
+    Download cache management is provided using an instance of `ExtensionCache` passed to
+    `package_cache`.
+
     If `follow_dependencies` is `True`, the extension's metadata will be checked to see if it
     depends on any additional packages, which will be added to the queue if they haven't yet been
     downloaded.
@@ -83,19 +94,29 @@ def download_extensions(
     with httpx.Client() as client:
         while extensions:
             ext = extensions.pop()
-            out_filepath = out_dir / f"{ext}.vsix"
-            with client.stream("GET", ext.vsix_query) as r:
-                if r.status_code == httpx.codes.OK:
-                    with out_filepath.open("wb") as f:
-                        for chunk in r.iter_bytes():
-                            f.write(chunk)
-
-                    seen_extensions.add(ext)
-                    print(f"Successfully downloaded extension '{ext}'")
-
-                else:
-                    print(f"Could not download extension '{ext}': {r.status_code}")
-                    continue
+
+            latest_ver = query_latest_version(str(ext))
+            out_filepath = out_dir / f"{ext}_{latest_ver}.vsix"
+
+            cached_ver = package_cache.cached_version(ext)
+            if (cached_ver is not None) and (cached_ver == latest_ver):
+                print(f"Cached download for '{ext}' found - version: {cached_ver}")
+                package_cache.copy_to(ext, out_dir)
+            else:
+                with client.stream("GET", ext.vsix_query(version=latest_ver)) as r:
+                    if r.status_code == httpx.codes.OK:
+                        with out_filepath.open("wb") as f:
+                            for chunk in r.iter_bytes():
+                                f.write(chunk)
+
+                        seen_extensions.add(ext)
+                        print(f"Successfully downloaded extension '{ext}', version: {latest_ver}")
+
+                        # Add to cache
+                        package_cache.insert(out_filepath)
+                    else:
+                        print(f"Could not download extension '{ext}': {r.status_code}")
+                        continue
 
             if follow_dependencies:
                 dependencies = extract_dependencies(out_filepath)