Python wrapper for Coda.io API

codaio is in active development stage. Issues and PRs very welcome!

Installation

pip install codaio

Config via environment variables

The following variables will be called from environment where applicable:

• CODA_API_ENDPOINT (default value https://coda.io/apis/v1beta1)
• CODA_API_KEY - your API key to use when initializing document from environment

Quickstart using raw API

Coda class provides a wrapper for all API methods. If API response included a JSON it will be returned as a dictionary from all methods. If it didn't a dictionary {"status": response.status_code} will be returned. If request wasn't successful a CodaError will be raised with details of the API error.

from codaio import Coda

coda = Coda('YOUR_API_KEY')

>>> coda.create_doc('My document')
{'id': 'NEW_DOC_ID', 'type': 'doc', 'href': 'https://coda.io/apis/v1beta1/docs/LINK', 'browserLink': 'https://coda.io/d/LINK', 'name': 'My Document', 'owner': 'your@email', 'createdAt': '2019-08-29T11:36:45.120Z', 'updatedAt': '2019-08-29T11:36:45.272Z'}

For full API reference for Coda class see documentation

Quickstart using codaio objects

codaio implements convenient classes to work with Coda documents: Document, Table, Row, Column and Cell.

from codaio import Coda, Document

# Initialize by providing a coda object directly
coda = Coda('YOUR_API_KEY')

doc = Document('YOUR_DOC_ID', coda=coda)

# Or initialiaze from environment by storing your API key in environment variable `CODA_API_KEY`
doc = Document.from_environment('YOUR_DOC_ID')

doc.list_tables()

table = doc.get_table('TABLE_ID')

Fetching a Row

# You can fetch a row by ID
row  = table['ROW_ID']

Using with Pandas

If you want to load a codaio Table or Row into pandas, you can use the Table.to_dict() or Row.to_dict() methods:

import pandas as pd

df = pd.DataFrame(table.to_dict())

Fetching a Cell

# Or fetch a cell by ROW_ID and COLUMN_ID
cell = table['ROW_ID']['COLUMN_ID']  

# This is equivalent to getting item from a row
cell = row['COLUMN_ID']
# or 
cell = row['COLUMN_NAME']  # This should work fine if COLUMN_NAME is unique, otherwise it will raise AmbiguousColumn error
# or use a Column instance
cell = row[column]

Changing Cell value

row['COLUMN_ID'] = 'foo'
# or
row['Column Name'] = 'foo'

Iterating over rows

# Iterate over rows using IDs -> delete rows that match a condition
for row in table.rows():
    if row['COLUMN_ID'] == 'foo':
        row.delete()

# Iterate over rows using names -> edit cells in rows that match a condition
for row in table.rows():
    if row['Name'] == 'bar':
        row['Value'] = 'spam'

Upserting new row

To upsert a new row you can pass a list of cells to table.upsert_row()

name_cell = Cell(column='COLUMN_ID', value_storage='new_name')
value_cell = Cell(column='COLUMN_ID', value_storage='new_value')

table.upsert_row([name_cell, value_cell])

Upserting multiple new rows

Works like upserting one row, except you pass a list of lists to table.upsert_rows() (rows, not row)

name_cell_a = Cell(column='COLUMN_ID', value_storage='new_name')
value_cell_a = Cell(column='COLUMN_ID', value_storage='new_value')

name_cell_b = Cell(column='COLUMN_ID', value_storage='new_name')
value_cell_b = Cell(column='COLUMN_ID', value_storage='new_value')

table.upsert_rows([[name_cell_a, value_cell_a], [name_cell_b, value_cell_b]])

Updating a row

To update a row use table.update_row(row, cells)

row = table['ROW_ID']

name_cell_a = Cell(column='COLUMN_ID', value_storage='new_name')
value_cell_a = Cell(column='COLUMN_ID', value_storage='new_value')

table.update_row(row, [name_cell_a, value_cell_a])

Documentation

codaio documentation lives at readthedocs.io

Support

Testing

All tests are in the /tests folder. It's a little bit problematic to test against the live API since some responses may take a bit longer, so test results are not reliable enough to use a CI system.

Check out the fixtures if you want to improve the testing process.

Contributing

If you are willing to contribute please go ahead, we can use some help!

Using CI to deploy to PyPi

When a PR is merged to master the CI will try to deploy to pypi.org using poetry. It will succeed only if the version number changed in pyproject.toml.

To do so use poetry's version command. For example:

Bump 0.4.11 to 0.4.12:

poetry version patch

Bump 0.4.11 to 0.5.0:

poetry version minor

Bump 0.4.11 to 1.0.0:

poetry version major