Fauna Python driver for FQL 10+
Project description
See the Fauna Documentation for additional information how to configure and query your databases.
This driver can only be used with FQL X, and is not compatible with earlier versions of FQL. To query your databases with earlier API versions, see the faunadb package.
Installation
pip install fauna
Compatibility
The following versions of Python are supported:
Python 3.9
Python 3.10
Python 3.11
Basic Usage
You can expect a Client instance to have reasonable defaults, like the Fauna endpoint https://db.fauna.com and a global HTTP client, but you will always need to configure a secret.
You can configure your secret by passing it directly to the client or by setting an environment variable.
Supported Environment Variables:
FAUNA_ENDPOINT: The Fauna endpoint to use. For example, http://localhost:8443
FAUNA_SECRET: The Fauna secret to use.
from fauna import fql
from fauna.client import Client
from fauna.encoding import QuerySuccess
from fauna.errors import FaunaException
client = Client()
# The client defaults to using using the value stored FAUNA_SECRET for its secret.
# Either set the FAUNA_SECRET env variable or retrieve it from a secret store.
# As a best practice, don't store your secret directly in your code.
try:
# create a collection
q1 = fql('Collection.create({ name: "Dogs" })')
client.query(q1)
# create a document
q2 = fql('Dogs.create({ name: "Scout" })')
res: QuerySuccess = client.query(q2)
doc = res.data
print(doc)
except FaunaException as e:
# handle errors
print(e)
Query Composition
This driver supports query composition with Python primitives, lists, dicts, and other FQL queries. Serialization to and from user-defined classes is not yet supported—for now, adapt your classes into a dict or list prior to using it in composition.
For FQL templates, denote variables with ${} and pass variables as kwargs to fql(). You can escape a variable by prepending an additional $.
from fauna import fql
from fauna.client import Client
client = Client()
def add_two(x):
return fql("${x} + 2", x=x)
q = fql("${y} + 4", y=add_two(2))
res = client.query(q)
print(res.data) # 8
Document Streaming
Not implemented
Query Stats
Stats are returned on query responses and ServiceErrors.
from fauna import fql
from fauna.client import Client
from fauna.encoding import QuerySuccess, QueryStats
from fauna.errors import ServiceError
client = Client()
def emit_stats(stats: QueryStats):
print(f"Compute Ops: {stats.compute_ops}")
print(f"Read Ops: {stats.read_ops}")
print(f"Write Ops: {stats.write_ops}")
try:
q = fql('Collection.create({ name: "Dogs" })')
qs: QuerySuccess = client.query(q)
emit_stats(qs.stats)
except ServiceError as e:
if e.stats is not None:
emit_stats(e.stats)
# more error handling...
Setup
$ virtualenv venv
$ source venv/bin/activate
$ pip install . .[test] .[lint]
Testing
We use pytest. You can run tests directly or with docker. If you run integration tests directly, you must have fauna running locally.
If you want to run fauna, then run integration tests separately:
$ make docker-fauna
$ source venv/bin/activate
$ make install
$ make integration-test
To run unit tests locally:
$ source venv/bin/activate
$ make install
$ make unit-test
To stand up a container and run all tests at the same time:
$ make docker-test
See the Makefile for more.
Coverage
$ source venv/bin/activate
$ make coverage
Contribute
GitHub pull requests are very welcome.
License
Copyright 2023 Fauna, Inc.
Licensed under the Mozilla Public License, Version 2.0 (the “License”); you may not use this software except in compliance with the License. You can obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for fauna-0.6.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d23719bd8e21ea6429bf8436f6ed1ffd4b50d7964a9c0ab45894feb29ac2f77d |
|
MD5 | 273513d9799b2c5578eca667c6935e85 |
|
BLAKE2b-256 | fd237d29c9cbf5aaf0a5dd83b218be9bfbc6321a45ecd9a3e8ab11c6eaa792a5 |