Skip to content

Asynchronous client

AsyncConnectClient

Create a new instance of the AsyncConnectClient.

Usage:

from connect.client import AsyncConnectClient
client = AsyncConnectClient('ApiKey SU-000-000-000:xxxxxxxxxxxxxxxx')
product = await client.products['PRD-001-002-003'].get()

Parameters:

Name Type Description Default
api_key str

The API key used for authentication.

required
endpoint str

(Optional) The API endpoint, defaults to https://api.connect.cloudblue.com/public/v1.

required
use_specs bool

(Optional) Use Connect OpenAPI specifications.

required
specs_location

(Optional) The Connect OpenAPI specification local path or URL.

required
validate_using_specs

(Optional) Use the Connect OpenAPI specification to validate the call.

required
default_headers dict

(Optional) HTTP headers to apply to each request.

required
default_limit int

(Optional) Default value for pagination limit parameter.

required
max_retries int

(Optional) Max number of retries for a request before raising an error.

required
logger

(Optional) HTTP Request logger class.

required
timeout int

(Optional) Timeout parameter to pass to the underlying HTTP client.

required
resourceset_append

(Optional) Append all the pages to the current resourceset.

required

response property writable

Returns the raw httpx response.

response: requests.Response property writable

Returns the raw requests response.

collection(name: str) -> Union[Collection, AsyncCollection]

Returns a Collection object identified by its name.

Usage:

products = client.collection('products')

Concise form:

products = client.products

Parameters:

Name Type Description Default
name str

The name of the collection to access.

required

ns(name: str) -> Union[NS, AsyncNS]

Returns a Namespace object identified by its name.

Usage:

subscriptions = client.ns('subscriptions')

Concise form:

subscriptions = client('subscriptions')

Parameters:

Name Type Description Default
name str

The name of the namespace to access.

required

create(url: str, payload: Dict = None, **kwargs) -> Any async

Make a POST call to the given url with the payload.

Parameters:

Name Type Description Default
url str

The url to make the call.

required
payload dict

(Optional) The payload to be used.

None

delete(url: str, payload: Dict = None, **kwargs) -> Any async

Make a DELETE call to the given url with the payload.

Parameters:

Name Type Description Default
url str

The url to make the call.

required
payload dict

(Optional) The payload to be used.

None

get(url: str, **kwargs) -> Any async

Make a GET call to the given url.

Parameters:

Name Type Description Default
url str

The url to make the call.

required

update(url: str, payload: Dict = None, **kwargs) -> Any async

Make a PUT call to the given url with the payload.

Parameters:

Name Type Description Default
url str

The url to make the call.

required
payload dict

(Optional) The payload to be used.

None

AsyncNS

A namespace groups together a set of collections of resources.

collection(name: str)

Returns a [Async]Collection object nested under this namespace object identified by its name.

Usage:

devops_ns = client.ns('devops')
services = devops_ns.collection('products')

Concise form:

services = client('devops').services

Parameters:

Name Type Description Default
name str

The name of the collection to access.

required

Returns:

Type Description
Union[Collection, AsyncCollection]

Returns an object nested under this namespace object identified by its name.

ns(name: str)

Returns a [Async]Namespace object nested under this namespace identified by its name.

Usage:

subscriptions_ns = client.ns('subscriptions')
nested_ns = subcriptions_ns.ns('nested')

Concise form:

nested_ns = client('subscriptions')('nested')

Parameters:

Name Type Description Default
name str

The name of the namespace to access.

required

Returns:

Type Description
Union[NS, AsyncNS]

Returns an object nested under this namespace identified by its name.

AsyncCollection

A collection is a set of resources of the same type.

action(name: str)

Returns an [Async]Action object that represent an action to perform on this collection identified by its name.

Parameters:

Name Type Description Default
name str

The name of the action to perform.

required

Returns:

Type Description
Union[Action, AsyncAction]

Returns an object that represent an action to perform on this collection identified by its name.

all()

Returns a [Async]ResourceSet object that that allow to access all the resources that belong to this collection.

Returns:

Type Description
Union[ResourceSet, AsyncResourceSet]

Returns an object that that allow to access all the resources that belong to this collection.

filter(*args, **kwargs)

Returns a [Async]ResourceSet object. The returned ResourceSet object will be filtered based on the arguments and keyword arguments.

Arguments can be RQL filter expressions as strings or R objects.

Usage:

rs = collection.filter('eq(field,value)', 'eq(another.field,value2)')
rs = collection.filter(R().field.eq('value'), R().another.field.eq('value2'))

All the arguments will be combined with logical and.

Filters can be also specified as keyword argument using the __ (double underscore) notation.

Usage:

rs = collection.filter(
    field=value,
    another__field=value,
    field2__in=('a', 'b'),
    field3__null=True,
)

Also keyword arguments will be combined with logical and.

Returns:

Type Description
Union[ResourceSet, AsyncResourceSet]

The returned ResourceSet object will be filtered based on the arguments and keyword arguments.

resource(resource_id: str)

Returns a [Async]Resource object that represent a resource that belong to this collection identified by its unique identifier.

Usage:

resource = client.collection('products').resource('PRD-000-111-222')

Concise form:

resource = client.products['PRD-000-111-222']

Parameters:

Name Type Description Default
resource_id str

The unique identifier of the resource.

required

Returns:

Type Description
Union[Resource, AsyncResource]

Returns an object that represent a resource that belong to this collection identified by its unique identifier.

bulk_create(payload: Union[List, Tuple], **kwargs) async

Create a set of resources within this collection in a single call.

Usage:

translations = await client.ns('localization').collection('translations').bulk_create(
    payload=[
        {
            'context': {
                'id': 'LCX-1234-1234-123'
            },
            'locale': {
                'id': 'ES-MX'
            },
            'description': 'Awesome Mexican Spanish locale',
            'auto': {
                'enabled': True
            }
        },
        {
            'context': {
                'id': 'LCX-1234-1234-123'
            },
            'locale': {
                'id': 'ES'
            },
            'description': 'Awesome Spanish locale',
            'auto': {
                'enabled': False
            }
        }
    ]
)

Concise form:

translations = await client('localization').translations.bulk_create(
    payload=[
        {
            'context': {
                'id': 'LCX-1234-1234-123'
            },
            'locale': {
                'id': 'ES-MX'
            },
            'description': 'Awesome Mexican Spanish locale',
            'auto': {
                'enabled': True
            }
        },
        {
            'context': {
                'id': 'LCX-1234-1234-123'
            },
            'locale': {
                'id': 'ES'
            },
            'description': 'Awesome Spanish locale',
            'auto': {
                'enabled': False
            }
        }
    ]
)

Parameters:

Name Type Description Default
payload list | tuple

The list of objects to create.

required

bulk_delete(payload: Union[List, Tuple], **kwargs) async

Delete a set of resources from within this collection in a single call.

Usage:

await client.ns('localization').collection('translations').bulk_delete(
    payload=[
        {
            'id': 'TRN-6783-3216-8782'
        },
        {
            'id': 'TRN-6783-0001-8782'
        }
    ]
)

Concise form:

await client('localization').translations.bulk_delete(
    payload=[
        {
            'id': 'TRN-6783-3216-8782',
        },
        {
            'id': 'TRN-6783-0001-8782',
        }
    ]
)

Parameters:

Name Type Description Default
payload list | tuple

The list of objects to update.

required

bulk_update(payload: Union[List, Tuple], **kwargs) async

Update a set of resources that belong to this collection in a single call.

Usage:

translations = await client.ns('localization').collection('translations').bulk_update(
    payload=[
        {
            'id': 'TRN-6783-3216-8782',
            'description': 'Awesome English locale',
            'auto': {
                'enabled': True
            }
        },
        {
            'id': 'TRN-6783-0001-8782',
            'description': 'Awesome Spanish locale'
        }
    ]
)

Concise form:

translations = await client('localization').translations.bulk_update(
    payload=[
        {
            'id': 'TRN-6783-3216-8782',
            'description': 'Awesome English locale',
            'auto': {
                'enabled': True
            }
        },
        {
            'id': 'TRN-6783-0001-8782',
            'description': 'Awesome Spanish locale'
        }
    ]
)

Parameters:

Name Type Description Default
payload list | tuple

The list of objects to update.

required

create(payload: Dict = None, **kwargs) async

Create a new resource within this collection.

Usage:

case = await client.ns('helpdesk').collection('cases').create(
    payload={
        'subject': 'I have a question / problem',
        'description': 'Need help with contracts management.',
        'priority': 0,
        'state': 'pending',
        'type': 'business',
        'issuer': {
            'recipients': [
                {
                    'id': 'UR-012-345-678'
                }
            ]
        },
        'receiver': {
            'account': {
                'id': 'PA-111-222'
            }
        }
    }
)

Concise form:

case = await client('helpdesk').cases.create(
    payload={
        'subject': 'I have a question / problem',
        'description': 'Need help with contracts management.',
        'priority': 0,
        'state': 'pending',
        'type': 'business',
        'issuer': {
            'recipients': [
                {
                    'id': 'UR-012-345-678'
                }
            ]
        },
        'receiver': {
            'account': {
                'id': 'PA-111-222'
            }
        }
    }
)

Parameters:

Name Type Description Default
payload dict

The payload of the resource to create.

None

AsyncResource

A resource is an object with a type, associated data, relationships to other resources and actions that can be performed on such resource.

action(name: str)

Returns an [Async]Action object that can be performed on this this resource object identified by its name.

Usage:

approve_action = (
    client.collection('requests')
    .resource('PR-000-111-222')
    .action('approve')
)

Concise form:

approve_action = client.requests[''PR-000-111-222']('approve')

Parameters:

Name Type Description Default
name str

The name of the action to perform.

required

Returns:

Type Description
Union[Action, AsyncAction]

Returns an object that can be performed on this this resource object identified by its name.

collection(name: str)

Returns a [Async]Collection object nested under this resource object identified by its name.

Usage:

environments = (
    client.ns("devops")
    .collection("services")
    .resource("SRVC-0000-1111")
    .collection("environments")
)

Concise form:

services = client('devops').services['SRVC-0000-1111'].environments

Parameters:

Name Type Description Default
name str

The name of the collection to access.

required

Returns:

Type Description
Union[Collection, AsyncCollection]

Returns an object nested under this resource object identified by its name.

delete(**kwargs) async

Delete the resource this Resource object refers to.

Usage:

await client.collection('products').resource('PRD-000-111-222').delete()

Concise form:

await client.products['PRD-000-111-222'].delete()

exists() -> bool async

Return True if the resource this Resource object refers to exists.

Usage:

if await client.collection('products').resource('PRD-000-111-222').exits():
    ...

Concise form:

if await client.products['PRD-000-111-222'].exists():
    ...

Returns:

Type Description
bool

Return True if the resource this Resource object refers to exists.

get(**kwargs) -> Dict async

Retrieve the resource this Resource object refers to.

Usage:

product = await client.collection('products').resource('PRD-000-111-222').get()

Concise form:

product = await client.products['PRD-000-111-222'].get()

Returns:

Type Description
dict

Returns the resource this Resource object refers to.

update(payload = None, **kwargs) -> Dict async

Update the resource this Resource object refers to.

Usage:

product = await client.collection('products').resource('PRD-000-111-222').update(
    payload={
        'name': 'Cool product'
    }
)

Concise form:

product = await client.products['PRD-000-111-222'].update(
    payload={
        'name': 'Cool product'
    }
)

Parameters:

Name Type Description Default
payload dict

The payload of the update operations.

None

Returns:

Type Description
dict

Returns the updated object.

values(*fields) -> Dict async

Returns a flat dictionary containing only the fields of this resource passed as arguments.

Note

Nested field can be specified using dot notation.

Usage:

values = await resource.values('field', 'nested.field')

Returns:

Type Description
dict

Returns a flat dictionary containing only the fields of this resource passed as arguments.

AsyncAction

An action is an operation that can be performed on resources or collections.

delete(**kwargs) async

Execute the action this Action object refers to using the DELETE HTTP verb.

get(**kwargs) async

Execute the action this Action object refers to using the GET HTTP verb.

Usage:

xlsx = await (
    client.ns('devops')
    .collection('services')
    .resource('SRVC-0000-1111')
    .collection('environments')
    .resource('ENV-0000-1111-01')
    .collection('variables')
    .action('export')
    .get()
)

Concise form:

xlsx = await (
    client('devops')
    .services['SRVC-0000-1111']
    .environments['ENV-0000-1111-01']
    .variables('export').get()
)

post(payload: Dict = None, **kwargs) async

Execute the action this Action object refers to using the POST HTTP verb.

Usage:

product = await (
    client.collection('products')
    .resource('PRD-000-111-222')
    .action('endsale')
    .post(
        payload={
            'replacement': {'id': 'PRD-333-444-555'},
            'end_of_sale_notes': 'Obsolete product'
        }
    )
)

Concise form:

product = await client.products['PRD-000-111-222']('endsale').post(
    payload={
        'replacement': {'id': 'PRD-333-444-555'},
        'end_of_sale_notes': 'Obsolete product'
    }
)

Parameters:

Name Type Description Default
payload dict

The payload needed to perform this action.

None

put(payload: Dict = None, **kwargs) async

Execute the action this Action object refers to using the PUT HTTP verb.

Parameters:

Name Type Description Default
payload dict

The payload needed to perform this action.

None

AsyncResourceSet

A ResourceSet is a set of resources from one collection eventually filtered and ordered.

Represent a set of resources.

Usage:

async for product in (
    client.products.all().filter(
        R().status.eq('published')
    ).order_by('created')
):
    ...

count() -> int async

Returns the total number of resources within this ResourceSet object.

Usage:

no_of_products = await client.products.all().count()

Returns:

Type Description
int

Returns the total number of resources within this ResourceSet object.

first() async

Returns the first resource that belongs to this ResourceSet object or None if the ResourceSet doesn't contains resources.

Usage:

latest_news = await client.news.all().order_by('-updated').first()

Returns:

Type Description
Resource

Returns the first resource that belongs to this ResourceSet object or None.

all()

Returns a copy of the current ResourceSet.

Returns:

Type Description
ResourceSet

Returns a copy of the current ResourceSet.

configure(**kwargs)

Set the default keyword arguments that must be provided to the underlying GET call on each page fetch.

filter(*args, **kwargs)

Applies filters to this ResourceSet object.

Arguments can be RQL filter expressions as strings or R objects.

Usage:

rs = rs.filter('eq(field,value)', 'eq(another.field,value2)')
rs = rs.filter(R().field.eq('value'), R().another.field.eq('value2'))

All the arguments will be combined with logical and.

Filters can be also specified as keyword argument using the __ (double underscore) notation.

rs = rs.filter(
    field=value,
    another__field=value,
    field2__in=('a', 'b'),
    field3__null=True,
)

Also keyword arguments will be combined with logical and.

Returns:

Type Description
ResourceSet

Returns a copy of the current ResourceSet with the filter applied.

limit(limit: int)

Set the number of results that must be fetched on each HTTP call.

Parameters:

Name Type Description Default
limit int

Number of results to fetch in each HTTP call.

required

Returns:

Type Description
ResourceSet

Returns a copy of the current ResourceSet with the limit applied.

order_by(*fields)

Add fields for ordering.

Usage:

purchases = client.requests.all().order_by(
    'asset.tiers.customer.name',
    '-created'
)

Note

To sort results in descending order the name of the field must be prefixed with a - (minus) sign.

Returns:

Type Description
ResourceSet

Returns a copy of the current ResourceSet with the order applied.

search(term: str)

Create a copy of the current ResourceSet applying the search RQL operator equal to term.

Parameters:

Name Type Description Default
term str

The term to search for.

required

Returns:

Type Description
ResourceSet

Create a copy of the current ResourceSet applying the search RQL operator equal to term.

select(*fields)

Apply the RQL select operator to this ResourceSet object.

Usage:

purchases = client.requests.all().select(
    '-asset.items',
    '-asset.params',
    'activation_key',
)

Note

To unselect a field it must be prefixed with a - (minus) sign.

Returns:

Type Description
ResourceSet

Returns a copy of the current ResourceSet with the select applied.

values_list(*fields)

Returns a flat dictionary containing only the fields passed as arguments for each resource that belongs to this ResourceSet.

Nested field can be specified using dot notation.

Usage:

values = rs.values_list('field', 'nested.field')