galactic.helpers.market.core

galactic.helpers.market.core module

Defines the core market helpers.

• Market for market operations

• Store for store management

class Market(cache_path=None, config_path=None)

Bases: object

Singleton class representing a market of stores managing cached packages.

static __new__(cls, cache_path=None, config_path=None)

Create a singleton instance of the Market class.

Return type:

Self

property cache_path: Path

Get the cache directory used for directory paths.

Returns:

The cache directory.

Return type:

Path

property config_path: Path

Get the config directory used for directory paths.

Returns:

The config directory.

Return type:

Path

property store_path: Path

Get the store file used for directory paths.

Returns:

The store file.

Return type:

Path

property stores: dict[str, Store]

Get the list of stores managed by the market.

Returns:

A dictionary of Store instances managed by the market.

Return type:

dict[str, Store]

add_store(store, replace=False)

Add a new store to the market.

Parameters:

• store (Store) – The Store instance to add.

• replace (bool, default: False)

Raises:

• TypeError – If store is not an instance of Store.

• ValueError – If a store with the same name or url already exists.

Return type:

None

get_store(name)

Get a store by its name.

Parameters:

name (str) – The name of the store to retrieve.

Returns:

The Store instance with the specified name.

Return type:

Store

Raises:

• TypeError – If name is not a string.

• ValueError – If the store does not exist.

remove_store(name)

Remove a store by its name.

Parameters:

name (str) – The name of the store to remove.

Raises:

• TypeError – If name is not a string.

• ValueError – If the store does not exist.

• PermissionError – If trying to remove a system-level store.

Return type:

None

load_store(name)

Load the store by downloading the latest packages from the remote index.

Raises:

RuntimeError – If the download fails for any package.

Return type:

None

unload_store(name)

Unload the store by removing its cached packages.

Parameters:

name (str) – The name of the store to unload.

Raises:

TypeError – If name is not a string.

Return type:

None

save_store(name)

Save the store metadata to the stores.json file.

Parameters:

name (str) – The name of the store to save.

Raises:

• TypeError – If name is not a string.

• ValueError – If the store does not exist.

Return type:

None

unsave_store(name)

Remove the store metadata from the stores.json file.

Parameters:

name (str) – The name of the store to remove.

Raises:

• TypeError – If name is not a string.

• ValueError – If the store does not exist.

Return type:

None

get_package(name, pre_release=False)

Find package metadata by name using fuzzy matching.

Parameters:

• name (str) – The name of the package to search for (without version).

• pre_release (bool, default: False) – Whether to include pre-release versions in the search.

Returns:

Metadata dictionary of the matching package.

Return type:

Wheel

Raises:

FileNotFoundError – If no matching package is found in the cache.

find_matching_packages(**criteria)

Find packages in the cache matching given criteria.

Parameters:

criteria (dict[str, str]) – A dictionary of criteria to match against package metadata.

Returns:

A list of metadata dictionaries for each matching package.

Return type:

dict[str, list[Wheel]]

Raises:

TypeError – If criteria is not a dictionary or contains invalid keys.

install_package(name, extra_index_urls=None)

Install a package by name using fuzzy matching.

Parameters:

• name (str) – The name of the package to install (without version).

• extra_index_urls (list[str] | None, default: None) – Additional PyPI index URLs to use during installation.

Returns:

The name of the installed package file.

Return type:

str

Raises:

• TypeError – If name is not a string or extra_index_urls is not a list of strings.

• FileNotFoundError – If no matching package is found in the cache.

• RuntimeError – If pip is not installed or fails to install the package.

• subprocess.CalledProcessError – If the pip install command fails.

get_store_packages(name)

List all wheel packages for a given store name.

Parameters:

name (str) – The name of the store (used as folder name in cache).

Returns:

A dict of metadata dictionaries for each wheel file indexed by their names

Return type:

list[Wheel]

get_all_packages()

List all wheel packages grouped by store folder.

Returns:

Mapping store folder name -> list of package metadata dicts.

Return type:

dict[str, list[Wheel]]

Raises:

FileNotFoundError – If the cache directory does not exist or is not a directory.

purge_cache()

Purge the entire cache directory by removing it and recreating it.

Return type:

None

purge_config()

Purge the configuration directory by removing it and recreating it.

Return type:

None

class Store(name, url, /, *, summary='', created_at=None, loaded_at=None, package_count=0, access_level='unknown', extra_index_urls=None)

Bases: object

Class representing a store for managing Python package repositories.

Parameters:

• name (str) – The name of the store.

• url (str) – The URL of the store.

• summary (str, default: '') – The summary of the store.

• created_at (datetime | None, default: None) – The timestamp when the store was created.

• loaded_at (datetime | None, default: None) – The timestamp when the store was last updated.

• package_count (int, default: 0) – The number of packages available in the store.

• access_level (str, default: 'unknown') – The access level of the store (e.g., “public”, “protected”, “paid”, “private”, “unknown”, “network_error”).

• extra_index_urls (list[str] | None, default: None) – The extra index URLs detected in the store

property name: str

Get the store’s name.

Returns:

The name of the store.

Return type:

str

property url: str

Get the store’s URL.

Returns:

The URL of the store.

Return type:

str

property summary: str

Get the store’s summary description.

Returns:

The summary text.

Return type:

str

property is_system: bool

Check if the store is a system-level store.

Returns:

True if the store is system-level, False otherwise.

Return type:

bool

property created_at: datetime

Get the timestamp when the store was created.

Returns:

The creation timestamp in ISO 8601 format.

Return type:

datetime

property loaded_at: datetime

Get the timestamp when the store was last updated.

Returns:

The last updated timestamp in ISO 8601 format.

Return type:

datetime

property package_count: int

Get the number of packages available in the store.

Returns:

The number of packages in the store.

Return type:

int

property access_level: str

Get the access level of the store.

Returns:

The access level of the store.

Return type:

str

property extra_index_urls: list[str]

Get the store’s extra index URLs.

Returns:

The extra index URLs of the store.

Return type:

list[str]

fetch_access_level()

Determine the access level of the store by performing an HTTP GET request.

Returns:

One of the following access levels: - “public”: accessible without authentication (HTTP 200) - “protected”: requires authentication but is free (HTTP 401) - “paid”: requires payment for access (HTTP 402) - “private”: requires special permissions (HTTP 403) - “network_error”: if a network error occurs

Return type:

None

fetch_package_count()

Get the number of packages available in the store.

Returns:

The number of packages in the store, or -1 if an error occurs.

Return type:

None