OnyxClient

Class for querying and manipulating data within Onyx.

`init(config)` ¶

Initialise a client.

PARAMETER	DESCRIPTION
`config`	`OnyxConfig` object that stores information for connecting and authenticating with Onyx. TYPE: `OnyxConfig`

Examples:

The recommended way to initialise a client (as a context manager):

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    pass # Do something with the client here

Alternatively, the client can be initialised as follows:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

client = OnyxClient(config)
# Do something with the client here

Tips

When making multiple requests, using the client as a context manager can improve performance.
This is due to the fact that the client will re-use the same session for all requests, rather than creating a new session for each request.
For more information, see: https://requests.readthedocs.io/en/master/user/advanced/#session-objects

`projects()` ¶

View available projects.

RETURNS	DESCRIPTION
`List[Dict[str, str]]`	List of projects.

Examples:

name="__codelineno-0-1" href="#__codelineno-0-1">import os class="kn">from onyx import OnyxConfig, OnyxEnv, OnyxClient class="n">config = OnyxConfig( domain=os.environ[OnyxEnv.DOMAIN], token=os.environ[OnyxEnv.TOKEN], class="p">) class="k">with OnyxClient(config) as client: projects = client.projects() name="__codelineno-1-1" href="#__codelineno-1-1">>>> projects class="p">[ { "project": "project_1", "scope": "admin", "actions": [ "get", "list", "filter", "add", "change", "delete", ], }, { "project": "project_2", "scope": "analyst", "actions": [ "get", "list", "filter", ], }, class="p">]

`types()` ¶

View available field types.

RETURNS	DESCRIPTION
`List[Dict[str, Any]]`	List of field types.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    field_types = client.types()

>>> field_types
[
    {
        "type": "text",
        "description": "A string of characters.",
        "lookups": [
            "exact",
            "ne",
            "in",
            "notin",
            "contains",
            "startswith",
            "endswith",
            "iexact",
            "icontains",
            "istartswith",
            "iendswith",
            "length",
            "length__in",
            "length__range",
            "isnull",
        ],
    },
    {
        "type": "choice",
        "description": "A restricted set of options.",
        "lookups": [
            "exact",
            "ne",
            "in",
            "notin",
            "isnull",
        ],
    },
]

`lookups()` ¶

View available lookups.

RETURNS	DESCRIPTION
`List[Dict[str, Any]]`	List of lookups.

Examples:

import os

from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    lookups = client.lookups()

>>> lookups
[
    {
        "lookup": "exact",
        "description": "The field's value must be equal to the query value.",
        "types": [
            "text",
            "choice",
            "integer",
            "decimal",
            "date",
            "datetime",
            "bool",
        ],
    },
    {
        "lookup": "ne",
        "description": "The field's value must not be equal to the query value.",
        "types": [
            "text",
            "choice",
            "integer",
            "decimal",
            "date",
            "datetime",
            "bool",
        ],
    },
]

`fields(project)` ¶

View fields for a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict of fields.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    fields = client.fields("project")

>>> fields
{
    "name": "Project Name",
    "description": "Project description.",
    "object_type": "records",
    "version": "0.1.0",
    "fields": {
        "climb_id": {
            "description": "Unique identifier for a project record in Onyx.",
            "type": "text",
            "required": True,
            "actions": [
                "get",
                "list",
                "filter",
            ],
            "restrictions": [
                "Max length: 12",
            ],
        },
        "is_published": {
            "description": "Indicator for whether a project record has been published.",
            "type": "bool",
            "required": False,
            "actions": [
                "get",
                "list",
                "filter",
                "add",
                "change",
            ],
            "default": True,
        },
        "published_date": {
            "description": "The date the project record was published in Onyx.",
            "type": "date (YYYY-MM-DD)",
            "required": False,
            "actions": [
                "get",
                "list",
                "filter",
            ],
        },
        "country": {
            "description": "Country of origin.",
            "type": "choice",
            "required": False,
            "actions": [
                "get",
                "list",
                "filter",
                "add",
                "change",
            ],
            "values": [
                "ENG",
                "WALES",
                "SCOT",
                "NI",
            ],
        },
    },
}

`choices(project, field)` ¶

View choices for a field.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`field`	Choice field on the project. TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Dict[str, Any]]`	Dictionary mapping choices to information about the choice.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    choices = client.choices("project", "country")

>>> choices
{
    "ENG": {
        "description": "England",
        "is_active" : True,
    },
    "WALES": {
        "description": "Wales",
        "is_active" : True,
    },
    "SCOT": {
        "description": "Scotland",
        "is_active" : True,
    },
    "NI": {
        "description": "Northern Ireland",
        "is_active" : True,
    },
}

`get(project, climb_id=None, fields=None, include=None, exclude=None)` ¶

Get a record from a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`climb_id`	Unique identifier for the record. TYPE: `Optional[str]` DEFAULT: `None`
`fields`	Dictionary of field filters used to uniquely identify the record. TYPE: `Optional[Dict[str, Any]]` DEFAULT: `None`
`include`	Fields to include in the output. TYPE: `Union[List[str], str, None]` DEFAULT: `None`
`exclude`	Fields to exclude from the output. TYPE: `Union[List[str], str, None]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing the record.

Examples:

Get a record by CLIMB ID:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    record = client.get("project", "C-1234567890")

>>> record
{
    "climb_id": "C-1234567890",
    "published_date": "2023-01-01",
    "field1": "value1",
    "field2": "value2",
}

Get a record by fields that uniquely identify it:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    record = client.get(
        "project",
        fields={
            "field1": "value1",
            "field2": "value2",
        },
    )

>>> record
{
    "climb_id": "C-1234567890",
    "published_date": "2023-01-01",
    "field1": "value1",
    "field2": "value2",
}

The include and exclude arguments can be used to control the fields returned:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    record_v1 = client.get(
        "project",
        climb_id="C-1234567890",
        include=["climb_id", "published_date"],
    )
    record_v2 = client.get(
        "project",
        climb_id="C-1234567890",
        exclude=["field2"],
    )

>>> record_v1
{
    "climb_id": "C-1234567890",
    "published_date": "2023-01-01",
}
>>> record_v2
{
    "climb_id": "C-1234567890",
    "published_date": "2023-01-01",
    "field1": "value1",
}

Tips

Including/excluding fields to reduce the size of the returned data can improve performance.

`filter(project, fields=None, include=None, exclude=None, summarise=None, **kwargs)` ¶

Filter records from a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`fields`	Dictionary of field filters. TYPE: `Optional[Dict[str, Any]]` DEFAULT: `None`
`include`	Fields to include in the output. TYPE: `Union[List[str], str, None]` DEFAULT: `None`
`exclude`	Fields to exclude from the output. TYPE: `Union[List[str], str, None]` DEFAULT: `None`
`summarise`	For a given field (or group of fields), return the frequency of each unique value (or unique group of values). TYPE: `Union[List[str], str, None]` DEFAULT: `None`
`**kwargs`	Additional keyword arguments are interpreted as field filters. TYPE: `Any` DEFAULT: `{}`

RETURNS	DESCRIPTION
`None`	Generator of records. If a summarise argument is provided, each record will be a dict containing values of the summary fields and a count for the frequency.

Notes

Field filters specify requirements that the returned data must satisfy. They can be provided as keyword arguments, or as a dictionary to the fields argument.
These filters can be a simple match on a value (e.g. "published_date" : "2023-01-01"), or they can use a 'lookup' for more complex matching conditions (e.g. "published_date__iso_year" : "2023").
Multi-value lookups (e.g. in, range) can also be used. For keyword arguments, multiple values can be provided as a Python list. For the fields dictionary, multiple values must be provided as a comma-separated string (see examples below).

Examples:

Retrieve all records that match a set of field requirements:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

# Field conditions can either be provided as keyword arguments:
with OnyxClient(config) as client:
    records = list(
        client.filter(
            project="project",
            field1="abcd",
            published_date__range=["2023-01-01", "2023-01-02"],
        )
    )

# Or as a dictionary to the 'fields' argument:
with OnyxClient(config) as client:
    records = list(
        client.filter(
            project="project",
            fields={
                "field1": "abcd",
                "published_date__range" : "2023-01-01, 2023-01-02",
            },
        )
    )

>>> records
[
    {
        "climb_id": "C-1234567890",
        "published_date": "2023-01-01",
        "field1": "abcd",
        "field2": 123,
    },
    {
        "climb_id": "C-1234567891",
        "published_date": "2023-01-02",
        "field1": "abcd",
        "field2": 456,
    },
]

The summarise argument can be used to return the frequency of each unique value for a given field, or the frequency of each unique set of values for a group of fields:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    records_v1 = list(
        client.filter(
            project="project",
            field1="abcd",
            published_date__range=["2023-01-01", "2023-01-02"],
            summarise="published_date",
        )
    )

    records_v2 = list(
        client.filter(
            project="project",
            field1="abcd",
            published_date__range=["2023-01-01", "2023-01-02"],
            summarise=["published_date", "field2"],
        )
    )

>>> records_v1
[
    {
        "published_date": "2023-01-01",
        "count": 1,
    },
    {
        "published_date": "2023-01-02",
        "count": 1,
    },
]
>>> records_v2
[
    {
        "published_date": "2023-01-01",
        "field2": 123,
        "count": 1,
    },
    {
        "published_date": "2023-01-02",
        "field2": 456,
        "count": 1,
    },
]

`query(project, query=None, include=None, exclude=None, summarise=None)` ¶

Query records from a project.

This method supports more complex filtering than the OnyxClient.filter method. Here, filters can be combined using Python's bitwise operators, representing AND, OR, XOR and NOT operations.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`query`	`OnyxField` object representing the query being made. TYPE: `Optional[OnyxField]` DEFAULT: `None`
`include`	Fields to include in the output. TYPE: `Union[List[str], str, None]` DEFAULT: `None`
`exclude`	Fields to exclude from the output. TYPE: `Union[List[str], str, None]` DEFAULT: `None`
`summarise`	For a given field (or group of fields), return the frequency of each unique value (or unique group of values). TYPE: `Union[List[str], str, None]` DEFAULT: `None`

RETURNS	DESCRIPTION
`None`	Generator of records. If a summarise argument is provided, each record will be a dict containing values of the summary fields and a count for the frequency.

Notes

The query argument must be an instance of OnyxField.
OnyxField instances can be combined into complex expressions using Python's bitwise operators: & (AND), | (OR), ^ (XOR), and ~ (NOT).
Multi-value lookups (e.g. in, range) support passing a Python list (see example below).

Examples:

Retrieve all records that match the query provided by an OnyxField object:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient, OnyxField

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    records = list(
        client.query(
            project="project",
            query=(
                OnyxField(field1="abcd")
                & OnyxField(published_date__range=["2023-01-01", "2023-01-02"])
            ),
        )
    )

>>> records
[
    {
        "climb_id": "C-1234567890",
        "published_date": "2023-01-01",
        "field1": "abcd",
        "field2": 123,
    },
    {
        "climb_id": "C-1234567891",
        "published_date": "2023-01-02",
        "field1": "abcd",
        "field2": 456,
    },
]

`to_csv(csv_file, data, delimiter=None)` `classmethod` ¶

Write a set of records to a CSV file.

PARAMETER	DESCRIPTION
`csv_file`	File object for the CSV file being written to. TYPE: `TextIO`
`data`	The data being written to the CSV file. Must be either a list / generator of dict records. TYPE: `Union[List[Dict[str, Any]], Generator[Dict[str, Any], Any, None]]`
`delimiter`	CSV delimiter. If not provided, defaults to `","` for CSVs. Set this to `"\t"` to work with TSV files. TYPE: `Optional[str]` DEFAULT: `None`

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client, open("/path/to/file.csv") as csv_file:
    client.to_csv(
        csv_file=csv_file,
        data=client.filter(
            "project",
            fields={
                "field1": "value1",
                "field2": "value2",
            },
    )

`history(project, climb_id)` ¶

View the history of a record in a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`climb_id`	Unique identifier for the record. TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing the history of the record.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    history = client.history("project", "C-1234567890")

>>> history
{
    "climb_id": "C-1234567890",
    "history": [
        {
            "username": "user",
            "timestamp": "2023-01-01T00:00:00Z",
            "action": "add",
        },
        {
            "username": "user",
            "timestamp": "2023-01-02T00:00:00Z",
            "action": "change",
            "changes": [
                {
                    "field": "field_1",
                    "type": "text",
                    "from": "value1",
                    "to": "value2",
                },
                {
                    "field": "field_2",
                    "type": "integer",
                    "from": 3,
                    "to": 4,
                },
                {
                    "field": "nested_field",
                    "type": "relation",
                    "action": "add",
                    "count" : 3,
                },
                {
                    "field": "nested_field",
                    "type": "relation",
                    "action": "change",
                    "count" : 10,
                },
            ],
        },
    ],
}

`analyses(project, climb_id)` ¶

View the analyses of a record in a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`climb_id`	Unique identifier for the record. TYPE: `str`

RETURNS	DESCRIPTION
`List[Dict[str, Any]]`	List of Dicts containing basic details of each analysis of the record.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    analyses = client.analyses("project", "C-1234567890")

>>> analyses
[
    {
        "analysis_id": "A-1234567890",
        "published_date": "2023-02-01",
        "analysis_date": "2023-01-01",
        "site": "site",
        "name": "First Analysis",
        "report": "s3://analysis_1.html",
        "outputs": "s3://analysis_1_outputs/",
    },
    {
        "analysis_id": "A-0987654321",
        "published_date": "2024-02-01",
        "analysis_date": "2023-01-01",
        "site": "site",
        "name": "Second Analysis",
        "report": "s3://analysis_2.html",
        "outputs": "s3://analysis_2_outputs/",
    },
]

`identify(project, field, value, site=None)` ¶

Get the anonymised identifier for a value on a field.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`field`	Field on the project. TYPE: `str`
`value`	Value to identify. TYPE: `str`
`site`	Site to identify the value on. If not provided, defaults to the user's site. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, str]`	Dict containing the project, site, field, value and anonymised identifier.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    identification = client.identify("project", "sample_id", "hidden-value")

>>> identification
{
    "project": "project",
    "site": "site",
    "field": "sample_id",
    "value": "hidden-value",
    "identifier": "S-1234567890",
}

`create(project, fields, test=False)` ¶

Create a record in a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`fields`	Object representing the record to be created. TYPE: `Dict[str, Any]`
`test`	If `True`, runs the command as a test. Default: `False` TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing the CLIMB ID of the created record.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    result = client.create(
        "project",
        fields={
            "field1": "value1",
            "field2": "value2",
        },
    )

>>> result
{"climb_id": "C-1234567890"}

`update(project, climb_id, fields=None, test=False)` ¶

Update a record in a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`climb_id`	Unique identifier for the record. TYPE: `str`
`fields`	Object representing the record to be updated. TYPE: `Optional[Dict[str, Any]]` DEFAULT: `None`
`test`	If `True`, runs the command as a test. Default: `False` TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing the CLIMB ID of the updated record.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    result = client.update(
        project="project",
        climb_id="C-1234567890",
        fields={
            "field1": "value1",
            "field2": "value2",
        },
    )

>>> result
{"climb_id": "C-1234567890"}

`delete(project, climb_id)` ¶

Delete a record in a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`climb_id`	Unique identifier for the record. TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing the CLIMB ID of the deleted record.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    result = client.delete(
        project="project",
        climb_id="C-1234567890",
    )

>>> result
{"climb_id": "C-1234567890"}

`csv_create(project, csv_file, fields=None, delimiter=None, multiline=False, test=False)` ¶

Use a CSV file to create record(s) in a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`csv_file`	File object for the CSV file being used for record upload. TYPE: `TextIO`
`fields`	Additional fields provided for each record being uploaded. Takes precedence over fields in the CSV. TYPE: `Optional[Dict[str, Any]]` DEFAULT: `None`
`delimiter`	CSV delimiter. If not provided, defaults to `","` for CSVs. Set this to `"\t"` to work with TSV files. TYPE: `Optional[str]` DEFAULT: `None`
`multiline`	If `True`, allows processing of CSV files with more than one record. Default: `False` TYPE: `bool` DEFAULT: `False`
`test`	If `True`, runs the command as a test. Default: `False` TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Union[Dict[str, Any], List[Dict[str, Any]]]`	Dict containing the CLIMB ID of the created record. If `multiline = True`, returns a list of dicts containing the CLIMB ID of each created record.

Examples:

Create a single record:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client, open("/path/to/file.csv") as csv_file:
    result = client.csv_create(
        project="project",
        csv_file=csv_file,
    )

>>> result
{"climb_id": "C-1234567890"}

Create multiple records:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client, open("/path/to/file.csv") as csv_file:
    results = client.csv_create(
        project="project",
        csv_file=csv_file,
        multiline=True,
    )

>>> results
[
    {"climb_id": "C-1234567890"},
    {"climb_id": "C-1234567891"},
    {"climb_id": "C-1234567892"},
]

`csv_update(project, csv_file, fields=None, delimiter=None, multiline=False, test=False)` ¶

Use a CSV file to update record(s) in a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`csv_file`	File object for the CSV file being used for record upload. TYPE: `TextIO`
`fields`	Additional fields provided for each record being uploaded. Takes precedence over fields in the CSV. TYPE: `Optional[Dict[str, Any]]` DEFAULT: `None`
`delimiter`	CSV delimiter. If not provided, defaults to `","` for CSVs. Set this to `"\t"` to work with TSV files. TYPE: `Optional[str]` DEFAULT: `None`
`multiline`	If `True`, allows processing of CSV files with more than one record. Default: `False` TYPE: `bool` DEFAULT: `False`
`test`	If `True`, runs the command as a test. Default: `False` TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Union[Dict[str, Any], List[Dict[str, Any]]]`	Dict containing the CLIMB ID of the updated record. If `multiline = True`, returns a list of dicts containing the CLIMB ID of each updated record.

Examples:

Update a single record:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client, open("/path/to/file.csv") as csv_file:
    result = client.csv_update(
        project="project",
        csv_file=csv_file,
    )

>>> result
{"climb_id": "C-1234567890"}

Update multiple records:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client, open("/path/to/file.csv") as csv_file:
    results = client.csv_update(
        project="project",
        csv_file=csv_file,
        multiline=True,
    )

>>> results
[
    {"climb_id": "C-1234567890"},
    {"climb_id": "C-1234567891"},
    {"climb_id": "C-1234567892"},
]

`csv_delete(project, csv_file, delimiter=None, multiline=False)` ¶

Use a CSV file to delete record(s) in a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`csv_file`	File object for the CSV file being used for record upload. TYPE: `TextIO`
`delimiter`	CSV delimiter. If not provided, defaults to `","` for CSVs. Set this to `"\t"` to work with TSV files. TYPE: `Optional[str]` DEFAULT: `None`
`multiline`	If `True`, allows processing of CSV files with more than one record. Default: `False` TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Union[Dict[str, Any], List[Dict[str, Any]]]`	Dict containing the CLIMB ID of the deleted record. If `multiline = True`, returns a list of dicts containing the CLIMB ID of each deleted record.

Examples:

Delete a single record:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client, open("/path/to/file.csv") as csv_file:
    result = client.csv_delete(
        project="project",
        csv_file=csv_file,
    )

>>> result
{"climb_id": "C-1234567890"}

Delete multiple records:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client, open("/path/to/file.csv") as csv_file:
    results = client.csv_delete(
        project="project",
        csv_file=csv_file,
        multiline=True,
    )

>>> results
[
    {"climb_id": "C-1234567890"},
    {"climb_id": "C-1234567891"},
    {"climb_id": "C-1234567892"},
]

`analysis_fields(project)` ¶

View analysis fields.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict of fields.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    fields = client.analysis_fields("project")

`analysis_choices(project, field)` ¶

View choices for an analysis field.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`field`	Analysis choice field. TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Dict[str, Any]]`	Dictionary mapping choices to information about the choice.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    choices = client.analysis_choices("project", "country")

`get_analysis(project, analysis_id=None, fields=None, include=None, exclude=None)` ¶

Get an analysis from a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`analysis_id`	Unique identifier for the analysis. TYPE: `Optional[str]` DEFAULT: `None`
`fields`	Dictionary of field filters used to uniquely identify the record. TYPE: `Optional[Dict[str, Any]]` DEFAULT: `None`
`include`	Fields to include in the output. TYPE: `Union[List[str], str, None]` DEFAULT: `None`
`exclude`	Fields to exclude from the output. TYPE: `Union[List[str], str, None]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing the record.

Examples:

Get an analysis by analysis ID:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    analysis = client.get_analysis("project", "A-1234567890")

>>> analysis
{
    "analysis_id": "A-1234567890",
    "published_date": "2023-01-01",
    "name": "Very cool analysis",
    "result": "Found very cool things",
}

`filter_analysis(project, fields=None, include=None, exclude=None, summarise=None, **kwargs)` ¶

Filter analyses from a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`fields`	Dictionary of field filters. TYPE: `Optional[Dict[str, Any]]` DEFAULT: `None`
`include`	Fields to include in the output. TYPE: `Union[List[str], str, None]` DEFAULT: `None`
`exclude`	Fields to exclude from the output. TYPE: `Union[List[str], str, None]` DEFAULT: `None`
`summarise`	For a given field (or group of fields), return the frequency of each unique value (or unique group of values). TYPE: `Union[List[str], str, None]` DEFAULT: `None`
`**kwargs`	Additional keyword arguments are interpreted as field filters. TYPE: `Any` DEFAULT: `{}`

RETURNS	DESCRIPTION
`None`	Generator of analyses. If a summarise argument is provided, each record will be a dict containing values of the summary fields and a count for the frequency.

Examples:

Retrieve all analyses that match a set of field requirements:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    analyses = list(
        client.filter_analysis(
            project="project",
            published_date__range=["2023-01-01", "2023-01-02"],
        )
    )

>>> analyses
[
    {
        "analysis_id": "A-1234567890",
        "published_date": "2023-01-01",
        "name": "Very cool analysis",
        "result": "Found very cool things",
    },
    {
        "analysis_id": "A-1234567891",
        "published_date": "2023-01-02",
        "name": "Not so cool analysis",
        "result": "Found not so cool things",
    },
]

Tips

See the documentation for the filter method for more information on filtering records, as this also applies to analyses.

`analysis_history(project, analysis_id)` ¶

View the history of an analysis in a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`analysis_id`	Unique identifier for the analysis. TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing the history of the analysis.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    history = client.analysis_history("project", "A-1234567890")

>>> history
{
    "analysis_id": "A-1234567890",
    "history": [
        {
            "username": "user",
            "timestamp": "2023-01-01T00:00:00Z",
            "action": "add",
        },
        {
            "username": "user",
            "timestamp": "2023-01-02T00:00:00Z",
            "action": "change",
            "changes": [
                {
                    "field": "name",
                    "type": "text",
                    "from": "Cool analysis",
                    "to": "Very cool analysis",
                },
            ],
        },
    ],
}

`analysis_records(project, analysis_id)` ¶

View the records involved in an analysis in a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`analysis_id`	Unique identifier for the analysis. TYPE: `str`

RETURNS	DESCRIPTION
`List[Dict[str, Any]]`	List of Dicts containing basic details of each record involved in the analysis.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    records = client.analysis_records("project", "A-1234567890")

>>> records
[
    {
        "climb_id": "C-1234567890",
        "published_date": "2023-01-01",
        "site": "site_1",
    },
    {
        "climb_id": "C-1234567891",
        "published_date": "2023-01-02",
        "site": "site_2",
    },
]

`create_analysis(project, fields, test=False)` ¶

Create an analysis in a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`fields`	Object representing the analysis to be created. TYPE: `Dict[str, Any]`
`test`	If `True`, runs the command as a test. Default: `False` TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing the Analysis ID of the created analysis.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    result = client.create_analysis(
        "project",
        fields={
            "name": "Absolutely incredible analysis",
            "result": "Insane results",
        },
    )

>>> result
{"analysis_id": "A-1234567890"}

`update_analysis(project, analysis_id, fields=None, test=False)` ¶

Update an analysis in a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`analysis_id`	Unique identifier for the analysis. TYPE: `str`
`fields`	Object representing the analysis to be updated. TYPE: `Optional[Dict[str, Any]]` DEFAULT: `None`
`test`	If `True`, runs the command as a test. Default: `False` TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing the Analysis ID of the updated analysis.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    result = client.update_analysis(
        project="project",
        analysis_id="A-1234567890",
        fields={
            "result": "The results were even more insane",
        },
    )

>>> result
{"analysis_id": "A-1234567890"}

`delete_analysis(project, analysis_id)` ¶

Delete an analysis in a project.

PARAMETER	DESCRIPTION
`project`	Name of the project. TYPE: `str`
`analysis_id`	Unique identifier for the analysis. TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing the Analysis ID of the deleted analysis.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    result = client.delete_analysis(
        project="project",
        analysis_id="A-1234567890",
    )

>>> result
{"analysis_id": "A-1234567890"}

`register(domain, first_name, last_name, email, site, password)` `classmethod` ¶

Create a new user.

PARAMETER	DESCRIPTION
`domain`	Name of the domain. TYPE: `str`
`first_name`	First name of the user. TYPE: `str`
`last_name`	Last name of the user. TYPE: `str`
`email`	Email address of the user. TYPE: `str`
`site`	Name of the site. TYPE: `str`
`password`	Password for the user. TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing the user's information.

Examples:

import os
from onyx import OnyxClient, OnyxEnv

registration = OnyxClient.register(
    domain=os.environ[OnyxEnv.DOMAIN],
    first_name="Bill",
    last_name="Will",
    email="bill@email.com",
    site="site",
    password="pass123",
)

>>> registration
{
    "username": "onyx-willb",
    "site": "site",
    "email": "bill@email.com",
    "first_name": "Bill",
    "last_name": "Will",
}

`login()` ¶

Log in the user.

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing the user's authentication token and it's expiry.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    username=os.environ[OnyxEnv.USERNAME],
    password=os.environ[OnyxEnv.PASSWORD],
)

with OnyxClient(config) as client:
    token = client.login()

>>> token
{
    "expiry": "2024-01-01T00:00:00.000000Z",
    "token": "abc123",
}

`logout()` ¶

Log out the user.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    client.logout()

`logoutall()` ¶

Log out the user in all clients.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    client.logoutall()

`profile()` ¶

View the user's information.

RETURNS	DESCRIPTION
`Dict[str, str]`	Dict containing the user's information.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    profile = client.profile()

>>> profile
{
    "username": "user",
    "site": "site",
    "email": "user@email.com",
}

`activity()` ¶

View the user's latest activity.

RETURNS	DESCRIPTION
`List[Dict[str, Any]]`	List of the user's latest activity.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    activity = client.activity()

>>> activity
[
    {
        "date": "2023-01-01T00:00:00.000000Z",
        "address": "127.0.0.1",
        "endpoint": "/projects/project/",
        "method": "POST",
        "status": 400,
        "exec_time": 29,
        "error_messages" : "b'{"status":"fail","code":400,"messages":{"site":["Select a valid choice."]}}'",
    },
    {
        "timestamp": "2023-01-02T00:00:00.000000Z",
        "address": "127.0.0.1",
        "endpoint": "/accounts/activity/",
        "method": "GET",
        "status": 200,
        "exec_time": 22,
        "error_messages": "",
    },
]

`approve(username)` ¶

Approve another user.

PARAMETER	DESCRIPTION
`username`	Username of the user to be approved. TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict confirming user approval success.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    approval = client.approve("waiting_user")

>>> approval
{
    "username": "waiting_user",
    "is_approved": True,
}

`waiting()` ¶

Get users waiting for approval.

RETURNS	DESCRIPTION
`List[Dict[str, Any]]`	List of users waiting for approval.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    users = client.waiting()

>>> users
[
    {
        "username": "waiting_user",
        "site": "site",
        "email": "waiting_user@email.com",
        "date_joined": "2023-01-01T00:00:00.000000Z",
    }
]

`site_users()` ¶

Get users within the site of the requesting user.

RETURNS	DESCRIPTION
`List[Dict[str, Any]]`	List of users within the site of the requesting user.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config):
    users = client.site_users()

>>> users
[
    {
        "username": "user",
        "site": "site",
        "email": "user@email.com",
    }
]

`all_users()` ¶

Get all users.

RETURNS	DESCRIPTION
`List[Dict[str, Any]]`	List of all users.

Examples:

import os
from onyx import OnyxConfig, OnyxEnv, OnyxClient

config = OnyxConfig(
    domain=os.environ[OnyxEnv.DOMAIN],
    token=os.environ[OnyxEnv.TOKEN],
)

with OnyxClient(config) as client:
    users = client.all_users()

>>> users
[
    {
        "username": "user",
        "site": "site",
        "email": "user@email.com",
    },
    {
        "username": "another_user",
        "site": "another_site",
        "email": "another_user@email.com",
    },
]

OnyxClient

__init__(config) ¶

projects() ¶

types() ¶

lookups() ¶

fields(project) ¶

choices(project, field) ¶

get(project, climb_id=None, fields=None, include=None, exclude=None) ¶

filter(project, fields=None, include=None, exclude=None, summarise=None, **kwargs) ¶

query(project, query=None, include=None, exclude=None, summarise=None) ¶

to_csv(csv_file, data, delimiter=None) classmethod ¶

history(project, climb_id) ¶

analyses(project, climb_id) ¶

identify(project, field, value, site=None) ¶

create(project, fields, test=False) ¶

update(project, climb_id, fields=None, test=False) ¶

delete(project, climb_id) ¶

csv_create(project, csv_file, fields=None, delimiter=None, multiline=False, test=False) ¶

csv_update(project, csv_file, fields=None, delimiter=None, multiline=False, test=False) ¶

csv_delete(project, csv_file, delimiter=None, multiline=False) ¶

analysis_fields(project) ¶

analysis_choices(project, field) ¶

get_analysis(project, analysis_id=None, fields=None, include=None, exclude=None) ¶

filter_analysis(project, fields=None, include=None, exclude=None, summarise=None, **kwargs) ¶

analysis_history(project, analysis_id) ¶

analysis_records(project, analysis_id) ¶

create_analysis(project, fields, test=False) ¶

update_analysis(project, analysis_id, fields=None, test=False) ¶

delete_analysis(project, analysis_id) ¶

register(domain, first_name, last_name, email, site, password) classmethod ¶

login() ¶

logout() ¶

logoutall() ¶

profile() ¶

activity() ¶

approve(username) ¶

waiting() ¶

site_users() ¶

all_users() ¶

`init(config)` ¶

`projects()` ¶

`types()` ¶

`lookups()` ¶

`fields(project)` ¶

`choices(project, field)` ¶

`get(project, climb_id=None, fields=None, include=None, exclude=None)` ¶

`filter(project, fields=None, include=None, exclude=None, summarise=None, **kwargs)` ¶

`query(project, query=None, include=None, exclude=None, summarise=None)` ¶

`to_csv(csv_file, data, delimiter=None)` `classmethod` ¶

`history(project, climb_id)` ¶

`analyses(project, climb_id)` ¶

`identify(project, field, value, site=None)` ¶

`create(project, fields, test=False)` ¶

`update(project, climb_id, fields=None, test=False)` ¶

`delete(project, climb_id)` ¶

`csv_create(project, csv_file, fields=None, delimiter=None, multiline=False, test=False)` ¶

`csv_update(project, csv_file, fields=None, delimiter=None, multiline=False, test=False)` ¶

`csv_delete(project, csv_file, delimiter=None, multiline=False)` ¶

`analysis_fields(project)` ¶

`analysis_choices(project, field)` ¶

`get_analysis(project, analysis_id=None, fields=None, include=None, exclude=None)` ¶

`filter_analysis(project, fields=None, include=None, exclude=None, summarise=None, **kwargs)` ¶

`analysis_history(project, analysis_id)` ¶

`analysis_records(project, analysis_id)` ¶

`create_analysis(project, fields, test=False)` ¶

`update_analysis(project, analysis_id, fields=None, test=False)` ¶

`delete_analysis(project, analysis_id)` ¶

`register(domain, first_name, last_name, email, site, password)` `classmethod` ¶

`login()` ¶

`logout()` ¶

`logoutall()` ¶

`profile()` ¶

`activity()` ¶

`approve(username)` ¶

`waiting()` ¶

`site_users()` ¶

`all_users()` ¶