Client

Define the client classes to communicate with StArMap through a session.

Usage

The StarmapClient can be used to query the StArMap service over network and/or locally.

In the subsections below you can find how to properly use the client for different query use-cases.

Online Usage

In this mode the StarmapClient will always request data from the server over the network.

from starmap_client import StarmapClient

# Initialize the online client with the URL only
client = StarmapClient(url="https://starmap.example.com", api_version="v2")

# Alternatively you can create the session and inject it
from starmap_client.session import StarmapSession
session = StarmapSession("https://starmap.example.com", api_version="v2", retries=5, backoff_factor=5.0)
client = StarmapClient(session=session)
...
# Query
client.query_image("sample-product-1.0.0-vhd.xz")
client.query_image_by_name(name="sample-product", version="1.0.0")

Note that either url or session must be passed to the client to instantiate the object.

Offline Usage

In this mode the StarmapClient will always request data from a local provider instead of using the network.

import json
from starmap_client import StarmapClient
from starmap_client.session import StarmapMockSession
from starmap_client.models import QueryResponseContainer
from starmap_client.providers import InMemoryMapProviderV2

# Load the QueryResponseContainer models from somewhere
with open("path_to_your_data.json", 'r') as f:
   qr_data = json.load(f)

# Create the offline client
container = QueryResponseContainer.from_json(qr_data)
provider = InMemoryMapProviderV2(container)
session = StarmapMockSession("fake.starmap.com", "v2")
client = StarmapClient(session=session, provider=provider)

# Query
client.query_image("sample-product-1.0.0-vhd.xz")
client.query_image_by_name(name="sample-product", version="1.0.0")

Hybrid Usage:

In this mode the StarmapClient will first request data from a local provider and only proceed to query over network if the local provider doesn’t have the requested mapping.

import json
from starmap_client import StarmapClient
from starmap_client.models import QueryResponseContainer
from starmap_client.providers import InMemoryMapProviderV2

# Load the QueryResponseContainer models from somewhere
with open("path_to_your_data.json", 'r') as f:
   qr_data = json.load(f)

# Create the offline client
container = QueryResponseContainer.from_json(qr_data)
provider = InMemoryMapProviderV2(container)
client = StarmapClient(url="https://starmap.example.com", provider=provider)

# Query
client.query_image("sample-product-1.0.0-vhd.xz")
client.query_image_by_name(name="sample-product", version="1.0.0")

Implementation

class starmap_client.StarmapClient(url=None, api_version='v2', session=None, session_params=None, provider=None)

Implement the StArMap client.

POLICIES_PER_PAGE = 100

Number of policies to retrieve per call.

__init__(url=None, api_version='v2', session=None, session_params=None, provider=None)

Create a new StArMapClient.

Parameters:

• url (str, optional) – URL of the StArMap endpoint. Required when session is not set.

• api_version (str, optional) – The StArMap API version. Defaults to v2.

• session (StarmapBaseSession, optional) – Defines the session object to use. Defaults to StarmapSession when not set

• session_params (dict, optional) – Additional keyword arguments for StarmapSession

• provider (StarmapProvider, optional) – Object responsible to provide mappings locally. When set the client will be query it first and if no mapping is found the subsequent request will be made to the server.

query_image(nvr, **kwargs)

Query StArMap using an image NVR.

Parameters:

• nvr (str) – The image archive name or NVR.

• workflow (Workflow, optional) – The desired workflow to retrieve the mappings (APIv1 Only)

Returns:

The query result when found or None.

Return type:

QueryResponseContainer

query_image_by_name(name, version=None, **kwargs)

Query StArMap using an image NVR.

Parameters:

• name (str) – The image name from NVR.

• version (str, optional) – The version from NVR.

Returns:

The query result when found or None.

Return type:

QueryResponseContainer

property policies: Iterator[Policy]

Iterate over all Policies registered in StArMap.

list_policies()

List all Policies present in StArMap.

Returns:

List with all policies present in StArMap.

Return type:

list(Policy)

get_policy(policy_id)

Retrieve a single policy by its ID.

Parameters:

policy_id (str) – The Policy ID to retrieve from StArMap.

Returns:

The requested Policy when found.

Return type:

Policy

list_mappings(policy_id)

List all mappings for a given Policy ID.

Parameters:

policy_id (str) – Policy ID to list the mappings.

Return type:

List[Mapping]

Returns:

List with the Mappings for the requested Policy.

get_mapping(mapping_id)

Retrieve a single Marketplace Mapping by its ID.

Parameters:

mapping_id (str) – The Markeplace Mapping ID to retrieve from StArmAp.

Return type:

Optional[Mapping]

Returns:

The requested Marketplace Mapping when found.

list_destinations(mapping_id)

List all destinations for a given Marketplace Mapping ID.

Parameters:

mapping_id (str) – Marketplace Mapping ID to list the mappings.

Return type:

List[Destination]

Returns:

List with the Destinations for the requested Mapping.

get_destination(destination_id)

Retrieve a single Destination by its ID.

Parameters:

destination_id (str) – The Destination ID to retrieve from StArmAp.

Return type:

Optional[Destination]

Returns:

The requested Destination when found.