Synchronous client

ConnectClient

Create a new instance of the ConnectClient.

Usage:

from connect.client import ConnectClient
client = ConnectClient('ApiKey SU-000-000-000:xxxxxxxxxxxxxxxx')
product = 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`	`str`	(Optional) The Connect OpenAPI specification local path or URL.	required
`validate_using_specs`	`bool`	(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: 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`

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`

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`

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`

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`

NS

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.

Collection

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

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

Usage:

translations = 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 = 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)`

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

Usage:

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

Concise form:

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

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

Usage:

translations = 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 = 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) -> Any`

Create a new resource within this collection.

Usage:

case = 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 = 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`

Resource

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

Delete the resource this Resource object refers to.

Usage:

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

Concise form:

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

`exists() -> bool`

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

Usage:

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

Concise form:

if 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`

Retrieve the resource this Resource object refers to.

Usage:

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

Concise form:

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

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

Update the resource this Resource object refers to.

Usage:

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

Concise form:

product = 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`

`values(*fields) -> Dict`

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 = resource.values('field', 'nested.field')

Returns:

Type	Description
`dict`	Returns a flat dictionary containing only the fields of this resource passed as arguments.

Action

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

`delete(**kwargs)`

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

`get(**kwargs)`

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

Usage:

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

Concise form:

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

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

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

Usage:

product = (
    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 = 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)`

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`

ResourceSet

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

Represent a set of resources.

Usage:

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

`count() -> int`

Returns the total number of resources within this ResourceSet object.

Usage:

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

Returns:

Type	Description
`int`	Returns the total number of resources within this ResourceSet object.

`first()`

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

Usage:

latest_news = 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')

Synchronous client

ConnectClient

response: requests.Response property writable

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

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

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

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

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

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

NS

collection(name: str)

ns(name: str)

Collection

action(name: str)

all()

filter(*args, **kwargs)

resource(resource_id: str)

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

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

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

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

Resource

action(name: str)

collection(name: str)

delete(**kwargs)

exists() -> bool

get(**kwargs) -> Dict

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

values(*fields) -> Dict

Action

delete(**kwargs)

get(**kwargs)

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

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

ResourceSet

count() -> int

first()

all()

configure(**kwargs)

filter(*args, **kwargs)

limit(limit: int)

order_by(*fields)

search(term: str)

select(*fields)

values_list(*fields)

`response: requests.Response` `property` `writable`

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

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

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

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

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

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

`collection(name: str)`

`ns(name: str)`

`action(name: str)`

`all()`

`filter(*args, **kwargs)`

`resource(resource_id: str)`

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

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

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

`create(payload: Dict = None, **kwargs) -> Any`

`action(name: str)`

`collection(name: str)`

`delete(**kwargs)`

`exists() -> bool`

`get(**kwargs) -> Dict`

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

`values(*fields) -> Dict`

`delete(**kwargs)`

`get(**kwargs)`

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

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

`count() -> int`

`first()`

`all()`

`configure(**kwargs)`

`filter(*args, **kwargs)`

`limit(limit: int)`

`order_by(*fields)`

`search(term: str)`

`select(*fields)`

`values_list(*fields)`