ouro-py 0.8.0

The official Python library for the Ouro API

ouro-py

The Ouro Python library provides convenient access to the Ouro REST API from any Python 3.7+ application. Visit Ouro to learn more about the Ouro platform.

Documentation

The REST API documentation can be found on ouro.foundation/docs/developers/api.

Installation

# install from PyPI
pip install ouro-py

Usage

Generate an API key from your account settings by going to ouro.foundation/settings/api-keys.

Set your Ouro environment variables in a dotenv file, or using the shell:

export OURO_API_KEY="your_api_key"

Init client:

import os
from ouro import Ouro

api_key = os.environ.get("OURO_API_KEY")
ouro = Ouro(api_key=api_key)

Use the client to interface with the Ouro framework.

Create a dataset

rows = [
    {"name": "Bob", "age": 30},
    {"name": "Alice", "age": 27},
    {"name": "Matt", "age": 26},
]

res = ouro.datasets.create(
    data=rows,  # also accepts a Pandas DataFrame or a single dict row
    name="your_dataset_name",
    description="your_dataset_description",
    visibility="private",
)

data is required for datasets.create(...) and must include at least one row and one column.

Read a dataset

id = "3d82308b-0747-45e4-8045-c8f7d2f6c0a6" # penguins dataset

# Retrieve a dataset
dataset = ouro.datasets.retrieve(id)

# Read dataset's data as a Pandas DataFrame
df = ouro.datasets.query(id)

Run SQL against a dataset

# Pass a SQL string as the 2nd arg to query(). Use {{table}} as the table
# placeholder; read-only enforced server-side, 10s statement timeout.
df = ouro.datasets.query(id, "SELECT species, count(*) AS n FROM {{table}} GROUP BY species")

Update a dataset

id = "3d82308b-0747-45e4-8045-c8f7d2f6c0a6"
data_update = [
    {"name": "Bob", "age": 30},
    {"name": "Alice", "age": 27},
    {"name": "Matt", "age": 26},
]

update = {
    "visibility": "private",
    "data": data_update,  # also accepts a DataFrame or single dict row
}
data = ouro.datasets.update("018f86da-b1be-7099-9556-fe88fb6882c3", **update)

Save a dataset view

view = ouro.datasets.create_view(
    "3d82308b-0747-45e4-8045-c8f7d2f6c0a6",
    name="Age Distribution",
    sql_query="select age, count(*) as total from {{table}} group by age order by age",
    engine_type="recharts_json",
    config={
        "type": "bar",
        "xAxis": {"dataKey": "age", "type": "category"},
        "series": [{"dataKey": "total", "name": "People"}],
    },
)

views = ouro.datasets.list_views("3d82308b-0747-45e4-8045-c8f7d2f6c0a6")

Create a post

content = ouro.posts.Editor()
content.new_header(level=1, text="Hello World")
content.new_paragraph(text="This is a paragraph written in code.")

post = ouro.posts.create(
    content=content,
    name="Hello World",
    description="This is a post from the Python SDK",
    visibility="public",
)

You can also create a post from a local markdown file:

post = ouro.posts.create(
    name="Post From Markdown",
    content_path="/absolute/path/to/post.md",
    visibility="private",
)

Embed generated files in a post

Use partial assets to embed files that don't exist on the platform yet. The backend will materialise them into real file assets when the post is saved.

# Build a partial file payload from a local file
partial = ouro.files.partial_from_file(
    "/tmp/energy_curve.html",
    name="Energy curve",
    description="Energy vs. optimisation step",
    content_type="text/html",
)

# Or from raw bytes
partial = ouro.files.partial_from_bytes(
    html_bytes,
    "energy_curve.html",
    name="Energy curve",
    description="Energy vs. optimisation step",
)

# Embed it in a post
editor = ouro.posts.Editor()
editor.new_header(level=2, text="Results")
editor.new_partial_asset(partial, view_mode="preview")

post = ouro.posts.create(
    content=editor,
    name="Simulation Report",
    visibility="private",
)

partial_from_file and partial_from_bytes infer the MIME type and extension automatically when content_type is omitted. Pass an explicit id to new_partial_asset if you need a stable identifier for the embedded node.

Read a post

id = "b9ff1bfd-b3ae-4e92-9afc-70b1e1e2011a" # The post id

post = ouro.posts.retrieve(id)

Update a post

id = "b9ff1bfd-b3ae-4e92-9afc-70b1e1e2011a" # The post id

new_content = ouro.posts.Editor()
new_content.new_header(level=1, text="Hello World")
new_content.new_paragraph(text="This is a paragraph, but different this time.")

update = {
    "name": "Hello World",
    "visibility": "public",
    "content": new_content,
}
post = ouro.posts.update(id, **update)

Download any asset

result = ouro.assets.download(
    "3d82308b-0747-45e4-8045-c8f7d2f6c0a6",
    output_path="./downloads/",
)

print(result["path"])

assets.download(...) saves the asset to disk and returns the saved path, filename, content type, and byte count. Files download as their original bytes, datasets as .csv, and posts as .html.

Read the full API docs at ouro.foundation/docs/developers/api.

Contributing

Contributing to the Python library is a great way to get involved with the Ouro community. Reach out to us on our Github Discussions page if you want to get involved.

Set up a Local Development Environment

Clone the Repository

git clone [e-mail]:ourofoundation/ouro-py.git
cd ouro-py

Create and Activate a Virtual Environment

We recommend activating your virtual environment. Click here for more about Python virtual environments and working with conda and poetry.

Using venv (Python 3 built-in):

python3 -m venv env
source env/bin/activate  # On Windows, use .\env\Scripts\activate

Using conda:

conda create --name ouro-py
conda activate ouro-py

PyPi installation

Install the package (for > Python 3.7):

# with pip
pip install ouro-py

Local installation

You can also install locally after cloning this repo. Install Development mode with pip install -e, which makes it so when you edit the source code the changes will be reflected in your python module.

Badges