Metadata-Version: 2.1
Name: fauna
Version: 0.2.0
Summary: Fauna Python driver for FQL 10+
Home-page: https://github.com/fauna/fauna-python
Author: Fauna, Inc
Author-email: priority@fauna.com
License: MPL 2.0
Keywords: faunadb fauna
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Database
Classifier: Topic :: Database :: Front-Ends
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Unix
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: iso8601
Requires-Dist: future
Requires-Dist: httpx[http2]
Provides-Extra: lint
Requires-Dist: yapf ; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pytest-env ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'
Requires-Dist: pytest-httpx ; extra == 'test'
Requires-Dist: pytest-subtests ; extra == 'test'

Fauna Python
==============

.. image:: https://img.shields.io/pypi/v/fauna.svg?maxAge=21600
  :target: https://pypi.python.org/pypi/fauna
.. image:: https://img.shields.io/badge/license-MPL_2.0-blue.svg?maxAge=2592000
  :target: https://raw.githubusercontent.com/fauna/fauna-python/main/LICENSE

Python driver for `Fauna <https://fauna.com>`_.

.. warning::
    This driver is in beta release and not recommended for production use.
    It operates with the Fauna database service via an API which is also in
    beta release and is not recommended for production use. This driver is
    not compatible with v4 or earlier versions of Fauna. If you would like
    to participate in the private beta program contact product@fauna.com.
    

Installation
------------

.. code-block:: bash

    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.

.. code-block:: python

    from fauna import fql
    from fauna.client import Client, 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
        create_col = fql('Collection.create({ name: "Dogs" })')
        client.query(create_col)

        # create a document
        create_doc = fql('Dogs.create({ name: "Scout" })')
        res: QuerySuccess = client.query(create_doc)
        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 ``$``.

.. code-block:: python

    from fauna import fql
    from fauna.client import Client

    def user_by_tin(tin: str):
        return fql('Users.byTin(${tin})', tin=tin)

    def render_user():
        return fql('{ name, address }')

    tin = "123"
    q = fql("""let u = ${user}
    u ${render}
    """, user=user_by_tin(tin), render=render_user())

    client = Client()
    res = client.query(q)

Document Streaming
------------------

Not implemented

Query Stats
------------------

Stats are returned on query responses and ServiceErrors.

.. code-block:: python

    from fauna import fql
    from fauna.client import Client, QuerySuccess, QueryStats
    from fauna.errors import AuthenticationError, 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 AuthenticationError as e:
        print(e)
    except ServiceError as e:
        if e.query_info is not None:
            emit_stats(e.query_info.stats)
        # more error handling...


Setup
-----

.. code-block:: bash

    $ 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:

.. code-block:: bash

    $ make docker-fauna
    $ source venv/bin/activate
    $ make install
    $ make integration-test

To run unit tests locally:

.. code-block:: bash

    $ source venv/bin/activate
    $ make install
    $ make unit-test

To stand up a container and run all tests at the same time:

.. code-block:: bash

    $ make docker-test

See the ``Makefile`` for more.

Coverage
--------

.. code-block:: bash

    $ source venv/bin/activate
    $ make coverage

Contribute
----------

GitHub pull requests are very welcome.


License
-------

Copyright 2023 `Fauna, Inc. <https://fauna.com>`_

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

`http://mozilla.org/MPL/2.0/ <http://mozilla.org/MPL/2.0/>`_

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.


.. _`tests`: https://github.com/fauna/fauna-python/blob/main/tests/


