.. sondra documentation master file, created by sphinx-quickstart on Tue Oct 6 10:46:40 2015. You can adapt this file completely to your liking, but it should at least contain the root toctree directive.

Sondra

Author Jefferson Heard_

Copyright 2015 Jefferson Heard

License Apache 2.0

Development home https://github.com/jeffersonheard/sondra

Development status beta

Maintainer Jefferson Heard

Documentation https://jeffersonheard.github.io/sondra

Sondra is an "ORM" and REST-ful webservice framework for Python 3.x, Flask, and RethinkDB with some unique features. Sondra's goal is to aid full stack developers by letting them focus on data models and functionality instead of writing workarounds and glue code. It embraces common "shortcuts" developers take in common full-stack web applications, e.g. merging "Model" and "Controller" in the oft-used MVC pattern.

Sondra does not currently support asynchronous access to RethinkDB. The goal is to eventually support Tornado_

Features

• A clear, DRY heirarchical application structure that emphasizes convention over configuration.
• Authentication via JSON Web Tokens_ (JWT)
• JSON-Schema_ validation for documents.
• Expose methods on documents, collections, and applications, complete with schemas for call and return.
• A clear, predictable URL scheme for all manner of API calls, covering a broad set of use-cases.
• Self documenting APIs with both human-readable help based on docstrings and schemas for every call.
• Use API idiomatically over HTTP and native Python without writing boilerplate code

Installation

::

$ python setup.py

Contribute

Contributions are welcome. I haven't gotten around to posting a "master plan" of any sort yet, but I will get there. If you're interested in contributing, please email me directly_ or simply fork the GitHub project and issue a pull request.

Support

For support, please see the project page on GitHub_

License

This project is licensed under the Apache license V2. See LICENSE_.

Concept

A Sondra API is exposed in Flask as a suite of applications. Each application contains a number of document collections, and each collection contains a number of documents.

Sondra tries to take advantage of all manner of Python idioms in a sane manner. It generates as much as possible, while avoiding "magic tricks" or introducing conventions that are already covered by Python idioms. This means that:

• Online documentation is generated at every level from reStructuredText or Google style docstrings.
• Method schemas are generated from annotated function signatures
• All URL features that urllib.parse recognizes are taken advantage of to create a regular URL scheme that encompasses all manner of calls.

Web Services

Sondra uses a regular URL scheme for its web services. See the docs directory for more details:

* Underscores in Python identifiers are replaced with more web-friendly dashes (slugs)
* Paths address app / collection / instance (document)
* The last path element include an optional `.` (dot), which separates the object being addressed and a method being
  called.
* Fragments allow the caller to address sub-documents in JSON responses. Fragments delimted with `#` are not passed by
  browsers to the server. The alternative for delimiting fragments is `@!`
* Path parameters (on the last element, with a ";", see the URL spec or `urlparse`_ docs) are used to specify output
  format or content directives. Currently supported:

  - `json` or `format=json` retrieves data in JSON format.
  - `geojson` or `format=geojson` retrieves data in GeoJSON feature or feature collection format.
  - `help` or `format=help` retrieves HTML autogenerated help.
  - `schema` or `format=schema` retrieves a JSON-Schema document for the service call.

Documents
~~~~~~~~~

A `Document` is a single document that conforms to a JSON-Schema `object` type.
That is, it is never a simple type nor an array of items.

Documents may expose methods to the HTTP api.  These are similar to instance
methods in Python.  They operate on an individual document in a collection
instead. Document methods might include operations that combine multiple
documents to make a third (add, multiply, divide, subtract, or similar) or they
might provide specific views of a document.  Anything that you would write as
an "instance method" in Python.

Collections
~~~~~~~~~~~

A `Collection` is a RethinkDB table that contains a specific subclass of
`Document`, which is defined by a single JSON-Schema. The collection class
defines additionally:

* The primary key name (defaults to the RethinkDB default of "id")
* Indexes
* Any document properties that require "special treatment" in RethinkDB such as geographical and date/time types.
* Relations to other Collections
* The `Application` class it belongs to.

Collections may expose methods to the HTTP api.  These are similar to class
methods in Python, as they operate on the collection itself and not the
individual documents. Collection methods might provide special filtering,
create documents according to a specific template, or set properties on the
collection itself. Anything you would write as a "class method" in Python

Applications

An Application is a reusable grouping of collections and a set of optional application methods, which operate a bit like globally available functions. Applications are bound to a single database within RethinkDB.

Applications may expose methods to the HTTP api. These are similar to the functions that are defined at the module level in Python. They are not specific to a particular class or instance, but instead are defined to provide broad functionality for the whole application.

The Suite

A `Suite` defines the environment of applications, including database
connections and provides some basic functionality. Every application is
registered with the global `Suite` object, which itself implements Python's
Mapping protocol to provide dictionary-like lookup of application objects.  The
"Suite" object determines the base path of all Application APIs. Suites are
similar in nature to Django's `settings.py` except that they are class-based.
There may be only *one* concrete class of Suite in your Flask app, although it
may derive from any number of abstract Suite mixins.



.. External links go below here.
   -----------------------------

.. _email me directly: mailto:[email protected]
.. _project page on GitHub: https://github.com/JeffHeard/sondra
.. _JSON Web Tokens: https://self-issued.info/docs/draft-ietf-oauth-json-web-token.html
.. _JSON-Schema: http://json-schema.org
.. _LICENSE: https://github.com/JeffHeard/sondra/blob/master/LICENSE
.. _Tornado: http://www.tornadoweb.org/en/stable/
.. _urlparse: https://docs.python.org/3/library/urllib.parse.html
.. _Jefferson Heard: https://jeffersonheard.github.io