Merge branch 'master' into develop

.gitignore

@@ -1,3 +1,5 @@
+.python-version
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

.travis.yml

@@ -2,6 +2,8 @@
 language: python
 env:
   - TOXENV=py27
+  - TOXENV=py33
+  - TOXENV=py34
 install:
   - pip install tox
 script: tox

MANIFEST.in

@@ -1,2 +1,3 @@
 include README.md
-include VERSION
+include VERSION
+recursive-include nefertari/scaffolds *

README.md

@@ -1,5 +1,5 @@
 # `Nefertari`
 [![Build Status](https://travis-ci.org/brandicted/nefertari.svg?branch=master)](https://travis-ci.org/brandicted/nefertari)
-[![Documentation Status](https://readthedocs.org/projects/nefertari/badge/?version=master)](http://nefertari.readthedocs.org/en/master/)
+[![Documentation](https://readthedocs.org/projects/nefertari/badge/?version=stable)](http://nefertari.readthedocs.org)
 
-Nefertari is a REST API framework sitting on top of [Pyramid](https://github.com/Pylons/pyramid) and [ElasticSearch](https://www.elastic.co/downloads/elasticsearch). She currently offers two backend engines: [SQLA](https://github.com/brandicted/nefertari-sqla) and [MongoDB](https://github.com/brandicted/nefertari-mongodb).
+Nefertari is a REST API framework sitting on top of [Pyramid](https://github.com/Pylons/pyramid) and [Elasticsearch](https://www.elastic.co/downloads/elasticsearch). She currently offers two backend engines: [SQLA](https://github.com/brandicted/nefertari-sqla) and [MongoDB](https://github.com/brandicted/nefertari-mongodb).

VERSION

@@ -1 +1 @@
-0.3.0
+0.6.1

docs/source/auth.rst

@@ -1,31 +1,101 @@
 Authentication & Security
 =========================
 
-Set `auth = true` in you .ini file to enable authentication.
+In order to enable authentication, add the ``auth`` paramer to your .ini file:
 
-Ticket Auth
------------
+.. code-block:: ini
+
+    auth = true
+
+Nefertari currently uses the default Pyramid "auth ticket" cookie mechanism.
+
+
+Custom User Model
+-----------------
+
+When authentication is enabled, Nefertari uses its own `User` model. This model has 4 fields by default: username, email, password and groups (list field with values 'admin' and 'user'). However, this model can be extanded.
+
+.. code-block:: python
 
-Nefertari currently supports the default Pyramid "auth ticket" cookie method of authentication.
+    from nefertari import engine as eng
+    from nefertari.authentication.models import AuthUserMixin
+    from nefertari.engine import BaseDocument
 
-Token Auth
-----------
 
-(under development)
+    class User(AuthUserMixin, BaseDocument):
+        __tablename__ = 'users'
 
-Visible fields in views
+        first_name = eng.StringField(max_length=50, default='')
+        last_name = eng.StringField(max_length=50, default='')
+
+
+Visible Fields in Views
 -----------------------
 
-You can control which fields to display to both authenticated users and unauthenticated users by defining `_auth_fields` and `_public_fields` respectively in your models.
+You can control which fields to display by defining the following properties on your models:
+
+**_auth_fields**
+    Lists fields to be displayed to authenticated users.
+
+**_public_fields**
+    Lists fields to be displayed to all users including unauthenticated users.
+
+**_hidden_fields**
+    Lists fields to be hidden but remain editable (as long as user has permission), e.g. password.
+
+
+Permissions
+-----------
+
+This section describes permissions used by nefertari, their relation to view methods and HTTP methods. These permissions should be used when defining ACLs.
+
+To make things easier to grasp, let's imagine we have an application that defines a view which handles all possible requests under ``/products`` route. We are going to use this example to make permissions description more obvious.
+
+Following lists nefertari permissions along with HTTP methods and view methods they correspond to:
+
+**view**
+    * Collection GET (``GET /products``). View method ``index``
+    * Item GET (``GET /products/1``) View method ``show``
+    * Collection HEAD (``HEAD /products``). View method ``index``
+    * Item HEAD (``HEAD /products/1``). View method ``show``
+
+**create**
+    * Collection POST (``POST /products``). View method ``create``
+
+**update**
+    * Collection PATCH (``PATCH /products``). View method ``update_many``
+    * Collection PUT (``PUT /products``). View method ``update_many``
+    * Item PATCH (``PATCH /products/1``). View method ``update``
+    * Item PUT (``PUT /products/1``) View method ``replace``
+
+**delete**
+    * Collection DELETE (``DELETE /products``). View method ``delete_many``
+    * Item DELETE (``DELETE /products/1``). View method ``delete``
+
+**options**
+    * Collection OPTIONS (``OPTIONS /products``). View method ``collection_options``
+    * Item OPTIONS (``OPTIONS /products/1``). View method ``item_options``
+
 
 ACL API
 -------
 
 For authorizing access to specific resources, Nefertari uses standard Pyramid access control lists. `See the documentation on Pyramid ACLs <http://docs.pylonsproject.org/projects/pyramid/en/1.5-branch/narr/security.html>`_ to understand how to extend and customize them.
 
+Considerations:
+    * An item will inherit its collection's permissions if the item's permissions are not specified in an ACL class
+    * If you create an ACL class for your document that does something like give the document.owner edit permissions, then you can’t rely on this setting to be respected during collection operation. in other words, only if you walk up to the item via a URL will this permission setting be applied.
+
 .. automodule:: nefertari.acl
     :members:
 
+
+Advanced ACLs
+-------------
+
+For more advanced ACLs, you can look into using `nefertari-guards <https://github.com/brandicted/nefertari-guards>`_ in you project. This package stores ACLs at the object level, making it easier to build multi-tenant applications using a single data store.
+
+
 CORS
 ----
 

docs/source/changelog.rst

@@ -1,9 +1,75 @@
 Changelog
 =========
 
+* :release:`0.6.1 <2015-11-18>`
+* :bug:`-` Added 'event.instance' to 'event' object to access newly created object (if object is returned by view method)
+* :bug:`-` Fixed a bug with GET '/auth/logout'
+* :bug:`-` 'request.user' is now set to None when using 'auth = False'
+
+* :release:`0.6.0 <2015-10-07>`
+* :feature:`-` Event system is now crud-based as opposed to db-based
+* :feature:`-` Refactored field processors to use the new event system
+* :feature:`-` Removed unnecessary extra '__confirmation' parameter from PATCH/PUT/DELETE collection requests
+* :feature:`-` Nested relationships are now indexed in bulk in Elasticsearch
+* :feature:`-` Added '_hidden_fields' model attribute to hide fields while remaining editable (e.g. password)
+* :bug:`- major` Fixed a bug causing polymorchic collections to always return 403
+* :bug:`- major` Fixed nested relationships not respecting '_auth_fields'
+* :support:`-` Added support for `'nefertari-guards' <https://nefertari-guards.readthedocs.org/>`_
+
+* :release:`0.5.1 <2015-09-02>`
+* :bug:`-` Fixed '_self' param for ``/api/users/self`` convience route
+* :bug:`-` Fixed a bug when using reserved query params with GET tunneling
+* :bug:`-` Fixed an error preventing RelationshipFields' backrefs to be set as _nested_relationships
+* :bug:`-` Fixed a bug allowing to update hidden fields
+* :bug:`-` Simplified ACLs (refactoring)
+
+* :release:`0.5.0 <2015-08-19>`
+* :feature:`-` Renamed field 'self' to '_self'
+* :feature:`-` Refactored authentication
+* :feature:`-` Renamed setting `debug` to `enable_get_tunneling`
+* :feature:`-` Added the ability to apply processors on 'Relationship' fields and their backrefs
+* :feature:`-` Model's save()/update()/delete()/_delete_many()/_update_many() methods now require self.request to be passed for '_refresh_index' parameter to work
+* :feature:`-` Routes can now have the same member/collection name. E.g. root.add('staff', 'staff', ...)
+* :bug:`- major` Fixed sorting by 'id' when two ES-based models have two different 'id' field types
+* :bug:`- major` Removed unused 'id' field from 'AuthUserMixin'
+* :bug:`- major` Fixed bug with full-text search ('?q=') when used in combination with field search ('&<field>=')
+* :bug:`- major` Fixed 40x error responses returning html, now all responses are json-formatted
+* :bug:`- major` Fixed formatting error when using `_fields` query parameter
+* :bug:`- major` Fixed duplicate records when querying ES aggregations by '_type'
+* :bug:`- major` Fixed 400 error returned when querying resources with id in another format than the id field used in URL schema, e.g. ``/api/<collection>/<string_instead_of_integer>``, it now returns 404
+* :bug:`- major` Fixed `_count` querying not respecting ``public_max_limit`` .ini setting
+* :bug:`- major` Fixed error response when aggregating hidden fields with ``auth = true``, it now returns 403
+
+* :release:`0.4.1 <2015-07-07>`
+* :bug:`-` Fixed a bug when setting ``cors.allow_origins = *``
+* :bug:`-` Fixed errors in http methods HEAD/OPTIONS response
+* :bug:`-` Fixed response of http methods POST/PATCH/PUT not returning created/updated objects
+* :support:`- backported` Added support for Elasticsearch polymorphic collections accessible at ``/api/<collection_1>,<collection_N>``
+
+* :release:`0.4.0 <2015-06-14>`
+* :support:`-` Added python3 support
+* :feature:`-` Added ES aggregations
+* :feature:`-` Reworked ES bulk queries to use 'elasticsearch.helpers.bulk'
+* :feature:`-` Added ability to empty listfields by setting them to "" or null
+
+* :release:`0.3.4 <2015-06-09>`
+* :bug:`-` Fixed bug whereby `_count` would throw exception when authentication was enabled
+
+* :release:`0.3.3 <2015-06-05>`
+* :bug:`-` Fixed bug with posting multiple new relations at the same time
+
+* :release:`0.3.2 <2015-06-03>`
+* :bug:`-` Fixed bug with Elasticsearch indexing of nested relationships
+* :bug:`-` Fixed race condition in Elasticsearch indexing by adding the optional '_refresh_index' query parameter
+
+* :release:`0.3.1 <2015-05-27>`
+* :bug:`-` Fixed PUT to replace all fields and PATCH to update some
+* :bug:`-` Fixed posting to singular resources e.g. ``/api/users/<username>/profile``
+* :bug:`-` Fixed ES mapping error when values of field were all null
+
 * :release:`0.3.0 <2015-05-18>`
 * :support:`-` Step-by-step 'Getting started' guide
-* :bug:`- major` Fixed several issues related to ElasticSearch indexing
+* :bug:`- major` Fixed several issues related to Elasticsearch indexing
 * :support:`-` Increased test coverave
 * :feature:`-` Added ability to PATCH/DELETE collections
 * :feature:`-` Implemented API output control by field (apply_privacy wrapper)
@@ -18,4 +84,4 @@ Changelog
 * :support:`-` Improved docs
 
 * :release:`0.1.1 <2015-04-01>`
-* :support:`-` Initial release after two years of development as "Presto". Now with database engines! Originally extracted and generalized from the Brandicted API which only used MongoDB.
+* :support:`-` Initial release after two years of development as 'Presto'. Now with database engines! Originally extracted and generalized from the Brandicted API which only used MongoDB.

docs/source/conf.py

@@ -60,9 +60,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+# version = '0.1'
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+# release = '0.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -154,7 +154,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/source/development_tools.rst

@@ -1,19 +1,19 @@
 Development Tools
 =================
 
-Indexing in ElasticSearch
+Indexing in Elasticsearch
 -------------------------
 
-``nefertari.index`` console script can be used to manually (re-)index models from your database engine to ElasticSearch.
+``nefertari.index`` console script can be used to manually (re-)index models from your database engine to Elasticsearch.
 
 You can run it like so::
 
-    $ nefertari.index --config local.ini --models example_api.model.Story
+    $ nefertari.index --config local.ini --models Model
 
 The available options are:
 
 --config        specify ini file to use (required)
---models        list of models to index (e.g. User). Models must subclass ESBaseDocument.
+--models        list of models to index. Models must subclass ESBaseDocument.
 --params        URL-encoded parameters for each module
 --quiet         "quiet mode" (surpress output)
 --index         Specify name of index. E.g. the slug at the end of http://localhost:9200/example_api