Skip to content

Client API Reference

Jump to bottom
Sumio Kiyooka edited this page Apr 19, 2021 · 17 revisions

class Client

A binding to Blackduck's REST API that provides a robust connection backed by a session object. A base URL, timeout, retries, proxies, and TLS verification are set upon initialization and these attributes are persisted across all requests.

At the REST API level, it provides a consistent way to discover and traverse public resources, uses a generator to fetch all items using pagination, and automatically renews the bearer token.

Ultimately it provides a solid foundation especially suited for long-running scripts.

Methods:

def __init__(token=None, base_url=None, session=None, auth=None, verify=True, timeout=15.0, retries=3):

Instantiates a new Client with a binding to Blackduck's REST API.

Arguments:

  • token (str): Access Token obtained from the Hub UI: System -> My Access Tokens
  • base_url (str): e.g. "https://your.blackduck.url"
  • session (requests.Session): custom session if specified. For advanced users only. If not provided, a HubSession with recommended defaults will be generated and used. Any custom session must incorporate a base_url in every request as a plain requests.Session() will not work. See HubSession implementation for an example.
  • auth (requests.auth.AuthBase): custom authorization if specified. For advanced users only. If not provided, one based on the access token is generated and used.
  • verify (bool): TLS certificate verification. Defaults to True.
  • timeout (float): request timeout in seconds. Defaults to 15 seconds.
  • retries (int): maximum number of times to retry a request. Defaults to 3.

def list_resources(self, parent=None):

List named resources that can be fetched.

Arguments:

  • parent (dict/json): resource object from prior get_resource invocations. Defaults to None (for root /api/ base).

Returns:

  • dict(str -> str): of public resource names to urls. To obtain the url to the parent itself, use key 'href'.

def get_resource(name, parent=None, items=True, **kwargs):

Fetch a named resource.

Arguments:

  • name (str): resource name i.e. specific key from list_resources()
  • parent (dict/json): resource object from prior get_resource() call. Use None for root /api/ base.
  • items (bool): enable resource generator for paginated results. Defaults to True.
  • **kwargs: passed to session.request

Returns:

  • list (items=True) or dict (items=False) formed from returned json

def get_metadata(name, parent=None, **kwargs):

Fetch resource metadata and other useful data such as totalCount.

Arguments:

  • name (str): resource name i.e. specific key from list_resources()
  • parent (dict/json): resource object from prior get_resource() call. Use None for root /api/ base.
  • **kwargs: passed to session.request

Returns:

  • dict/json: named resource metadata

def get_json(url, **kwargs):

Utility method to streamline GET request to url endpoint and return json result but preserve underlying error handling.

Arguments:

Returns:

  • json/dict: requested object

def get_items(url, page_size=100, **kwargs):

Fetch all items using pagination.

Arguments:

  • url (str): of endpoint
  • page_size (int): Number of items to get per page. Defaults to 100.
  • **kwargs: passed to session.request

Yields:

  • generator(dict/json): of items

def http_error_handler(r):

Handle an unexpected HTTPError or Response by logging useful information.

Arguments:

  • r (requests.HTTPError OR requests.Response): to handle
Clone this wiki locally