StArMap Client

A client library to communicate with StArMap.

Contents:

• Client
  • Usage
  • Implementation
• Models
  • APIv2
  • APIv1 (Deprecated)
  • Common
  • Utils
• Session
  • Interface
  • Implementations
• Providers
  • Interface
  • Implementations

Quick Start

Install starmap_client:

pip install starmap-client

In your python code, obtain a StarmapClient instance and use it to communicate with StArMap:

from starmap_client import StarmapClient
import logging

# Alternatively you can pass the api_version as well. Defaults to "v2".
# client = StarmapClient(url="https://starmap.example.com", api_version="v2")
client = StarmapClient(url="https://starmap.example.com")

Then it’s possible to use the client object to call any API endpoint from StArMap.

# Query image destinations by NVR
query = client.query_image("sample-product-1.0.0-vhd.xz")

# Query image destinations by name only
query = client.query_image_by_name(name="sample-product")

# Query image destinations by name and version
query = client.query_image_by_name(name="sample-product", version="1.0.0")

# Iterate over all policies from StArMap
for policy in client.policies:
    # Do something
    ...

# List all policies
policies = client.list_policies()

# Get a specific policy by its ID
policy = client.get_policy(policy_id="426a3eac-8b9d-11ed-90ee-902e165594e8")

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")