Metadata-Version: 2.0
Name: django-rester
Version: 0.0.2.dev11
Summary: Django REST API build helper
Home-page: http://lexycore.github.io/django-rester
Author: Sergei Kovalev
Author-email: zili.tnd@gmail.com
License: MIT
Download-URL: https://github.com/lexycore/django-rester.git
Keywords: development,API
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.1
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Dist: django
Requires-Dist: django-rediser
Requires-Dist: pyjwt

Django-Rester
=============

|build| |codacy| |pypi| |license|

Package for creating API with built-in validation and authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This product is designed to build API endpoints of varying complexity
and nesting.

The core is a view class - BaseApiView (the inheritor of the standard
django view)

--------------

1. settings
'''''''''''

DEFAULT settings (may be overridden):

.. code:: python

    DJANGO_RESTER = {
        'LOGIN_FIELD': 'username',
        'AUTH_BACKEND': 'django_rester.rester_jwt',
        'RESPONSE_STRUCTURE': False,  # here can be a dict with 'success', 'message' and 'data' as a values
    }

    DJANGO_RESTER_JWT: {
        'SECRET': 'secret_key',
        'EXPIRE': 60 * 60 * 24 * 14,  # seconds
        'AUTH_HEADER': 'Authorization',
        'AUTH_HEADER_PREFIX': 'jwt',
        'ALGORITHM': 'HS256',
        'PAYLOAD_LIST': ['username'],
        'USE_REDIS': False,  # here can be an int value (redis db number)
    }

**DJANGO\_RESTER** - django-rester settings:

     **LOGIN\_FIELD** - user login field (default is 'username' as in
django)

     **AUTH\_BACKEND** - authentication backend\*

     **RESPONSE\_STRUCTURE** - use or not @try\_response() decorator by
default.

**DJANGO\_RESTER\_JWT** - JWT authentication settings (in case of
'RESTER\_AUTH\_BACKEND' = 'django\_rester.rester\_jwt')\*:

     **SECRET** - JWT secret key

     **EXPIRE** - token expiration time (datetime.now() +
RESTER\_EXPIRATION\_DELTA)

     **AUTH\_HEADER** - HTTP headed, which will be used for auth token.

     **AUTH\_HEADER\_PREFIX** - prefix for auth token
("Authorization:<prefix> <token>")

     **ALGORITHM** - cypher algorithm

     **PAYLOAD\_LIST** - payload list for token encode (will take
specified **user** attributes to create token)

     **USE\_REDIS** - use redis-server to store tokens or not \*\*\*

2. built-in statuses
''''''''''''''''''''

``from django_rester.status import ...`` slightly modified status.py
from `DRF <http://www.django-rest-framework.org/>`__, it's simple and
easy to understand.

Any statuses used in this documentation are described in that file.
\*\*\* ##### 3. built-in exceptions:

``from django_rester.exceptions import ...`` you may use those
exceptions to interact with **@try\_response** decorator (good example
of usage), or in any other way you want

**class ResponseError(Exception)**

    base exception class, standard Exception inheritor, added response
status - HTTP\_500\_INTERNAL\_SERVER\_ERROR

**class ResponseBadRequest(ResponseError)**

    ResponseError inheritor, response status changed to
HTTP\_400\_BAD\_REQUEST

**class ResponseServerError(ResponseError)**

    ResponseError inheritor

**class ResponseAuthError(ResponseError)**

    ResponseError inheritor, response status changed to
HTTP\_401\_UNAUTHORIZED

**class ResponseOkMessage(ResponseError)**

    ResponseError inheritor

    acceptable arguments: \*, message='', data=None,
status=HTTP\_200\_OK

**class ResponseFailMessage(ResponseError)**

    ResponseError inheritor

    acceptable arguments: \*, message='', data=None,
status=HTTP\_500\_INTERNAL\_SERVER\_ERROR

**class ResponseBadRequestMsgList(ResponseError)**

    ResponseError inheritor

    acceptable arguments: \*, messages=None,
status=HTTP\_400\_BAD\_REQUEST

    messages could be list, tuple or string. \*\*\* ##### 4. permission
classes

``from django_rester.permission import ...`` Permission classes created
to interact wih **@permissions()** decorator (good example of usage), or
in any other way you want

All permission classes accepts only one argument on **init** - django
view **request** object.

All permission classes has 2 attributes, defined on **init**:

**check**: Bool - returns **True** or **False** if request.user may or
may not access endpoint method

**message**: could be a string or list of messages **class
BasePermission**

    contains all base permission methods, it is not recommended to use
it directly in projects

**class IsAuthenticated(BasePermission)**

    check = **True** if user authenticated and active, else **False**

**class IsAdmin(BasePermission)**

    check = **True** if user authenticated and active and is\_superuser,
else **False**

**class AllowAny(BasePermission)**

    check = **True** for any user (even anonymous)

--------------

5. built-in decorators
''''''''''''''''''''''

``from django_rester.decorators import ...`` **@permissions()**

    accepts permission class or list, tuple of classes.

    if check is passed, then user will be allowed to use endpoint

example:

::

    class Example(BaseApiView):

        @permissions(IsAdmin)
        def post(request, request_data, *args, **kwargs):
            pass

--------------

6. built-in views
'''''''''''''''''

``from django_rester.views import ...`` **class BaseApiView(View)**

inherits from standard django view.

class attributes:

    **auth** - authentication backend instance

    **request\_fields** - request validator

class HTTP methods (get, post, put, etc...) accepts next arguments:
request, request\_data, \*args, \*\*kwargs

    **request** - standard django view request object

    **request\_data** - all received request parameters as json
serialized object

User authentication with selected authentication backend **class
Login(BaseApiView)**

Could be used to authenticate user with selected authentication backend.

    Allowed method is 'POST' only.

    Requires username and password in request parameters (username
fieldname parameter may be set in settings)

    Returns token and HTTP\_200\_OK status code if authentication
success, error message and HTTP\_401\_UNAUTHORIZED if failed **class
Logout(BaseApiView)**

Could be used to logout (with redis support) or just to let know
frontend about logout process. Any view could be used the same way, here
is a **simple example**:

    **app/views.py:**

::

    from django_rester.views import BaseAPIView
    from django_rester.decorators import permissions
    from django_rester.exceptions import ResponseOkMessage
    from django_rester.permission import IsAdmin
    from django_rester.status import HTTP_200_OK
    from app.models import Model
    from django_rester.fields import JSONField

    class TestView(BaseAPIView):

        request_fields = {"POST": {
            "id": JSONField(field_type=int, required=True, ),
            "title": JSONField(field_type=str, required=True, default='some_title'),
            "fk": [{"id": JSONField(field_type=int, required=True)}],
        }}


        def retrieve_items():
            return Model.objects.all()

        def create_item(title):
            item, cre = Model.objects.get_or_create(title=title)
            return item, cre

        @permissions(AllowAny)
        def get(self, request, request_data, *args, **kwargs):
            items = self.retrieve_items()
            response_data = {...here we should build some response structure...}***
            return response_data, HTTP_200_OK

        @permissions(IsAdmin)
        def post(self, request, request_data, *args, **kwargs):
            title = request_data.get('title', None)
            # no need to check 'if title', because it is allready validated by 'available_fields'
            # ... here we will do some view magic with the rest request_data
            item, cre = self.create_item(title)
            if not cre:
                raise ResponseOkMessage(message='Item allready exists', data={'title': title})
            response_data = {...here we should build some response structure...}***

            return response_data

    **app/urls.py:**

::

    from django.conf.urls import url
    from .views import TestView

    urlpatterns = [
        url(r'^test/', TestView.as_view()),
    ]

--------------

7. built-in fields
''''''''''''''''''

``from django_rester.fields import ...`` **class JSONField**

class attributes:

    **field\_type** - data type (int, float, str, bool)

    **required** - field is required

    **default** - default value if not specified

    **blank** - may or may not be blank

    **model** - model for foreign relations

    **field** - field for foreign relations

methods:

    **validate** - validate field value with parameters \*\*\*

\*- There is only one authentication backend available for now -
RESTER\_JWT

\*\*- BaseApiView is on active development stage, other attributes and
methods could be added soon

\*\*\*- automatic response structure build - one of the nearest tasks

.. |build| image:: https://travis-ci.org/lexycore/django-rester.svg?branch=develop
   :target: https://travis-ci.org/lexycore/django-rester
.. |codacy| image:: https://api.codacy.com/project/badge/Grade/dee291831b0b43158e2d2301726e2c00
   :target: https://www.codacy.com/app/lexycore/django-rester/dashboard
.. |pypi| image:: https://img.shields.io/pypi/v/django-rester.svg
   :target: https://pypi.python.org/pypi/django-rester
.. |license| image:: https://img.shields.io/pypi/l/django-rester.svg
   :target: https://github.com/lexycore/django-rester/blob/master/LICENSE


