django-paste

Pluggable, configurable, pastebin HTTP REST API

django-paste is a simple Django pluggable app of a code pasting and highlighting HTTP REST API, written using Django REST framework. It supports the CRUD operations on source code snippets and uses any existing user authentication system. Syntax highlighting is powered by Pygments.

Installation

The following Python versions are supported:

  • CPython: 3.6, 3.7, 3.8, 3.9

  • PyPy: 3.6

Django:

  • 2.0, 2.1, 2.2

  • 3.0, 3.1

  • Install via pip:

    $ pip install django-paste

  • Add it to your INSTALLED_APPS:

    INSTALLED_APPS = [
    # ...
    'paste.apps.PasteConfig',
]

  • Register the app’s URLs under a path of your choice:

    urlpatterns = [
    # ...
    path('some-path/', include('paste.urls')),
]

    where 'some-path/' could be any URL.

  • Optionally, configure the app settings.

  • Generate and run the database migrations:

    $ python manage.py makemigrations paste
$ python manage.py migrate

API

Endpoints

/

Snippet list

GET

List viewable snippets.

POST

Create new snippet.

/{snippet-id}/

Snippet detail

GET

View queried snippet.

PUT

Update queried snippet.

PATCH

Partially update queried snippet.

DELETE

Delete queried snippet.

/user/{user-id}/

User snippet list

GET

List queried user’s viewable snippets.

/{snippet-id}/highlight/

Snippet highlight

GET

View queried snippet’s highlighted content, as HTML. If full exists as a query parameter, get a full HTML document.

Content Types

The API can parse data of the following content types:

  • application/json

  • application/x-www-form-urlencoded

  • multipart/form-data

It can render its responses in the following formats:

  • application/json

  • text/html

A client can request the response in a specific format either by sending an Accept header, or by appending .json or .api to the URL, for JSON and HTML content, respectively.

Fields

The following fields of snippets have a value automatically generated for them and hence clients are not supposed to explicitly provide them:

The rest of the fields are optional, except for content:

In more detail:

id
Type

number

Read only

yes

The snippet’s primary key in the database.

content
Type

string

Required

yes

The source code of the snippet.

language
Type

string

The programming language of the snippet. Must be a valid Pygments lexer name.

style
Type

string

The style the snippet should be highlighted with. Must be a valid Pygments style name.

line_numbers
Type

boolean

Default

DEFAULT_LINE_NUMBERS

Whether line numbers should be shown in the snippet’s highlight view.

embed_title
Type

boolean

Default

DEFAULT_EMBED_TITLE

Whether the title of the snippet should be included in its full highlight view.

private
Type

boolean

Default

DEFAULT_PRIVATE

Whether the snippet should be only viewable by its owner and staff users.

created
Type

string

Read only

yes

The datetime of the snippet’s creation.

updated
Type

string

Read only

yes

The datetime of the snippet’s last modification.

owner
Type

number / null

Read only

yes

The primary key in the database of the user who created the snippet. If that user was unauthenticated, this field is null.

Settings

Note

Every time you change settings related to the database, you should then generate and run database migrations.

All the settings of django-admin have default values, which can get overriden. This is done by defining a PASTE dict in your Django project’s settings file, whith any of the following keys:

DEFAULT_EMBED_TITLE
Type

bool

Default

True

Whether the title of a snippet should be included in its full highlight view, in case the relative field is not set for it.

DEFAULT_LANGUAGE
Type

str

Default

'text'

The Pygments lexer name (programming language) used for the highlighting of a snippet, in case the relative field is not set for it, and the GUESS_LEXER setting is False.

DEFAULT_LINE_NUMBERS
Type

bool

Default

True

Whether line numbers should be shown in a snippet’s highlight view, in case the relative field is not set for it.

DEFAULT_PRIVATE
Type

bool

Default

False

Whether a snippet should be only viewable by its owner and staff users, in case the relative field is not set for it.

DEFAULT_STYLE
Type

str

Default

'default'

The Pygments style for the highlighting of a snippet, in case the relative field is not set for it.

FORBID_ANONYMOUS
Type

bool

Default

False

Whether to forbid any API access to unauthenticated users.

FORBID_ANONYMOUS_CREATE
Type

bool

Default

False

Whether to forbid snippet creation to unauthenticated users.

FORBID_ANONYMOUS_LIST
Type

bool

Default

False

Whether to forbid snippet listing to unauthenticated users.

FORBID_LIST
Type

bool

Default

False

Whether to forbid snippet listing to non-staff users.

GUESS_LEXER
Type

bool

Default

True

Whether to let Pygments guess a lexer for the highlighting of a snippet, in case the language field is not set for it. If this setting is False and a language is not set for a snippet, the DEFAULT_LANGUAGE setting is considered for its highlighting.

TITLE_MAX_LENGTH
Type

int

Default

100

The maximum character length for the title field of snippets.