Skip to content

Commit

Permalink
Include docs stuff. This is lift-and-shift from drf-proxy-pagination
Browse files Browse the repository at this point in the history
  • Loading branch information
Andrew Dodd authored and Andrew Dodd committed Feb 24, 2017
1 parent e96ec11 commit 0ad5572
Show file tree
Hide file tree
Showing 3 changed files with 136 additions and 0 deletions.
23 changes: 23 additions & 0 deletions docs/css/extra.css
@@ -0,0 +1,23 @@
body.homepage div.col-md-9 h1:first-of-type {
text-align: center;
font-size: 60px;
font-weight: 300;
margin-top: 0;
}

body.homepage div.col-md-9 p:first-of-type {
text-align: center;
}

body.homepage .badges {
text-align: right;
}

body.homepage .badges a {
display: inline-block;
}

body.homepage .badges a img {
padding: 0;
margin: 0;
}
109 changes: 109 additions & 0 deletions docs/index.md
@@ -0,0 +1,109 @@
<div class="badges">
<a href="http://travis-ci.org/andrewdodd/drf-timeordered-pagination">
<img src="https://travis-ci.org/andrewdodd/drf-timeordered-pagination.svg?branch=master">
</a>
<a href="https://pypi.python.org/pypi/drf-timeordered-pagination">
<img src="https://img.shields.io/pypi/v/drf-timeordered-pagination.svg">
</a>
</div>

---

# drf-timeordered-pagination

Pagination utilities for Django REST Framework to allow for pagination by a mutable, but time-ordered field (like 'modified').

---

## Overview

Pagination utilities for Django REST Framework to allow for pagination by a mutable, but time-ordered field (like 'modified'). It provides results in a stable order (i.e. by 'modified') and ensures that the 'next' links will allow full walking of the list without omitting values, even if they mutate between calls.

In many ways this is similar to a 'Cursor based' pagination, but is designed to:
- Not require state on the server
- Be tailored to getting 'only the things that have updated since I last checked' from an API

## Important notes

The layout of the docs and the Git project were borrowed from:
- drf-proxy-pagination

## Requirements

* Python (2.7, 3.4+)
* Django (1.8+)
* Django REST Framework (3.1+)

## Installation

Install using `pip`...

```bash
$ pip install drf-timeordered-pagination
```

In `views.py`, hook up your own integration into the pagination, or use one of the provided ones like so:

```python

class ExampleClass(django.Model):
...
modified = DateTimeField(...)
...


from
class ExampleClassView(
ModifiedFilterApiViewSetMixin,
...,
viewsets.ModelViewSet)
...
```

## Example

http://api.example.org/examples/ gives default pagination.
http://api.example.org/examples/?modified_after=1900-01-01T00:00:00Z gives all examples, modified after (greater than) Midnight, 1 Jan 1900, in modified order
http://api.example.org/examples/?modified_from=1900-01-01T00:00:00Z gives all examples, modified from (greater than or equal to) Midnight, 1 Jan 1900, in modified order


## Testing

Install testing requirements.

```bash
$ pip install -r requirements.txt
```

Run with runtests.

```bash
$ ./runtests.py
```

You can also use the excellent [tox](http://tox.readthedocs.org/en/latest/) testing tool to run the tests against all supported versions of Python and Django. Install tox globally, and then simply run:

```bash
$ tox
```

## Documentation

To build the documentation, you'll need to install `mkdocs`.

```bash
$ pip install mkdocs
```

To preview the documentation:

```bash
$ mkdocs serve
Running at: http://127.0.0.1:8000/
```

To build the documentation:

```bash
$ mkdocs build
```
4 changes: 4 additions & 0 deletions mkdocs.yml
@@ -0,0 +1,4 @@
site_name: drf-timeordered-pagination
site_description: Pagination class for Django REST Framework to paginate by mutable time attribute
repo_url: https://github.com/andrewdodd/drf-timeorders-pagination
site_dir: html

0 comments on commit 0ad5572

Please sign in to comment.