Skip to content

api.md

Latest commit

 

History

History
217 lines (117 loc) · 5.74 KB

api.md

File metadata and controls

217 lines (117 loc) · 5.74 KB

quilt3

Quilt API

clear_api_key() {#clear_api_key}

Clear the API key and fall back to interactive session (if available).

config(*catalog_url, **config_values) {#config}

Set or read the QUILT configuration.

To retrieve the current config, call directly, without arguments:

import quilt3
quilt3.config()

To trigger autoconfiguration, call with just the navigator URL:

import quilt3
quilt3.config('https://YOUR-CATALOG-URL.com')

To set config values, call with one or more key=value pairs:

import quilt3
quilt3.config(navigator_url='http://example.com')

Default config values can be found in quilt3.util.CONFIG_TEMPLATE.

Arguments

  • catalog_url: A (single) URL indicating a location to configure from
  • **config_values: key=value pairs to set in the config

Returns

QuiltConfig: (an ordered Mapping)

delete_package(name, registry=None, top_hash=None) {#delete_package}

Delete a package. Deletes only the manifest entries and not the underlying files.

Arguments

  • name (str): Name of the package
  • registry (str): The registry the package will be removed from
  • top_hash (str): Optional. A package hash to delete, instead of the whole package.

get_boto3_session(*, fallback: bool = True) -> boto3.session.Session {#get_boto3_session}

Return a Boto3 session with Quilt stack credentials and AWS region. In case of no Quilt credentials found, return a "normal" Boto3 session if fallback is True, otherwise raise a QuiltException.

Note: you need to call quilt3.config("https://your-catalog-homepage/") to have region set on the session, if you previously called it in quilt3 < 6.1.0.

list_package_versions(name, registry=None) {#list_package_versions}

Lists versions of a given package.

Returns an iterable of (latest_or_unix_ts, hash) of package revisions. If the registry is None, default to the local registry.

Arguments

  • name (str): Name of the package
  • registry (str): location of registry to load package from.

Returns

An iterable of tuples containing the version and hash for the package.

list_packages(registry=None) {#list_packages}

Lists Packages in the registry.

Returns an iterable of all named packages in a registry. If the registry is None, default to the local registry.

Arguments

  • registry (str): location of registry to load package from.

Returns

An iterable of strings containing the names of the packages

logged_in() {#logged_in}

Return catalog URL if Quilt client is authenticated, None otherwise.

login() {#login}

Authenticate to your Quilt stack and assume the role assigned to you by your stack administrator. Not required if you have existing AWS credentials.

Launches a web browser and asks the user for a token.

login_with_api_key(key: str) {#login_with_api_key}

Authenticate using an API key.

The API key is stored in memory only (no disk persistence). While set, the API key overrides any interactive session. Use clear_api_key() to revert to interactive session.

Arguments

  • key: API key string (starts with 'qk_')

Raises

  • ValueError: If the key doesn't start with 'qk_' prefix.

logout() {#logout}

Do not use Quilt credentials. Useful if you have existing AWS credentials.

search(query: Union[str, dict], limit: int = 10) -> List[dict] {#search}

Execute a search against the configured search endpoint.

Arguments

  • query: query string to query if passed as str, DSL query body if passed as dict
  • limit: maximum number of results to return. Defaults to 10

Query Syntax: Query String Query Query DSL

Index schemas and search examples can be found in the Quilt Search documentation.

Returns

search results

quilt3.api_keys

API for managing your own API keys.

APIKey(id: str, name: str, fingerprint: str, created_at: datetime.datetime, expires_at: datetime.datetime, last_used_at: Optional[datetime.datetime], status: Literal['ACTIVE', 'EXPIRED'], user_email: str) -> None {#APIKey}

An API key for programmatic access.

APIKeyError(result) {#APIKeyError}

Error during API key operation.

list(name: Optional[str] = None, fingerprint: Optional[str] = None, status: Optional[Literal['ACTIVE', 'EXPIRED']] = None) -> List[quilt3.api_keys.APIKey] {#list}

List your API keys. Optionally filter by name, fingerprint, or status.

Arguments

  • name: Filter by key name.
  • fingerprint: Filter by key fingerprint.
  • status: Filter by "ACTIVE" or "EXPIRED". None returns all.

Returns

List of your API keys matching the filters.

get(id: str) -> Optional[quilt3.api_keys.APIKey] {#get}

Get a specific API key by ID.

Arguments

  • id: The API key ID.

Returns

The API key, or None if not found.

create(name: str, expires_in_days: int = 90) -> Tuple[quilt3.api_keys.APIKey, str] {#create}

Create a new API key for yourself.

Arguments

  • name: Name for the API key.
  • expires_in_days: Days until expiration (1-365, default 90).

Returns

Tuple of (APIKey, secret). The secret is only returned once - save it securely!

Raises

  • APIKeyError: If the operation fails.

revoke(id: Optional[str] = None, secret: Optional[str] = None) -> None {#revoke}

Revoke an API key. Provide either the key ID or the secret.

Arguments

  • id: The API key ID to revoke.
  • secret: The API key secret to revoke.

Raises

  • ValueError: If neither id nor secret is provided.
  • APIKeyError: If the operation fails.