Metadata-Version: 2.0
Name: plume
Version: 0.1.0
Summary: Easy webapps with falcon & mongodb
Home-page: https://github.com/JamesRamm/plume
Author: James Ramm
Author-email: jamessramm@gmail.com
License: GNU General Public License v3
Description-Content-Type: UNKNOWN
Keywords: plume
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Requires-Dist: marshmallow (==2.13.6)
Requires-Dist: pymongo (==3.5.1)
Requires-Dist: falcon (==1.3.0)
Requires-Dist: simplejson (==3.11.1)

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


