Skip to main content

Download Service

Download Service for spec-kit - Handles GitHub template downloads and archive extraction.

Overview​

This module provides services for downloading templates from GitHub repositories, extracting archives, and validating template packages. Extracted from the monolithic init.py implementation to provide a cleaner, testable interface.

Classes​

DownloadService​

Abstract base class for download services.

Inherits from: ABC

Abstract class

Methods​

download_github_repo​
download_github_repo(self, repo_url: str, destination_path: pathlib.Path, _branch: str = 'main') -> bool

Download a GitHub repository to the specified destination.

Parameters:

  • repo_url (str, required) - GitHub repository URL (e.g., "owner/repo")
  • destination_path (Path, required) - Where to save the downloaded repo
  • _branch (str, optional) - Default: main

Returns: bool

download_specific_template​
download_specific_template(self, repo_url: str, template_name: str, destination_path: pathlib.Path) -> bool

Download a specific template from a repository.

Parameters:

  • repo_url (str, required) - GitHub repository URL
  • template_name (str, required) - Name of the specific template
  • destination_path (Path, required) - Where to save the template

Returns: bool

download_template​
download_template(self, template_url: str, destination_path: pathlib.Path) -> bool

Download a template from a URL to the specified destination.

Parameters:

  • template_url (str, required) - URL to download the template from
  • destination_path (Path, required) - Where to save the downloaded template

Returns: bool

extract_archive​
extract_archive(self, archive_path: pathlib.Path, destination_path: pathlib.Path) -> bool

Extract an archive (ZIP or TAR) to the specified destination.

Parameters:

  • archive_path (Path, required) - Path to the archive file
  • destination_path (Path, required) - Where to extract the archive

Returns: bool

get_available_templates​
get_available_templates(self, repo_url: str) -> List[str]

Get list of available templates from a repository.

Parameters:

  • repo_url (str, required) - GitHub repository URL

Returns: List

validate_template_package​
validate_template_package(self, template_path: pathlib.Path) -> Tuple[bool, Optional[str]]

Validate a template package structure.

Parameters:

  • template_path (Path, required) - Path to the template directory

Returns: Tuple

HttpxDownloadService​

Download service implementation using httpx for HTTP requests.

Inherits from: DownloadService

Methods​

download_github_release_template​
download_github_release_template(self, destination_path: pathlib.Path) -> Tuple[bool, Dict]

Download template from spec-kit GitHub releases.

Parameters:

  • destination_path (Path, required) - Where to save the downloaded template

Returns: Tuple

This method replicates the original download_template_from_github logic.

download_github_repo​
download_github_repo(self, repo_url: str, destination_path: pathlib.Path, _branch: str = 'main') -> bool

Download a GitHub repository to the specified destination.

Parameters:

  • repo_url (str, required)
  • destination_path (Path, required)
  • _branch (str, optional) - Default: main

Returns: bool

This method downloads the latest release from the GitHub repository using the same logic as the original monolithic implementation.

download_specific_template​
download_specific_template(self, repo_url: str, template_name: str, destination_path: pathlib.Path) -> bool

Download a specific template from a repository.

Parameters:

  • repo_url (str, required)
  • template_name (str, required)
  • destination_path (Path, required)

Returns: bool

download_template​
download_template(self, template_url: str, destination_path: pathlib.Path) -> bool

Download a template from a URL to the specified destination.

Parameters:

  • template_url (str, required)
  • destination_path (Path, required)

Returns: bool

extract_archive​
extract_archive(self, archive_path: pathlib.Path, destination_path: pathlib.Path) -> bool

Extract an archive (ZIP or TAR) to the specified destination.

Parameters:

  • archive_path (Path, required)
  • destination_path (Path, required)

Returns: bool

get_available_templates​
get_available_templates(self, repo_url: str) -> List[str]

Get list of available templates from a repository.

Parameters:

  • repo_url (str, required)

Returns: List

validate_template_package​
validate_template_package(self, template_path: pathlib.Path) -> Tuple[bool, Optional[str]]

Validate a template package structure.

Parameters:

  • template_path (Path, required)

Returns: Tuple

Functions​

create_download_service​

create_download_service(console: Optional[rich.console.Console] = None) -> specify_cli.services.download_service.download_service.DownloadService

Factory function to create a download service instance.

Parameters:

  • console (Optional, optional)

Returns: DownloadService