Merge pull request #4 from Ayub-Khan/documentation

Documentation

.gitignore

@@ -71,6 +71,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+.DS_Store
 
 # PyBuilder
 target/

CHANGELOG.rst

@@ -1 +1,42 @@
-django-view-permissions changelog
+Change Log
+----------
+
+..
+   All enhancements and patches to django-view-permissions will be documented
+   in this file.  It adheres to the structure of http://keepachangelog.com/ ,
+   but in reStructuredText instead of Markdown (for ease of incorporation into
+   Sphinx documentation and the PyPI description).
+
+   This project adheres to Semantic Versioning (http://semver.org/).
+
+.. There should always be an "Unreleased" section for changes pending release.
+
+Unreleased
+~~~~~~~~~~
+
+Added
+_____
+
+* _
+
+
+[0.0.1] - 19-03-2020
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Added
+_____
+
+* Automatic upload to PyPI on tags.
+* Documentation
+
+
+[0.0.dev0] - 17-03-2020
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Added
+_____
+
+* Attr based permissions
+* Method based permissions
+* Class based permissions
+* First release on PyPI.

CONTRIBUTING.rst

@@ -0,0 +1,47 @@
+=================
+How To Contribute
+=================
+
+
+Installation
+-------------------------
+
+Fork the repository and run::
+
+    $ git clone [email protected]:<username>/django-view-permissions.git
+
+    $ cd django-view-permissions
+
+    $ make venv  # needs python3.5
+    
+    $ make requirements
+
+
+Updating the Requirements
+-------------------------
+
+pip-tools is used for the requirement management. If you want to add/update
+some existing requirement, you need to update it in the .in file and run the
+following command.
+
+::
+
+    $ make upgrade
+
+
+Process
+-------
+
+1. Share the idea. (Create a Issue)
+
+2. Sumbit first working draft of your idea. (Create a Pull Request)
+
+3. Incorporate the reviwers sugestions.
+
+4. Get a couple of thumbs up and merge. (Y)
+
+
+Support
+-------
+
+For any kind of queries feel free to create github issues.

Makefile

@@ -3,7 +3,7 @@
 #####################################################################
 .PHONY: clean clean-test clean-pyc help requirements upgrade venv
 .DEFAULT_GOAL := help
-VENV = .venv
+VENV = .env
 
 
 ######################################################################
@@ -32,6 +32,7 @@ clean-test: ## Remove test and coverage artifacts
 clean-docs-build: ## Remove docs and build artifacts
 	rm -fr build/
 	rm -fr dist/
+	rm -rf docs/build/
 
 docs-requirements: ## Install docs requirements
 	pip3 install -qr requirements/docs.txt
@@ -40,10 +41,12 @@ requirements: ## Install development requirements
 	pip3 install -r requirements/dev.txt
 
 build: docs-requirements ## Build the project
+	export DJANGO_SETTINGS_MODULE=test_settings.py
 	python setup.py bdist_wheel
+	cd docs && $(MAKE) html
 
 venv: ## Create a virtual env and install test and production requirements
-	python3 -m venv $(VENV)
+	python3.5 -m venv $(VENV)
 	source $(VENV)/bin/activate
 	pip3 install --upgrade pip
 

README.rst

@@ -1 +1,136 @@
-django_view_permissions
+django-view-permissions
+=======================
+
+|pypi-badge| |travis-badge| |codecov-badge| |pyversions-badge|
+|license-badge|
+
+django-view-permissions provides ways to control access for Django app views
+
+Overview
+--------
+
+Checks the incoming requests, to grant or deny access for views accoding to 
+the permissions defined in the views. If permissions attribute is not defined
+in the view, normal django flow is followed. If permissions attribute is
+defined in view it checks and grants or denys access of the view.
+
+
+Installation
+------------
+
+Install the latest release using pypi:
+
+::
+
+    pip3 install django-view-permissions
+
+Add the application to the INSTALLED_APPS:
+
+::
+
+    INSTALLED_APPS = (
+        ...
+        # DjangoViewPermissions
+        'django_view_permissions',
+    )
+
+Add the middleware to the configuration:
+
+::
+
+    MIDDLEWARE_CLASSES = (
+        ...
+        'django_view_permissions.middleware.DjangoViewPermissionsMiddleware',
+    )
+
+Usage
+-----
+Currently, 3 ways to define permissions are supported.
+
+    - Attribute based permissions
+    - Method based permissions
+    - Class based permissions
+
+Below is a Attribute based permission example. Where view will be only accessable
+to users whose attribute 'is_staff' is 'True'. 
+
+::
+
+    class DummyView(View):
+        permissions = [
+            ('attr', 'is_staff', True),
+        ]
+
+In Method based permissions, you will need to defind the method with a 'request=None'
+argument and a boolean return statement. All the requests for which method returns
+'True' will be able to access the view.
+
+::
+
+    class DummyView(View):
+        permissions = [
+            ('method', permission_method),
+        ]
+
+
+In Class based permissions, you will need to defind a class with a 'request=None'
+argument in __init__ method. All the requests for which __call__ method returns
+'True' will be able to access the view.
+
+::
+
+    class DummyView(View):
+        permissions = [
+            ('class', PermissionClass),
+        ]
+
+Note: It is recommended to define the permission methods or classes in a separate file.
+
+Please check `permissions.py <https://github.com/Ayub-Khan/django-view-permissions/blob/master/django_view_permissions/tests/test_app/permissions.py>`_ for examples.
+
+
+License
+-------
+
+The code in this repository is licensed under the Apache Software License 2.0 unless
+otherwise noted.
+
+Please see ``LICENSE`` for details.
+
+How To Contribute
+-----------------
+
+Contributions are very welcome.
+
+Please read `How To Contribute <https://github.com/Ayub-Khan/django-view-permissions/blob/master/CONTRIBUTING.rst>`_ for details.
+
+Reporting Security Issues
+-------------------------
+
+Please do not report security issues in public. Please email [email protected].
+
+Getting Help
+------------
+
+Feel free to create git issues in case of queries/issues/enhancements. 
+
+
+.. |pypi-badge| image:: https://img.shields.io/pypi/v/django-view-permissions.svg
+    :target: https://pypi.python.org/pypi/django-view-permissions/
+    :alt: PyPI
+
+.. |travis-badge| image:: https://travis-ci.com/ayub-khan/django-view-permissions.svg?branch=master
+    :target: https://travis-ci.com/ayub-khan/django-view-permissions
+    :alt: Travis
+
+.. |codecov-badge| image:: http://codecov.io/github/ayub-khan/django-view-permissions/coverage.svg?branch=master
+    :target: http://codecov.io/github/ayub-khan/django-view-permissions?branch=master
+    :alt: Codecov
+
+.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/django-view-permissions.svg
+    :target: https://pypi.python.org/pypi/django-view-permissions/
+    :alt: Supported Python versions
+
+.. |license-badge| image:: https://img.shields.io/github/license/ayub-khan/django-view-permissions.svg
+    :target: https://github.com/Ayub-Khan/django-view-permissions/blob/master/LICENSE
+    :alt: License

django_view_permissions/__init__.py

@@ -1,4 +1,4 @@
 """
 Grants the ability to allow or block django view access based on user group.
 """
-VERSION = '0.0.dev0'
+VERSION = '0.0.1'

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../../CHANGELOG.rst

docs/source/conf.py

@@ -0,0 +1,58 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'django_view_permissions'
+copyright = '2020, Ayub khan'
+author = 'Ayub khan'
+
+# The full version, including alpha/beta/rc tags
+release = '0.0.1'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode'
+
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# 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']

docs/source/contributing.rst

@@ -0,0 +1 @@
+.. include:: ../../CONTRIBUTING.rst