Skip to content

Latest commit

 

History

History
208 lines (143 loc) · 7.28 KB

TUTORIAL.md

File metadata and controls

208 lines (143 loc) · 7.28 KB
Raw

component-registry-bindings

Python bindings for accessing the Component Registry data entities in native python.

Requirements

  • Python 3
  • pip

Installation

You can install the bindings via Python 3 pip:

  • directly from the GitHub repository (will install the version from master branch) 
    pip install -e git+https://github.com/RedHatProductSecurity/component-registry-bindings#egg=component_registry_bindings

Component Registry Compatibility

Component Registry and bindings both uses semantic versioning (eg. MAJOR.MINOR.PATCH, 1.2.3). Bindings are compatible with Component Registry when MAJOR and MINOR version matches.

Eg.

  • Component Registry 1.2.0, bindings 1.2.0 - compatible
  • Component Registry 1.2.0, bindings 1.2.1 - compatible
  • Component Registry 1.2.2, bindings 1.2.1 - compatible
  • Component Registry 1.3.0, bindings 1.2.1 - feature incomplete
  • Component Registry 2.0.0, bindings 1.9.9 - incompatible

Usage

Import the bindings

import component_registry_bindings

Create a session

Session is the main part of the bindings which you will be using. You can create it using the component_registry_bindings.new_session. Created session is then used to access the various endpoints.

You must always specify component_registry_server_uri of the Component Registry instance you want to access.

By default, the SSL verification is enabled, you can disable it by passing verify_ssl argument

session = component_registry_bindings.new_session(component_registry_server_uri="<component registry uri>", username="<username>", password="<password>", verify_ssl=False)

Session operations

This section describes possible session operations. See response section to learn how to work with obtained operation responses.

Operations can be performed on the following entities

  • builds
  • channels
  • components
  • products
  • product_versions
  • product_streams
  • product_variants

status

Most basic operation of the session is retrieving the status.

See /GET /api/{api_version}/status` in API docs for more details (query parameters, response format, etc.)

    status_response = session.status()

builds.retrieve_list

Retrieve a list of Builds.

See /GET /api/{api_version}/builds in API docs for more details (query parameters, response format, etc.)

    all_builds = session.builds.retrieve_list()
    select_builds = session.builds.retrieve_list(type="BREW")

builds.retrieve

Retrieve a single Build with specified 'id'. See /GET /api/{api_version}/builds/{id} in API docs for more details (query parameters, response format, etc.)

session.builds.retrieve(id="1872838")

components.retrieve_list

Retrieve a list of Components.

See /GET /api/{api_version}/components in API docs for more details (query parameters, response format, etc.)

  all_components = session.components.retrieve_list()
  select_components = session.components.retrieve_list(arch="x86_64")

components.retrieve_list_iterator

Retrieve a list of Components. Handles the pagination and returns the generator of individual resource entities.

See /GET /api/{api_version}/components in API docs for more details (query parameters, response format, etc.)

  all_components = session.components.retrieve_list_iterator()
  for component in all_components:
    do_calc(component)

  for component in session.components.retrieve_list_iterator(arch="x86_64"):
    print(component.arch)

components.retrieve_list_iterator_async

Retrieve a list of Components. Handles the pagination and returns the generator of individual resource entities. Uses asynchronous communitation to speed up the data retrieval.

By default there is a limit which allows up to 10 concurrent connections. This limit can be changed by setting the COMPONENT_REGISTRY_BINDINGS_MAX_CONCURRENCY environmental variable. It is strongly recommended to keep this limit between 1-50 concurrent connections. Exceeding this limit may cause service overload which might by considered as the Denial-of-Service attack.

export COMPONENT_REGISTRY_BINDINGS_MAX_CONCURRENCY=30

Using the argument max_results you can limit the number of results returned.

See /GET /api/{api_version}/components in API docs for more details (query parameters, response format, etc.)

  all_components = session.components.retrieve_list_iterator_async()
  for component in all_components:
    do_calc(component)

  for component in session.components.retrieve_list_iterator_async(arch="x86_64"):
    print(component.arch)

  # print the first 200 results
  for component in session.components.retrieve_list_iterator_async(max_results=200):
    print(component.arch)

components.count

Retrieve the the total count number of entities which would be returned by the same retrieve_list call. In terms of the input arguments this operation behaves the same as retrieve_list.

components.retrieve

Retrieve a single Component with specified id.

See /GET /api/{api_version}/components/{id} in API docs for more details (query parameters, response format, etc.)

session.components.retrieve(id="be2e8441-b188-483a-be4a-c040e8c665d2")

search components

Retrieve a list of Components. Performs full text search filter.

    components = session.components.search("crypto")

tag components

Create a tag for the component

    tag = session.components.create_tags(id="be2e8441-b188-483a-be4a-c040e8c665d2")

untag components

Delete tags for the component

    session.components.delete_tags(id="be2e8441-b188-483a-be4a-c040e8c665d2")

Response

This section describes how to work with responses. See operations section to learn how to get these responses.

Single response

This response is typically retrieved from the retrieve or status operations and you receive only one item of desired resource in the response.

Retrieved data are encapsulated in respective model of the retrieved resource which is built on the bindings side.

single_response = session.components.retrieve_list(
    purl="pkg:upstream/github.com/cryostatio/private-cryostat-operator@b63e22b47b0ba47759f6d4a15bbbd11be031da83?version=b63e22b47b0ba47759f6d4a15bbbd11be031da83")

You can access all the model fields as attributes.

single_response.results[0].uuid
# "4a41bafd-43e9-4255-b5cc-a554af8dbb0c"

alternately you can retrieve directly by uuid

single_response = session.components.retrieve(
    id="4a41bafd-43e9-4255-b5cc-a554af8dbb0c"

Which can then be converted to a dictionary.

single_response_dict = single_response.to_dict()

Each paginated response comes also with pagination helpers which allows user to conveniently browse through all the pages without the need to adjust offset or limit. These methods are .next(), .prev() for basic navigation in both directions and .iterator which returns iterable enabling looping through the responses in for loop.