Python driver

Python logo

This section describes the Fauna open source Python driver, which provides the resource required to interact with Fauna.

Current stable version

4.3.1

Repository

fauna/faunadb-python

Installation

pip install faunadb

Compatibility

The following versions of Python are supported:

  • Python 3.5

  • Python 3.6

  • Python 3.7

  • Python 3.8

  • Python 3.9

Usage

from faunadb import query as q
from faunadb.objects import Ref
from faunadb.client import FaunaClient

client = FaunaClient(
  secret="YOUR_FAUNA_SECRET",
  # NOTE: Use the correct endpoint for your database's Region Group.
  endpoint="https://db.fauna.com/",
)

indexes = client.query(q.paginate(q.indexes()))

print(indexes)

See Connections for more details on creating client connections.

Event streaming

This section demonstrates how to subscribe to change events. To learn more, see Event streaming.

There are two kinds of event streaming:

  1. Document streaming

  2. Set streaming

The code required to subscribe to each type is similar. The main difference is the type of Reference involved in the subscription, and the kinds of events that are included in the stream.

There is a cost in compute operations to hold a stream open, or to repeatedly start a stream that fails.

See Billing for details.

Document streaming

The following example subscribes to change events for a document:

client = FaunaClient(
  secret=secret,
  domain=o.hostname,
  port=o.port,
  scheme=o.scheme
)

# Define a handler for the stream start event
def on_start(event):
    print("started stream at %s"%(event.txn))

# Define a handler for the stream's version events
def on_version(event):
    print("on_version event at %s"%(event.txn))
    print("version event: %s"%(event.event))

# Define a handler for any stream errors that might occur
def on_error(event):
    print("Received error event %s"%(event))

# Define the stream options to use
options = {
  # "fields": <array of fields to return from stream event objects>,
  # Valid fields are ["diff", "prev", "document", "action"]
}

# Define a reference to the document that we want to stream
# Note that the Scores collection must already exist
ref = q.ref(q.collection("Scores"), "1")

# Subscribe to the stream
stream = client.stream(
  ref,
  options,
  on_start,
  on_error,
  on_version
)

# Start the subscription. As events arrive, the event handlers are
# called.
stream.start()

Before you run the example:

  1. Set the FAUNADB_SECRET environment variable, and optionally the FAUNADB_ENDPOINT environment variable (if you are using Region Groups or Fauna Dev).

  2. The collection Scores must exist.

Once the example is running, you can use the Fauna Dashboard, or another client application, to create or update the target document and watch the events arrive as the changes are made.

For example, if the document does not yet exist, you could run this query in the Fauna Dashboard Shell:

Create(Ref(Collection("Scores"), "1"), { data: { scores: [1, 2, 3] }})

Once the document exists, you could run this query:

Update(Ref(Collection("Scores"), "1"), { data: { scores: [5, 2, 3] }})

The streaming example waits indefinitely for events. Use Ctrl+C to terminate the program.

Set streaming

The following example subscribes to change events for a set:

client = FaunaClient(
  secret=secret,
  endpoint=endpoint
)

# Define a handler for the stream start event
def on_start(event):
    print("started stream at %s"%(event.txn))

# Define a handler for the stream's set events
def on_set(event):
    print("on_set event at %s"%(event.txn))
    print("set event: %s"%(event.event))

# Define a handler for any stream errors that might occur
def on_error(event):
    print("Received error event %s"%(event))

# Define the reference to the target set
setref = q.documents(q.collection("Scores"))

# Define the stream fields to include
options = { "fields": ["action", "document", "index"] }

# Subscribe to the stream
stream = client.stream(
  setref,
  options,
  on_start,
  on_error,
  None, # no version event handler required for set streaming
  None, # no history event handler required for set streaming
  on_set
)

# Start the subscription. As events arrive, the event handlers are
# called.
stream.start()

Before you run the example:

  1. Set the FAUNADB_SECRET environment variable, and optionally the FAUNADB_ENDPOINT environment variable (if you are using Region Groups or Fauna Dev).

  2. The collection Scores must exist.

Once the example is running, you can use the Fauna Dashboard, or another client application, to add or delete documents in the "Scores" collection and watch the events arrive as the changes are made. For example, you could run this query in the Fauna Dashboard's Shell:

Create(Collection("Scores"), { data: { scores: [5, 6, 7] }})

The streaming example waits indefinitely for events. Use Ctrl+C to terminate the program.

Next steps

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!