Skip to main content

Easy webapps with falcon & mongodb

Project description

=======
Plume
=======


.. image:: https://img.shields.io/pypi/v/plume.svg
:target: https://pypi.python.org/pypi/plume

.. image:: https://img.shields.io/travis/JamesRamm/plume.svg
:target: https://travis-ci.org/JamesRamm/plume

.. image:: https://readthedocs.org/projects/plume/badge/?version=latest
:target: https://plume.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status

.. image:: https://landscape.io/github/JamesRamm/plume/master/landscape.svg?style=flat
:target: https://landscape.io/github/JamesRamm/plume/master
:alt: Code Health

.. image:: https://pyup.io/repos/github/JamesRamm/plume/shield.svg
:target: https://pyup.io/repos/github/JamesRamm/plume/
:alt: Updates


A library to help you make Falcon web apps backed by MongoDB.

Features
---------------

- Simple interface to MongoDB using ``marshmallow`` schemas. This allows a single document
definition which also provides serialization and validation

- Standard ``Resource`` classes for creating a full CRUD JSON API for REST collections and items.

- Easy filtering/projection of documents per request

- The ``FileCollection`` and ``FileItem`` resources provide file upload functionality. They can be configured
to use plumes' basic ``FileStore`` or your own storage backend (e.g. GridFS)

- Useful extra fields for marshmallow (``Choice``, ``Slug``, ``MongoId``, ``Password``...)


Example
--------

The following example creates a basic JSON API for a representation of a user.

.. code-block:: python

from datetime import datetime
from plume import create_app, schema, Collection, Item
from plume.connection import connect
from plume.fields import Slug
from marshmallow import fields, Schema

class UserSchema(schema.MongoSchema):
name = fields.Str(required=True)
email = fields.Email(required=True)
created = fields.DateTime(
missing=lambda: datetime.utcnow().isoformat(),
default=lambda: datetime.utcnow().isoformat()
)
profile = fields.Nested("ProfileSchema")
slug = Slug(populate_from='name')

class ProfileSchema(Schema):
"""Example of nesting a schema.
In mongodb, this will be a nested document
"""
biography = fields.Str()
profile_image = fields.Url(load_from='profileImage', dump_to='profileImage')


def get_app(database_name='myapp')
"""Creates the falcon app.
We pass the database name so we can use a different db for testing
"""
# Connect to the database *before* making schema instance.
# The ``connect`` function takes the same arguments as pymongo's
# ``MongoClient``. Here we connect to localhost.
connect(database_name)
user = UserSchema()
resources = (Collection(user, '/users'), Item(user, '/users/{email}'))
return create_app(resources)

Name this file ``app.py`` and run it with gunicorn:

gunicorn 'app:get_app()'

Design
----------

Plume intends to be a light and transparent library. It should compliment and enhance
Falcon & MongoDB usage but not get in the way of custom development.
To this end I have a small number of rules:

- No magic. Like falcon itself, it should be easy to follow inputs to outputs. To this end we have
a few soft rules such as:
- Avoid mixins. Mixins introduce implicit dependencies and make it harder to reason about code.
- Don't mess with metaclasses and double underscore methods without good reason.
There is often an easier, clearer way to achieve the same result.

- No reinvention. We try to use well proven existing solutions before rolling our own. Hence the use
of ``marshmallow`` for the ORM/serialization framework.

- No hijacking. Plume is complimentary or an 'add-on' to Falcon. It does not replace direct usage of Falcon (what
you might expect from a framework). It solves some common use cases and provides some useful tools. When you want to
do something unsupported and go direct to falcon, it doesnt get in your way.






=======
History
=======

0.1.0 (2017-09-25)
------------------

* First release on PyPI.

Project details


Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for plume, version 0.1.0
Filename, size File type Python version Upload date Hashes
Filename, size plume-0.1.0-py2.py3-none-any.whl (15.1 kB) File type Wheel Python version 3.6 Upload date Hashes View
Filename, size plume-0.1.0.tar.gz (33.3 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page