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.5.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

  • Python 3.10

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.

Tracing

A trace uniquely identifies a transaction flow. In distributed scenarios, a traceparent propagates a contextual identifier, which lets you associate logs from disparate services that participate in the application. The traceparent request header represents a request in a tracing system using a common format. See traceparent.

Fauna supports distributed tracing by allowing you to apply a traceparent header to individual queries. The traceparent request header format is similar to this example:
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01.

Use the identifier in the query response in subsequent queries. If the Fauna query logic is not the main application, you should use the identifier provided by that application and follow the recommended processing model for mutating the identifier.

If you don’t include a traceparent identifier, one is generated for you and attached to the query response.

Tags

You can tag individual queries with identifiers that can be used to associate operations by using the x-fauna-tags header tag.

  • Tags and associated values can be alphanumeric strings and include the underscore (_) character.

  • Tag names can be up to 40 characters, and tag values can be up to 80 characters.

  • You can have up to 25 tags per query.

A query fails with a 400 status code if the tag is invalid.

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!