# SDK (python)

SDK is the toolkit with prebuilt Labii components that developers use to interact with Labii APIs. Full documentation available at <https://docs.labii.com/api/overview>

## Usage <a href="#usage" id="usage"></a>

1. Install the Labii SDK

```
pip install labii-sdk
```

2\. Import the package

```
from labii_sdk.sdk import LabiiObject
```

3\. Initial the API object

```
labii = LabiiObject(
    api_key="xxx",
    organization__sid="xxx"
)
```

4\. Start querying

```
# get a list of tables
labii.Tables.list()
```

## Initial SDK <a href="#initial-sdk" id="initial-sdk"></a>

During SDK initiation, the following parameters can be customized:

* `base_url`, the server base URL, defaults to <https://www.labii.dev>. If you are using a different data center, make sure to change the `base_url` setting.
* `api_key` , the API Key to get authenticated.
* `organization__sid`, your organization sid. You can find it by logging into Labii (<https://www.labii.com/login/>) and going to Side menu -> Settings -> Organization -> Sid
* `api,` the APIObject. If a new APIObject is not provided, it will be automatically created. Utilize this functionality when you require authentication for the API before initializing a Labii Object.

```
labii = LabiiObject(
    base_url="https://www.labii.dev",
    api_key="xxx"
    organization__sid=None
    api=None
)
```

## Objects <a href="#objects" id="objects"></a>

Labii objects for interaction. Learn more at <https://docs.labii.com/api/overview#objects>

* Profile
* APIKey
* Organization
* Application
* Subscription
* People
* Team
* SAML
* OrganizationWidget
* Backup
* Project
* ProjectMember
* Table
* Column
* Section
* Filter
* Record
* Cell
* Version
* Visitor
* Activity
* Workflow
* Step
* Widget
* Dashboard
* Notification

## Methods <a href="#methods" id="methods"></a>

A list of methods for interacting with objects.

### **create**

Create a object.

* `data` (dict), a JSON dict data to post. Learn more at <https://docs.labii.com/api/methods>
* `query` (optional), additional query to limit the results.

```
# Create a project
labii.Project.create({name="test", ...})

# Create a table
labii.Table.create({name_singular="test", ...})

# Create a row
labii.Record.create{{name="test", ...}, query="table__sid=xxx"}
```

### **retrieve**

Return a object

* `sid`, the sid of the object
* `query` (optional), additional query to limit the results.

```
# Return a project
labii.Project.retrieve("psvy0a40x18c0rwBGLQV1")

# Return a record
labii.Row.retrieve("psvy0a40x18c0rwBGLQV1")
```

### **list**

Get a list of objects

* `page` (default=1), the page number to return.
* `page_size` (default=10), the number of items to be paginated.
* `all_pages` (bool, default=False), Whether all pages should be returned. When False, only return the data for the first page. Only applies to list views.
* `level` (default to "organization"), the scope of records to retrieve. Learn more at <https://docs.labii.com/api/overview#levels>
* `serializer` (default to "list"), the scope of fields of the return data. Learn more at <https://docs.labii.com/api/overview#serializer>
  * **name**, return only sid and name, very fast
  * **list**, return selected fields of the objects, fast
  * **detail**, return all fields of the objects, slow
* `query` (optional), additional query to limit the results.

```
# Return first page of experiment records
labii.Row.list(
    page=1,
    page_size=10,
    all_pages=False,
    level="organization",
    serializer="name",
    query="table__sid=psvy0a40x18c0rwBGLQV1&is_archived=false"
)

# Return list of projects
labii.Project.list()
```

### **modify**

Edit an object

* `sid`, the sid of the object
* `data` (dict), a JSON dict data to post. Learn more at <https://docs.labii.com/api/methods>
* `query` (optional), additional query to limit the results.

```
# modify the name of a project
labii.Project.modify(
    sid="psvy0a40x18c0rwBGLQV1",
    data={"name": "new name"}
)
```

### **delete**

Remove an object

* `sid`, the sid of the object
* `query` (optional), additional query to limit the results.

{% hint style="info" %}
Not all objects can be deleted. A 405 error will be displayed if an object cannot be deleted.
{% endhint %}

```
# remove the permission of a user
labii.ProjectMember.delete("psvy0a40x18c0rwBGLQV1")
```

## File operations

Labii also developed a few functions to facilitate the file uploading.

### upload

Upload a file to Labii

* `file_path`, the full file path
* `projects` , list of projects in the format of \[{"sid": "project\_\_sid"}]

```python
# upload a file
from labii_sdk.sdk import LabiiObject
labii = LabiiObject(api_key="xxx", organization__sid="xxx")
file_record = labii.upload("/tmp/test.txt", [{"sid":"xxx"}])
```

### watch\_folder

You can use this function to watch a particular folder. As soon as the file(s) are present, the function will upload each file to Labii and move the file to the "uploaded" subfolder. This function allows you to upload files generated by a machine/equipment automatically.

{% hint style="info" %}
Version 1.9 or later is required to use this function.
{% endhint %}

* `folder_path`, required, the folder (including the path) to watch. default to current path.
* `projects`, required, list of projects in the format of \[{"sid": "project\_\_sid"}]
* `interval`, optional, time interval to check the folder, default to 5 seconds.

```python
// Watch a results folder
from labii_sdk.sdk import LabiiObject
labii = LabiiObject(api_key="xxx", organization__sid="xxx")
labii.watch_folder(folder_path="./results", [{"sid":"xxx"}])
```

## Other

### Switch organization

Utilize this function for seamlessly transitioning between various organizations. This will prove especially advantageous when transitioning from a test organization to a production organization.

```python
// switch organization
from labii_sdk.sdk import LabiiObject
labii = LabiiObject(api_key="xxx", organization__sid="xxx")
labii.switch_organization(organization__sid)
```

### Get columns

When you're in the process of generating a new record, it's frequently necessary to have the column SID in order to prepare the data object. In Python, obtaining the index of an object in an array isn't always a straightforward task. This is why we have developed this function to simplify the coding process when working with the Labii SDK.

```python
from labii_sdk.sdk import LabiiObject
labii = LabiiObject(api_key="xxx", organization__sid="xxx")

# get sample table
table = labii.Table.list(query="name_singular=sample", serializer="name")["results"][0]
columns = labii.get_columns(f"table__sid={table['sid']}&name__in=volume,concentration,storage")
print(columns)

{
    "volume": "70cf0a40x459cb9dinsxCH",
    "concentration": "9beh0a40x459cdafkpuzEJ",
    "source_samples": "0cfi0a40x459cebglqvAFK",
    "storage": "behk0a40x459d0dinsxCHM",
    "storage_coordinates": "cfil0a40x459d1ejotyDIN"
}
```