API

This section of the documentation covers the public interfaces of Stac.

Note

When using the library, always make sure to access classes and functions through the stac.api module, not each individual module.

Clients

The classes and functions in the stac.client module make up the main interface to the Stac library. Unless you’re doing something non-typical, this is probably all you need to worry about.

class stac.client.ArtifactoryClient[source]

Interface for getting URLs and versions of artifacts.

How artifact names, packaging, and descriptors are interpreted is implementation specific and typically based on a particular repository layout. For example a Maven layout based client would use full_name for the full group and artifact (e.g. ‘com.example.project.service’). While a Python layout based client would use full_name as unique name in a flat namespace (e.g ‘my-project’).

class stac.client.GenericArtifactoryClient(config)[source]

Artifactory client for use with multiple different repository layouts.

Different ArtifactUrlGenerator implementations can be used with this client to support different repository layouts. The logic within this client should be relatively layout agnostic.

This class is thread safe.

__init__(config)[source]

Create a new generic client instance based on the supplied configuration.

Parameters:config (GenericArtifactoryClientConfig) – Required configuration for this client
get_latest_version(full_name, remote=False)[source]

Get the most recent version of the given project.

The name of the artifact should be composed of the group ID and artifact ID (if available). E.g. “com.example.project.service”. Depending on the repository layout, the full_name might only be the artifact name.

Example usage:

>>> client = new_maven_client('https://www.example.com/artifactory', 'libs-release')
>>> client.get_latest_version('com.example.users.service')
'1.5.0'

The example above returns the latest version of a hypothetical user service, 1.5.0.

This method makes a single network request.

Parameters:
  • full_name (str) – Fully qualified name of the artifact to get the version of.
  • remote (bool) – Should remote repositories be searched to find the latest version (for example if the repository being checked is a virtual repository)? Note that this can make the search much slower. The default is not to check remote repositories.
Returns:

Version number of the latest version of the artifact
Return type:

str
Raises:

stac.exceptions.NoMatchingVersionsError – If no matching artifact could be found
get_latest_versions(full_name, remote=False, limit=5)[source]

Get the most recent versions of the given project, ordered most recent to least recent.

The name of the artifact should be composed of the group ID and artifact ID (if available). E.g. “com.example.project.service”. Depending on the repository layout, the full_name might only be the artifact name.

Example usage:

>>> client = new_maven_client('https://www.example.com/artifactory', 'libs-release')
>>> client.get_latest_versions('com.example.auth.service', limit=3)
['1.6.0', '1.5.4', '1.5.3']

The example above would return a list of the three most recent versions of some hypothetical authentication service.

This method makes a single network request.

Parameters:
  • full_name (str) – Full qualified name of the artifacts to get the versions of.
  • remote (bool) – Should remote repositories be searched to find the latest versions (for example if the repository being checked is a virtual repository)? Note that this can make the search much slower. The default is not to check remote repositories.
  • limit (int) – Only get the limit most recent versions.
Returns:

Most recent versions of the artifact with the given name, ordered with most recent first.
Return type:

list
Raises:
get_version_url(full_name, packaging, version, descriptor=None)[source]

Get the URL to a specific version of the given project, optionally using a descriptor to get a particular variant of the version (sources, javadocs, etc.).

The name of the artifact should be composed of the group ID and artifact ID (if available). E.g. “com.example.project.service”. Depending on the repository layout, the full_name might only be the artifact name.

Packaging should be the type of file used for the artifact, e.g. ‘war’, ‘jar’, ‘pom’, etc.

The descriptor may be used to select javadoc jars, sources jars, or any other assemblies created as part of the version of the artifact.

Example usage:

>>> client = new_maven_client('https://www.example.com/artifactory', 'libs-release')
>>> client.get_version_url('com.example.users.service', '1.4.5', 'jar', descriptor='sources')
'https://www.example.com/artifactory/libs-release/com/example/users/service/1.4.5/service-1.4.5-sources.jar'

The example above would return a path object for the sources jar of version 1.4.5 of some hypothetical user service.

This method does not make any network requests.

Parameters:
  • full_name (str) – Fully qualified name of the artifact to get the path of.
  • packaging (str) – Type of packaging / file format used for the artifact
  • version (str) – Version of the artifact to get the path of.
  • descriptor (str) – Tag to get a particular variant of a release.
Returns:

URL to the artifact with given name and version
Return type:

str
class stac.client.GenericArtifactoryClientConfig[source]

Configuration for construction of a new GenericArtifactoryClient instance.

http_dao = None

DAO for interacting with the Artifactory HTTP API.

is_integration = None

Does the repository we are searching against contain SNAPSHOT (a.k.a. integration) versions and thus require alternate API calls to determine the latest version? Default is false.

url_generator = None

URL generator for determining the URL to download an artifact.

class stac.client.ArtifactUrlGenerator[source]

Interface for generating the URL to download a particular version of an artifact.

Implementations will typically be specific to a particular repository layout in Artifactory. I.e. there may be one URL generator for Maven repositories, another one for Python packages, and another for NPM modules.

class stac.client.MavenArtifactUrlGenerator(base, repo)[source]

URL generator for use with Maven repositories.

stac.client.new_maven_client(base_url, repo, is_snapshot=False, username=None, password=None)[source]

Get a new implementation of ArtifactoryClient for use with Maven repository layouts, optionally using the provided authentication.

Most users will simply call this method to get a new Maven client instance. For example:

>>> client = new_maven_client('https://www.example.com/artifactory', 'libs-release')
>>> latest = client.get_latest_version('com.example.users.service', 'war')
'1.6.0'
Parameters:
  • base_url (str) – URL to root of the Artifactory installation. Example, “https://artifactory.example.com/artifactory”.
  • repo (str) – Which repository should searches be done against. Example, “libs-release-local” or “libs-snapshot-local”.
  • is_snapshot (bool) – Does the repository to perform searches against contain SNAPSHOT (a.k.a. integration) versions? Default is False
  • username (str) – Optional username for authentication when making API calls and downloading artifacts.
  • password (str) – Optional password for authentication when making API calls and downloading artifacts.
Returns:

New Artifactory client for use with Maven repositories
Return type:

GenericArtifactoryClient

HTTP Dao

If you need to customize how the Stac library interacts with Artifactory over HTTP, the stac.http module probably has what you’re looking for.

class stac.http.VersionApiDao(session, base_url, repo)[source]

HTTP DAO to get one or multiple versions of a particular artifact.

This DAO interacts with the Artifactory API over HTTP or HTTPS.

This class is thread safe.

__init__(session, base_url, repo)[source]

Set the factory for requests session and factory for API urls.

Parameters:
  • session (requests.Session) – Session for making HTTP requests to the Artifactory API. This session should be configured with any required credentials for accessing the API.
  • base_url (str|unicode) – Base URL to the Artifactory installation
  • repo (str|unicode) – Name of repository to search against.
get_most_recent_release(group, artifact, remote=False)[source]

Get the version number of the most recent release (non-integration version) of a particular group and artifact combination.

Parameters:
  • group (str) – Group of the artifact to get the version of
  • artifact (str) – Name of the artifact to get the version of
  • remote (bool) – Should remote repositories be searched to find the latest version? Note this can make the request much slower. Default is false.
Returns:

Version number of the most recent release
Return type:

str
Raises:

requests.exceptions.HTTPError – For any non-success HTTP responses from the Artifactory API.
get_most_recent_versions(group, artifact, limit, remote=False, integration=False)[source]

Get a list of the version numbers of the most recent artifacts (integration or non-integration), ordered by the version number, for a particular group and artifact combination.

Parameters:
  • group (str) – Group of the artifact to get versions of
  • artifact (str) – Name of the artifact to get versions of
  • limit (int) – Fetch only this many of the most recent releases
  • remote (bool) – Should remote repositories be searched to find the latest versions? Note this can make the request much slower. Default is false.
  • integration (bool) – If true, fetch only “integration versions”, otherwise fetch only non-integration versions.
Returns:

Version numbers of the most recent artifacts
Return type:

list
Raises:
  • requests.exceptions.HTTPError – For any non-success HTTP responses from the Artifactory API.
  • ValueError – If limit is 0 or negative.

Exceptions

class stac.exceptions.StacError[source]

Base for exceptions raised by the Stac library

class stac.exceptions.NoMatchingVersionsError(*args, **kwargs)[source]

Raised when there is no version or versions matching given criteria