Python driver

Python logo

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

Current stable version

4.2.0

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",
  domain="db.fauna.com",
  # NOTE: Use the correct domain for your database's Region Group.
  port=443,
  scheme="https"
)

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 very similar. The primary 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 attempt to start a stream that fails for any reason.

See Billing for details.

Document streaming

The following example subscribes to change events for a specific 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. Be sure to 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 modify 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's 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,
  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 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. Be sure to 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

Was this article helpful? 

We're sorry to hear that.
Tell us how we can improve!
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!