PyDirectus: Python API Wrapper for Directus

PyDirectus is a simple and lightweight Python REST API wrapper for Directus. It provides methods and typed dicts to work with items and files and is easily extensible. It also handles authentication and re-authentication.

The low-level rest adapter is based on this series of blog posts by @PretzelLogix!

Important

Please be aware that PyDirectus is still under active development and some parts may be subject to change in the future!

Installation

pip install git+https://github.com/johind/pydirectus

Getting Started

To get started with PyDirectus, create an instance of the DirectusClient class by providing your Directus instance's hostname. You can also include optional parameters for authentication, SSL verification, and logging.

from pydirectus import DirectusClient

directus = DirectusClient(hostname="http://0.0.0.0:8055")

Authentication

The authentication process is done automatically, and you have a couple of options to choose from:

• Static Token: Provide a static token for simple authentication that bypasses the logic of the authentication process.
• Username and Password: Use your Directus username and password for a more secure authentication.

directus = DirectusClient(
    hostname="http://0.0.0.0:8055",
    static_token="your_static_token",
    # OR
    username="your_username",
    password="your_password",
)

Note

If you use both types of authentication, a static token takes precedence.

Making a request

Now that you have your PyDirectus client set up, making requests is easy. Let's fetch items from a collection:

items = directus.read_items("articles")

You can perform various operations like reading, creating, updating, and deleting items and files using the provided methods in the DirectusClient.

Tip

The available query parameters align with the global parameters outlined in the Directus documentation.

Examples

Reading Items

# Retrieve the latest 10 items from the articles collection
items = directus.read_items("articles", query={"limit": 10})

# Fetch items that match specific filter criteria
filtered_items = directus.read_items(
    collection="articles",
    query={"filter": {"author": {"_eq": "Beff Jezos"}}},
)

Reading an Item by ID

item = directus.read_item(collection="articles", id="53356")

Creating an Item

new_item_data = {"field1": "value1", "field2": "value2"}
created_item = directus.create_item("your_collection", data=new_item_data)

Updating an Item

updated_item_data = {"field1": "new_value1"}
updated_item = directus.update_item(
    collection="your_collection", id="item_id", data=updated_item_data
)

Deleting an Item

directus.delete_item(collection="your_collection", id="item_id")

Working with files

The method scheme introduced earlier also applies to other tables, such as the files

# Retrieve the latest 5 files
files = directus.read_files(query={"limit": 5})

Currently, only existing files stored in the directory can be added. Uploading a file is not possible yet. This feature will be added soon!

file_data: File = {
    "storage": "local",
    "filename_disk": "demo/big-buck-bunny.mp4",
    "filename_download": "big-buck-bunny.mp4",
    "title": "Big Buck Bunny Demo",
    "type": "video/mp4",
    "filesize": 24252243, # in bytes
    "width": 1920,
    "height": 1080,
    "duration": 596047, # in milliseconds
    "metadata": {"frame_rate": 25.0}, # optional example
}

created_file = directus.create_file(file_data)

To learn more about the client, refer to the methods provided in the DirectusClient!

Feel free to report issues on GitHub.