Module `dcso.portal`

The dcso.portal Python3 module helps you create applications and scripts which need to interact with the DCSO Portal.

Installation

To install the latest DCSO Portal SDK using pip:

$ pip install dcso-portal-python-sdk

We advise to use a Virtual Environment when testing/developing.

Alternatively, you can can download or clone the DCSO Portal SDK from GitHub and within the root of the repository:

$ pip install .
or
$ python3 setup.py install

Usage

Initializing API Client

APIClient is the main class for interacting with DCSO Portal.

Basic example (api_endpoint is something known to the reader):

from dcso.portal import APIClient

apic = APIClient(api_endpoint)
apic.auth.authenticate(username='alice', password='tea.pots')

When authentication was successful, the API token will stored in the APIClient instance, unless the authenticate method was called with parameter set_api_token set to False.

In most cases, using credentials is not an option, and a Machine (API) Token is preferred. In your application, you can after instantiating the client, you set the token property:

from dcso.portal import APIClient

apic = APIClient(api_endpoint)
apic.token = "YOURTOKENHERE"

The above is done automatically for you when you set the environment variable DCSO_PORTAL_TOKEN.

Executing GraphQL Queries

DCSO Portal's API uses GraphQL. With the client object initialized, it is possible to execute any GraphQL Query, which response is turned into a namedtuple.

In the following example, we list all the DCSO TDH issues available to us:

result = apic.execute_graphql(query='{ tdh_allIssues { id reference } }')
for issue in result.tdh_allIssues:
    print(f"{issue.id} {issue.reference}")

Depending on the query, you will get sequence, or another nametuple. For example, if you query a specific issue, using its UUID:

issue_id = '3be13d5f-1556-4edf-a243-e7ea4db67f2e'
query = '{ issue: tdh_issue(filter: {id: "'+issue_id+'"}) '+
    '{ title affectedAssets {ip} } }'

result = apic.execute_graphql(query)

print(result.issue.title)
for asset in result.issue.affectedAssets:
    print(f"        {asset.ip}")

Note that in the above example we also used an alias for ({issue: tdh_issue..}). This make the following code more readable.

Expand source code

# Copyright (c) 2020, DCSO GmbH

"""
.. include:: ./README.md

Usage
-----

### Initializing API Client

.. include:: ./apiclient.md

### Executing GraphQL Queries

DCSO Portal's API uses GraphQL. With the client object initialized, it is
possible to execute any GraphQL Query, which response is turned into
a namedtuple.

In the following example, we list all the DCSO TDH issues available to us:

    result = apic.execute_graphql(query='{ tdh_allIssues { id reference } }')
    for issue in result.tdh_allIssues:
        print(f"{issue.id} {issue.reference}")

Depending on the query, you will get sequence, or another nametuple. For example,
if you query a specific issue, using its UUID:

    issue_id = '3be13d5f-1556-4edf-a243-e7ea4db67f2e'
    query = '{ issue: tdh_issue(filter: {id: "'+issue_id+'"}) '+
        '{ title affectedAssets {ip} } }'

    result = apic.execute_graphql(query)

    print(result.issue.title)
    for asset in result.issue.affectedAssets:
        print(f"\t{asset.ip}")

Note that in the above example we also used an alias for (`{issue: tdh_issue..`}).
This make the following code more readable.

"""

__pdoc__ = {
    'test_api': False,
}

from .api import APIClient, ENV_PORTAL_TOKEN
from .exceptions import *

Sub-modules

dcso.portal.abstracts: Definitions of abstract base classes used throughout the dcso.portal module.
dcso.portal.api: Definition of the APIClient class which is used to start interactions with the DCSO Portal API.
dcso.portal.auth: Authentication and Authorization functionality.
dcso.portal.exceptions: Definition of exceptions raised by the dcso.portal module.
dcso.portal.util: Various helper functions and classes.