# sea-serpent
A dataframe-like wrapper around the [SeaTable](https://seatable.io/en/) API.
This library tries to make interacting with SeaTables as if you were working
with a local pandas DataFrame.
Some notes:
- This library is at an early stage and the interface might still change somewhat.
- For convenience and ease of access we're using names to identify tables,
columns and bases. Hence you should avoid duplicate names if at all possible.
## Install
From PyPI:
```bash
pip3 install sea-serpent
```
Bleeding edge from Github:
```bash
pip3 install git+https://github.com/schlegelp/sea-serpent@main
```
## Examples
### Getting your API (auth) token
```python
>>> import seaserpent as ss
>>> ss.get_auth_token(username='USER',
... password='PASSWORD',
... server='https://cloud.seatable.io')
{'token': 'somelongassstring1234567@£$^@£$^£'}
```
For future use, set your default server and auth token as `SEATABLE_SERVER` and
`SEATABLE_TOKEN` environment variable, respectively.
### Initializing a table
`Table` works as connection to a single SeaTable table. If its name is unique,
you can initialize the connection with just the name:
```python
>>> import seaserpent as ss
>>> # Initialize the table
>>> # (if there are multiple tables with this name you need to provide the base too)
>>> table = ss.Table(table='MyTable')
>>> table
SeaTable <"MyTable", 10 rows, 2 columns>
>>> # Inspect the first couple rows
>>> table.head()
column1 labels
0 1 A
1 2 B
2 3 C
```
### Fetching data
The `Table` itself doesn't download any of the data. Reading the data works
via an interface similar to `pandas.DataFrames`:
```python
>>> # Fetching a column returns a promise
>>> c = table['column1'] # this works too: c = table.column1
>>> c
Column <column="column1", table="LH_bodies", datatype=number>
>>> # To get the values
>>> c.values
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> # Filters are automatically translated into SQL query
>>> table.loc[table.column1 >= 7]
column1 labels
0 7 H
1 8 I
2 9 J
>>> table.loc[table.labels.isin(['D', 'E']) ]
column1 labels
0 4 D
1 5 E
>>> # Download the whole table as pandas DataFrame
>>> df = table.to_frame()
```
### Adding a column
```python
>>> # First we need to re-initialize the table with write access
>>> table = ss.Table(table='MyTable', read_only=False)
>>> table.add_column(col_name='checked', col_type=bool)
>>> # The column will be empty
>>> table.head()
column1 labels checked
0 1 A None
1 2 B None
2 3 C None
```
### Pushing data to table
```python
>>> # Overwrite the whole column
>>> table['checked'] = False
>>> table.head()
column1 labels checked
0 1 A False
1 2 B False
2 3 C False
>>> # Alternatively pass a list of values
>>> table['checked'] = [False, True, False]
>>> table.head()
column1 labels checked
0 1 A False
1 2 B True
2 3 C False
>>> # Write to a subset of the column
>>> table.loc[:2, 'checked'] = False
>>> table.loc[table.labels == 'C', 'checked'] = True
>>> table.head()
column1 labels checked
0 1 A False
1 2 B False
2 3 C True
>>> # To write only changed values to the table
>>> # (faster & better for logs)
>>> values = table.checked.values
>>> values[0:2] = True # Change only two values
>>> table.checked.update(values)
```
### Deleting a column
```python
>>> table['checked'].delete()
>>> table.head()
column1 labels
0 1 A
1 2 B
2 3 C
>>> # Alternatively you can also clear an entire column
>>> table.checked.clear()
>>> table.head()
column1 labels checked
0 1 A None
1 2 B None
2 3 C None
```
### Creating a new table
Empty table:
```python
>>> table = ss.Table.new(table_name='MyNewTable', base='MyBase')
```
From pandas DataFrame:
```python
>>> table = ss.Table.from_frame(df, table_name='MyNewTable', base='MyBase')
```
### Linking tables
Create links:
```python
>>> table.link(other_table='OtherTable', # name of the other table (must be same base)
... link_on='Column1', # column in this table to link on
... link_on_other='ColumnA', # column in other table to link on
... link_col='OtherTableLinks') # name of column to store links in
```
Create column that pulls data from linked table:
```python
>>> table.add_linked_column(col_name='LinkedData', # name of new column
... link_col='OtherTableLinks', # column with link(s) to other table
... link_on='some_value', # which column in other table to link to
... formula='lookup') # how to aggregate data (lookup, mean, max, etc)
```
## Known limitations & oddities
1. 64 bit integers/floats are truncated when writing to a table. I suspect this
happens on the server side when decoding the JSON payload because manually
entering large numbers through the web interface works perfectly well
(copy-pasting still fails though). Hence, `seaserpent` quietly downcasts 64
bit to 32 bit if possible and failing that converts to strings before uploading.
2. The web interface appears to only show floats up to the 8th decimal. In the
database the precision must be higher though because I have successfully
written 1e-128 floats.
3. Infinite values (i.e. `np.inf`) raise an error when trying to write.
4. Cells manually cleared through the UI return empty strings (``''``). By
default, ``sea-serpent`` will convert these to ``None`` where possible.
Raw data
{
"_id": null,
"home_page": "https://github.com/schlegelp/sea-serpent",
"name": "sea-serpent",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "SeaTable API interface dataframe",
"author": "Philipp Schlegel",
"author_email": "pms70@cam.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/17/a9/e308b5fef5b76721bd93968c62fb96bab7754446e20bc7dd183c7aeceb42/sea-serpent-0.4.0.tar.gz",
"platform": null,
"description": "# sea-serpent\nA dataframe-like wrapper around the [SeaTable](https://seatable.io/en/) API.\n\nThis library tries to make interacting with SeaTables as if you were working\nwith a local pandas DataFrame.\n\nSome notes:\n- This library is at an early stage and the interface might still change somewhat.\n- For convenience and ease of access we're using names to identify tables,\n columns and bases. Hence you should avoid duplicate names if at all possible.\n\n## Install\n\nFrom PyPI:\n\n```bash\npip3 install sea-serpent\n```\n\nBleeding edge from Github:\n\n```bash\npip3 install git+https://github.com/schlegelp/sea-serpent@main\n```\n\n## Examples\n\n### Getting your API (auth) token\n\n```python\n>>> import seaserpent as ss\n>>> ss.get_auth_token(username='USER',\n... password='PASSWORD',\n... server='https://cloud.seatable.io')\n{'token': 'somelongassstring1234567@\u00a3$^@\u00a3$^\u00a3'}\n```\n\nFor future use, set your default server and auth token as `SEATABLE_SERVER` and\n`SEATABLE_TOKEN` environment variable, respectively.\n\n### Initializing a table\n\n`Table` works as connection to a single SeaTable table. If its name is unique,\nyou can initialize the connection with just the name:\n\n```python\n>>> import seaserpent as ss\n>>> # Initialize the table\n>>> # (if there are multiple tables with this name you need to provide the base too)\n>>> table = ss.Table(table='MyTable')\n>>> table\nSeaTable <\"MyTable\", 10 rows, 2 columns>\n>>> # Inspect the first couple rows\n>>> table.head()\n column1 labels\n0 1 A\n1 2 B\n2 3 C\n```\n\n### Fetching data\n\nThe `Table` itself doesn't download any of the data. Reading the data works\nvia an interface similar to `pandas.DataFrames`:\n\n```python\n>>> # Fetching a column returns a promise\n>>> c = table['column1'] # this works too: c = table.column1\n>>> c\nColumn <column=\"column1\", table=\"LH_bodies\", datatype=number>\n>>> # To get the values\n>>> c.values\n[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n>>> # Filters are automatically translated into SQL query\n>>> table.loc[table.column1 >= 7]\n column1 labels\n0 7 H\n1 8 I\n2 9 J\n>>> table.loc[table.labels.isin(['D', 'E']) ]\n column1 labels\n0 4 D\n1 5 E\n>>> # Download the whole table as pandas DataFrame\n>>> df = table.to_frame()\n```\n\n### Adding a column\n\n```python\n>>> # First we need to re-initialize the table with write access\n>>> table = ss.Table(table='MyTable', read_only=False)\n>>> table.add_column(col_name='checked', col_type=bool)\n>>> # The column will be empty\n>>> table.head()\n column1 labels checked\n0 1 A None\n1 2 B None\n2 3 C None\n```\n\n### Pushing data to table\n\n```python\n>>> # Overwrite the whole column\n>>> table['checked'] = False\n>>> table.head()\n column1 labels checked\n0 1 A False\n1 2 B False\n2 3 C False\n>>> # Alternatively pass a list of values\n>>> table['checked'] = [False, True, False]\n>>> table.head()\n column1 labels checked\n0 1 A False\n1 2 B True\n2 3 C False\n>>> # Write to a subset of the column\n>>> table.loc[:2, 'checked'] = False\n>>> table.loc[table.labels == 'C', 'checked'] = True\n>>> table.head()\n column1 labels checked\n0 1 A False\n1 2 B False\n2 3 C True\n>>> # To write only changed values to the table\n>>> # (faster & better for logs)\n>>> values = table.checked.values\n>>> values[0:2] = True # Change only two values\n>>> table.checked.update(values)\n```\n\n### Deleting a column\n\n```python\n>>> table['checked'].delete()\n>>> table.head()\n column1 labels\n0 1 A\n1 2 B\n2 3 C\n>>> # Alternatively you can also clear an entire column\n>>> table.checked.clear()\n>>> table.head()\n column1 labels checked\n0 1 A None\n1 2 B None\n2 3 C None\n```\n\n### Creating a new table\n\nEmpty table:\n\n```python\n>>> table = ss.Table.new(table_name='MyNewTable', base='MyBase')\n```\n\nFrom pandas DataFrame:\n\n```python\n>>> table = ss.Table.from_frame(df, table_name='MyNewTable', base='MyBase')\n```\n\n### Linking tables\n\nCreate links:\n\n```python\n>>> table.link(other_table='OtherTable', # name of the other table (must be same base)\n... link_on='Column1', # column in this table to link on\n... link_on_other='ColumnA', # column in other table to link on\n... link_col='OtherTableLinks') # name of column to store links in\n```\n\nCreate column that pulls data from linked table:\n\n```python\n>>> table.add_linked_column(col_name='LinkedData', # name of new column\n... link_col='OtherTableLinks', # column with link(s) to other table\n... link_on='some_value', # which column in other table to link to\n... formula='lookup') # how to aggregate data (lookup, mean, max, etc)\n```\n\n## Known limitations & oddities\n\n1. 64 bit integers/floats are truncated when writing to a table. I suspect this\n happens on the server side when decoding the JSON payload because manually\n entering large numbers through the web interface works perfectly well\n (copy-pasting still fails though). Hence, `seaserpent` quietly downcasts 64\n bit to 32 bit if possible and failing that converts to strings before uploading.\n2. The web interface appears to only show floats up to the 8th decimal. In the\n database the precision must be higher though because I have successfully\n written 1e-128 floats.\n3. Infinite values (i.e. `np.inf`) raise an error when trying to write.\n4. Cells manually cleared through the UI return empty strings (``''``). By\n default, ``sea-serpent`` will convert these to ``None`` where possible.\n",
"bugtrack_url": null,
"license": "GNU GPL V3",
"summary": "Dataframe-like wrapper for SeaTable API.",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://github.com/schlegelp/sea-serpent",
"Source": "https://github.com/schlegelp/sea-serpent"
},
"split_keywords": [
"seatable",
"api",
"interface",
"dataframe"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d975e38361c97e8adff90034b8b63ae18227ce432e29f3c8676e4c2d97aaed99",
"md5": "8328653f4e364d6d3df79380f051b09b",
"sha256": "955be3153f7e188f29117ca39cbefd3adc176b5e2e38ab5d8814421281c37434"
},
"downloads": -1,
"filename": "sea_serpent-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8328653f4e364d6d3df79380f051b09b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 45888,
"upload_time": "2024-01-18T16:38:15",
"upload_time_iso_8601": "2024-01-18T16:38:15.489112Z",
"url": "https://files.pythonhosted.org/packages/d9/75/e38361c97e8adff90034b8b63ae18227ce432e29f3c8676e4c2d97aaed99/sea_serpent-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "17a9e308b5fef5b76721bd93968c62fb96bab7754446e20bc7dd183c7aeceb42",
"md5": "aa278bb82b82b28abd9475df9b72f0fa",
"sha256": "a947a7031de1e9c4d23198da90ae9c2a95d4ed133eb520a45b72a12eb9de27c3"
},
"downloads": -1,
"filename": "sea-serpent-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "aa278bb82b82b28abd9475df9b72f0fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 44370,
"upload_time": "2024-01-18T16:38:16",
"upload_time_iso_8601": "2024-01-18T16:38:16.744355Z",
"url": "https://files.pythonhosted.org/packages/17/a9/e308b5fef5b76721bd93968c62fb96bab7754446e20bc7dd183c7aeceb42/sea-serpent-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-18 16:38:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "schlegelp",
"github_project": "sea-serpent",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pandas",
"specs": []
},
{
"name": "seatable-api",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "tqdm",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "PyJWT",
"specs": []
}
],
"lcname": "sea-serpent"
}
JSON
