Tag Archives: Documentation

Django Rest Framework Authentication Packages

What is this ?

I’ve found the official documentation of Django Rest Framework third-party authentication packages difficult to parse, and lacking some information I would like, so I’ve produced my own version, extending the original. I will revise this blog post until I’m satisfied and then I will submit my version as a pull request to the Django Rest Framework project for consideration as a replacement for the existing version.

DRF – Third Party Authentication Packages

Categorisation

In addition to the main table, there are extra tables showing packages grouped by :

Main Table

NameDescriptionLast Update to Repos
Django-rest-knox
[docs]

Django-rest-knox library provides models and views to handle token-based authentication in a more secure and extensible way than the built-in TokenAuthentication scheme – with Single Page Applications and Mobile clients in mind.

It provides per-client tokens, and views:

  • to generate them when provided some other authentication (usually basic authentication),
  • to delete the token (providing a server enforced logout) and
  • to delete all tokens (logs out all clients that a user is logged into).
2025-01-28
Django OAuth Toolkit
[docs]

The Django OAuth Toolkit package provides OAuth 2.0 support and works with Python 3.4+.

The package is maintained by jazzband and uses the excellent OAuthLib.

The package is well documented, and well supported and is currently the DRF project  recommended package for OAuth 2.0 support.

2025-02-25
Django REST framework OAuth
[docs]

The Django REST framework OAuth package provides both OAuth1 and OAuth2 support for DRF.

This package was previously included directly in the REST framework but is now supported and maintained as a third-party package.

2019-04-13
JSON Web Token Authentication
[docs]

JSON Web Token is a fairly new standard which can be used for token-based authentication.

Unlike the built-in TokenAuthentication scheme, JWT Authentication doesn’t need to use a database to validate a token.

A package for JWT authentication is djangorestframework-simplejwt which provides some features as well as a pluggable token blacklist app.

2025-02-21
Hawk HTTP Authentication
[docs]

The HawkREST library builds on the Mohawk library to let you work with Hawk signed requests and responses in your API.

Hawk lets two parties securely communicate with each other using messages signed by a shared key.

It is based on HTTP MAC access authentication (which was based on parts of OAuth 1.0).

2018-10-07
HTTP Signature Authentication

HTTP Signature provides a way to achieve origin authentication and message integrity for HTTP messages.


Similar to Amazon’s HTTP Signature scheme, used by many of its services, it permits stateless, per-request authentication.


Elvio Toccalino maintains the djangorestframework-httpsignature (outdated) package which provides an easy-to-use HTTP Signature Authentication mechanism. You can use the updated fork version of djangorestframework-httpsignature, which is drf-httpsig.



2018-03-29
Djoser
[docs]

Djoser library provides a set of views to handle basic actions such as registration, login, logout, password reset and account activation.

The package works with a custom user model and uses token-based authentication.

This is a ready to use REST implementation of the Django authentication system.

2024-11-11
django-rest-auth / dj-rest-auth
[docs]

This library provides a set of REST API endpoints for registration, authentication (including social media authentication), password reset, retrieve and update user details, etc.

By having these API endpoints, your client apps such as AngularJS, iOS, Android, and others can communicate to your Django backend site independently via REST APIs for user management.

2024-12-02
drf-social-oauth2
[docs]

Drf-social-oauth2 is a framework that helps you authenticate with major social oauth2 vendors, such as Facebook, Google, Twitter, Orcid, etc.

It generates tokens in a JWTed way with an easy setup.

2024-07-19
drfpasswordless
[docs]

drfpasswordless adds (Medium, Square Cash inspired) passwordless support to Django REST Framework’s TokenAuthentication scheme.

Users log in and sign up with a token sent to a contact point like an email address or a mobile number.

2023-10-23
django-rest-authemail
[docs]

django-rest-authemail provides a RESTful API interface for user signup and authentication.

Email addresses are used for authentication, rather than usernames.

API endpoints are available for signup, signup email verification, login,

2023-04-10
Django-Rest-Durin
[docs]

Django-Rest-Durin is built with the idea to have one library that does token auth for multiple Web/CLI/Mobile API clients via one interface but allows different token configuration for each API Client that consumes the API.

It provides support for multiple tokens per user via custom models, views, permissions that work with Django-Rest-Framework.

The token expiration time can be different per API client and is customizable via the Django Admin Interface.

2023-05-04

Note1: ‘Last Update to Repos’ column values are as of 26 Feb 2024.

Note2: As of 26 Feb 2024 the table above does not differ a great deal from the official document. I believe that it is easier to read but otherwise the content is very similar. In the future I will update it to include other information to make selecting a third-party DRF authentication package easier.

Packages providing support for Social Identities

  • django-rest-auth / dj-rest-auth
  • drf-social-oauth2

Packages providing OAuth capability

  • Django OAuth Toolkit
  • Django REST framework OAuth
  • drf-social-auth2

Packages by date of last update

Last UpdatePackage
2025Django-rest-knox
Django OAuth Toolkit
JSON Web Token Authentication
2024Djoser
django-rest-auth / dj-rest-auth
drf-social-oauth2
2023drfpasswordless
django-rest-authemail
Django-Rest-Durin
2019Django REST framework OAuth
2018Hawk HTTP Authentication
HTTP Signature Authentication

A note about licensing

As mentioned, the above text is based on part of the official documentation. The license under which django-rest-framework is made available doesn’t make it very clear how the documentation should be treated when re-distributed as it’s neither source code, nor binary so I hope that it’s enough to point out that : this is the license of of the django rest framework project; and the documentation is Copyright © 2011-present, Encode OSS Ltd .

Ace ‘Editor in the Browser’ – Documentation

Ace ‘Editor in the Browser’ – Documentation

The documentation for Ace – where is it ?

Summary

The Ace documentation isn’t that hard to find but you do need to know where to look

Ace in the hole

The Ace project provides a customizable, embeddable code editor for web applications. It’s written solely in JavaScript and is really very impressive.

You can see it in action at their demo page (which frankly is a bit bare bones) or at the Cloud9 project for which Ace is the starting point.

Documentation is where ?

You can download the Ace distribution from https://github.com/ajaxorg/ace – you need the ‘Downloads’ button at the top right.

Once you’ve done that you’ll find there’s nothing worth reading in the docs folder within the distribution.

Instead what you need to do is go visit the Ace wiki at Github. It took me a while to work this out (with the help of the Ace user group forum) so I hope it will save some others the trouble.

Sphinx – how to make autodoc really automatic ?

Automating sphinx.ext.autodoc

A tool to help use the ‘autodoc’ facilties of Sphinx.

Summary

Sphinx has a great extension,sphinx.ext.autodoc, which imports the modules you want to document and uses the docstrings as the basis for the documentation. A script I’ve just found makes using sphinx.ext.autodoc even easier.

generate_modules.py

Although the sphinx.ext.autodoc extension reduces the work of creating Sphinx source files a great deal I still found myself having to create a set of files which corresponded to the modules in a project. This was a bit of a bore particularly as I like to start creating documentation early in a project and so modules would come and go during development.

On a number of occasions I wished I had a script to automatically create the source files needed … well it turns out that Etienne Desautels has already done the heavy lifting and written generate_modules.py which does just what I want.

Making use of it

generate_modules.py is completely independent of Sphinx. Just download it from the above location and run it as

>python generate_modules.py --help

Usage: generate_modules.py [options] <package path> [exclude paths, ...]

Note: By default this script will not overwrite already created files.

Options:
 -h, --help            show this help message and exit
 -n HEADER, --doc-header=HEADER
                       Documentation Header (default=Project)
 -d DESTDIR, --dest-dir=DESTDIR
                       Output destination directory
 -s SUFFIX, --suffix=SUFFIX
                       module suffix (default=txt)
 -m MAXDEPTH, --maxdepth=MAXDEPTH
                       Maximum depth of submodules to show in the TOC
                       (default=4)
 -r, --dry-run         Run the script without creating the files
 -f, --force           Overwrite all the files
 -t, --no-toc          Don't create the table of content file

Most of this is pretty self-explanatory.

My index.rst looks like this :

Welcome to pySourceAid's documentation!
=======================================

Contents:
=========

.. toctree::
:maxdepth: 2

overview.rst

Modules
===============

.. toctree::
:maxdepth: 20
:numbered:
:glob:

modules/*

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

And that line in the index.rst

    modules/*

… means that autodoc is going to go looking for source files corresponding to each of the modules in a directory called modules. As a result when I run generate_modules.py I use a command like this

python generate_modules.py --suffix=rst --dest-dir=C:\myproject\docs\source\modules C:\myproject\src

Where the modules are living in C:\myproject\src

Environment

This blog post is based on some work done using : Python 2.6 and Sphinx 1.0.5

Sphinx Documentation Generator – Tutorial 2

Sphinx – first project output

A series of tutorials on using the Sphinx Documentation system aimed at absolute beginners.

Summary

In this second part of my Sphinx Tutorial we use the ‘quickstart’ script provided with Sphinx to quickly produce a basic set of documentation source files.

Our First Sphinx Project

Sphinx has a great way to get you started and that’s the ‘quickstart’ script (you’ll find sphinx-quickstart-script.py in the Scripts directory of your Python installation). Quickstart walks you through a series of questions to produce a basic set of the files you’ll need to produce your documentation.

Quickstart is pretty easy to use and even more so when your aim is to produce something very basic (which is the aim of this tutorial).

We’ll just step through the more important bits here :

Specify where you want the Documentation to be created

Sphinx is going to create some files and a few directories so choose where you want those to be created :
Enter the root path for documentation.
> Root path for the documentation [.]: C:\data\src\Sphinx\Test1

Specify a name for the Documentation:

What ever name you choose will appear in various places in the documentation so choose something you’re happy with

The project name will occur in several places in the built documentation.
> Project name: Sphinx Tutorial
> Author name(s): Richard Shea

Specify a version for the Documentation:

Similarly you’ll get the version number appearing in various parts of the output documenation

> Project version: 1.0.0

Specify if you want any clever stuff:

Sphinx is able to do all sorts of clever stuff apart from interpreting your RST files into beautiful output. We don’t want any of that for the first part of the tutorial so say ‘no’ to all of this.

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]:
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
> coverage: checks for documentation coverage (y/N) [n]:
> pngmath: include math, rendered as PNG images (y/N) [n]:
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:

Make it easy on yourself (at least to start with)

It’s perfectly reasonable to use build the Sphinx output by providing your own command line options but to get started with it’s helpful to allow Sphinx to help a little so say ‘yes’ to a .BAT or a makefile (depending on what’s your choice of poison).

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (Y/n) [y]:
> Create Windows command file? (Y/n) [y]:

The results of quickstart

So after all that what have we got ? Well we specified C:\data\src\Sphinx\Test1 as the output path and if we look in there we find we’ve got a build and a source directory (as well as the Makefile and make.bat we asked for). What we’re interested in to start with is source\index.rst.

Open it up in a text editor and you’ll see it looks like this :
.. Sphinx Tutorial documentation master file, created by
sphinx-quickstart on Sun Nov 1 18:08:19 2009.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

Welcome to Sphinx Tutorial's documentation!
===========================================

Contents:

.. toctree::
:maxdepth: 2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Next Steps

In the next part of this series, Sphinx – Absolute Beginners – Part 3, we’ll see how to make this file into either HTML or PDF output. In later parts of the series we’ll see how to use your existing Python code comments to produce automated documentation of your Python code.

Sphinx Documentation Generator – Tutorial 1

Sphinx – Absolute Beginners – Part 1

A series of tutorials on using the Sphinx Documentation system aimed at absolute beginners

Summary

Sphinx is a great tool that makes it easy to create good looking documentation in a range of output formats. If you’re a Python programmer it also makes it easy to use your existing docstring comments to form the basis of your documentation.

I’ve found using Sphinx for the first time a little difficult as much of the documentation seems to assume you know certain things. This series of posts provides a tutorial for the absolute beginner.

Ground Rules (for impatient programmers)

Now at this stage there’s a couple of things that are well worth knowing !

  • Sphinx is good at auto-documenting Python code but that’s not its primary role. If you’re a Python programmer looking to auto-document your code it takes a while to understand that a lot of the facilities in Sphinx are nothing to do with what you’re after and that can be confusing.
  • In Sphinx-land ‘the source files’ refer to the documentation configuration files. This confused me for a while whenever the term ‘source files’ was used I thought it meant my python source files.

Getting Spinx Installed

The prerequisites part of the Sphinx doco does a good job here but in summary:

  • You want to have installed Python 2.4 or better
  • Grab the source from the Sphinx Python Project Page or …
  • … just use easy_install -U Sphinx

Next Steps

Sphinx has a great way to get you started and that’s the ‘quickstart’ script. In the next part of this tutorial series we’ll cover how to quickly and easily produce your first Sphinx project.