# Noloco Python SDK

Our Python SDK provides CRUD operations over your Noloco Collections.

## Installation

The SDK is published on PyPI and can be installed with `pip`.

```
$ pip install noloco
```

## Getting started

The examples here will be based around two example collections, one called `author` and one called `book`.

The `author` collection will have this schema:

```
{
    'firstName': 'TEXT',
    'lastName': 'TEXT'
}
```

The book collection will have the following schema:

```
{
    'title': 'TEXT',
    'author': 'AUTHOR',
    'pageCount': 'INTEGER'
}
```

### Pre-requisites

You will need to know your account API key before you can use the SDK. To find this:
- Open your project dashboard
- Go to the Settings page
- Go to Integrations & API Keys
- Copy your Account API Key

You will also need to know your project name. If you access your site via the Noloco subdomain you can just copy it from the URL as it will be [project-name].noloco.co. If you use a custom domain you will need to look it up:
- Open your project dashboard
- Go to the Settings page
- Go to Domains
- Find the Production subdomain
- This will be [project-name].noloco.co

### Building a client

A client is provided in the SDK through which you can carry out CRUD operations on your collections. You can construct an instance of this client as follows:

```
from noloco.client import Noloco
...
# See pre-requisites above.
account_api_key = ...
project_name = ...
...
client = Noloco(account_api_key, project_name)
```

This construction step might take a few seconds to run. The `Noloco.__init__` method is going to do a few things. Firstly it will use your account API key to lookup your project document, it will then find your project API key from this document and validate it with Noloco. Assuming this is all OK we will cache the data types that exist on your project at the time you constructed your client. If you alter the schema of any data types in your portal, you may notice a slight delay in the next request as we fetch your new data types.

### Creating a record in a collection

To create a new author and then create a new book linked to them you would write the following code:

```
author = client.create('author', {
    'data': {
        'firstName': 'Jane',
        'lastName': 'Doe'
    }
})

book = client.create('book', {
    'data': {
        'title': 'My Biography',
        'author': {
            'connect': {
                'id': author.id
            }
        },
        'pageCount': 500
    },
    'include': {
        'author': True
    }
})
```

You might be wondering what the significance of `{'include': {'author': True}}` is... Whenever we return a record from the API we will always return all the top-level fields (including files) by default. However we do not include relationship fields unless you specifically tell the client to include them in the `options` parameters. Because this call to create a `book` is including `author` in its `options`, when the created `book` is returned, the author relationship will also be included. In an interpreter we can see this:

```
$ print(book)

{
    'id': 1,
    'uuid': ...,
    'createdAt': ...,
    'updatedAt': ...,
    'title': 'My Biography',
    'author': {
        'id': 2,
        'uuid': ...,
        'createdAt': ...,
        'updatedAt': ...,
        'firstName': 'Jane',
        'lastName': 'Doe',
        '__typename': 'Author'
    },
    'pageCount': 500,
    '__typename': 'Book'
}
```

If we had omitted the `include` then the `book` that was returned would have just carried its top-level fields:

```
$ print(book)

{
    'id': ...,
    'uuid': ...,
    'createdAt': ...,
    'updatedAt': ...,
    'title': 'My Biography',
    'pageCount': 500,
    '__typename': 'Book'
}
```

### Reading a single record from a collection

If you know the value of a unique field of a record in a collection then you can read it from the collection:

```
book = client.findUnique('book', {
    'where': {
        'id': {
            'equals': 1
        }
    },
    'include': {
        'author': True
    }
})
```

You can `print` it like we did in the previous example, or you can directly access fields on the result. This is because we wrap all responses in a `Result` class that inherits from `dict`:

```
$ print(book.author.firstName)

Jane
```

### Reading multiple records from a collection

If you do not know the value of a unique field, or you just want to read multiple fields at once then you can do so:

```
book_collection = client.findMany('book', {
    'where': {
        'pageCount': {
            'lt': 250
        }
    },
    'first': 5,
    'order_by': {
        'direction': 'ASC',
        'field': 'id'
    }
})
```

This will return a `CollectionResult` instance. This is a paginated set of results limited to the value of `first` at a time. You can check the total number of records that match your criteria:

```
$ print(book_collection)

{
    'total_count': 51,
    'has_previous_page': False,
    'has_next_page': True,
    'data': [
        {'id': '10', ...},
        {'id': '14', ...},
        {'id': '16', ...},
        {'id': '17', ...},
        {'id': '22', ...},
    ]
}
```

We then provide two methods that let you page through the data:

```
$ print(book_collection.next_page().data)

{
    'total_count': 51,
    'has_previous_page': True,
    'has_next_page': True,
    'data': [
        {'id': '23', ...},
        {'id': '27', ...},
        {'id': '29', ...},
        {'id': '30', ...},
        {'id': '38', ...},
    ]
}

$ print(book_collection.next_page().previous_page())

{
    'total_count': 51,
    'has_previous_page': False,
    'has_next_page': True,
    'data': [
        {'id': '10', ...},
        {'id': '14', ...},
        {'id': '16', ...},
        {'id': '17', ...},
        {'id': '22', ...},
    ]
}
```

### Updating a record in a collection

If you know the ID of a record in a collection then you can update it in the collection:

```
book = client.update('book', 1, {
    'data': {
        'pageCount': 200
    },
    'include': {
        'author': True
    }
})
```

You can `print` it like we did in the previous example, or you can directly access fields on the result. This is because we wrap all responses in a `Result` class that inherits from `dict`:

```
$ print(book)

{
    'id': 1,
    'uuid': ...,
    'createdAt': ...,
    'updatedAt': ...,
    'title': 'My Biography',
    'pageCount': 499,
    '__typename': 'Book'
}
```

### Setting related field values

As you saw in the `create` example, you can connect an existing record to another record when you are creating that other record. The same logic applies to updates

book = client.update('book', 1, {
    'data': {
        'author': {
            'connect': {
                'id': author.id
            }
        },
    },
    'include': {
        'author': True
    }
})

If your collection has a field that accepts multiple linked records, you can set them while creating up updating the record like so: 

review_1 = client.create('review', {
     'data': {
        'name': 'Jane',
        'rating': 5
    }
})

review_2 = client.create('review', {
     'data': {
        'name': 'James',
        'rating': 3
    }
})

book = client.update('book', 1, {
    'data': {
        'reviews': {
            'connect': [
                {
                    'id': review_1.id
                },
                {
                    'id': review_2.id
                },
            }
        },
    },
    'include': {
        'reviews': True
    }
})

### Deleting a record from a collection

Finally, if you know the ID of a record in a collection then you can delete it from the collection:

```
client.delete('book', 1)
```

## Field types

You can use the following table to reference the mapping from Noloco field types onto Python types. For fields that are Python strings requiring a specific format, the format we expect is given here.

| Noloco Field Type | Python Type | Expected Formats           |
|-------------------|-------------|----------------------------|
| Boolean           | bool        |                            |
| Date              | str         | 'YYYY-MM-DDTHH:MM:SS.XXXZ' |
| Decimal           | float       |                            |
| Duration          | str         | 'HH:MM:SS'                 |
| File/Upload       | (see below) |                            |
| Integer           | int         |                            |
| Multiple Option   | list        | ['SCREAMING_SNAKE_CASE']   |
| Single Option     | str         | 'SCREAMING_SNAKE_CASE'     |
| Text              | str         |                            |

### Files

Note that unlike other the types, files have a different Python type depending on whether they are being given as an input or an output.

When you are inputting a file to the SDK to be uploaded, you need to give the SDK an opened file, for example:

```
profile_picture = open('/Users/user/Pictures/profile_picture.jpeg', 'rb')
```

You will need to manage the closing of this file yourself after the SDK is done with it.

When the SDK is outputting a file to you, it will give you a dictionary with information about the file:

```
{
    'id': '...',
    'uuid': '...',
    'fileType': 'IMAGE',
    'url': 'https://app-media.noloco.app/[project-name]/...profile_picture.jpeg',
    'name': '%2FUsers%2Fuser%2FPictures%2Fprofile_picture.jpeg'
}
```

You can use the URL to download the file if you need the contents.
