Skip to main content


Project description


*Reading List* is a service that aims to synchronize a list of articles URLs
between a set of devices owned by a same account.

|travis| |readthedocs|

.. |travis| image::

.. |readthedocs| image::
:alt: Documentation Status


* `Online documentation <>`_

Run locally

*Reading List* is based on top of the `cliquet <>`_ project, and
as such, please refer to cliquet's documentation for more details.

For development

By default, *Reading List* persists the records and internal cache in a PostgreSQL

The default configuration will connect to the ``postgres`` database on
``localhost:5432``, with user/password ``postgres/``postgres``. See more details
below about installation and setup of PostgreSQL.


make serve

Using Docker

*Reading List* uses `Docker Compose <>`_, which takes
care of running and connecting PostgreSQL:


docker-compose up


By default, *Reading List* relies on Firefox Account OAuth2 Bearer tokens to authenticate

See `cliquet documentation <>`_
to configure authentication options.

Install and setup PostgreSQL

(*requires PostgreSQL 9.3 or higher*).

Using Docker


docker run -e POSTGRES_PASSWORD=postgres -p 5434:5432 postgres


On debian / ubuntu based systems:


apt-get install postgresql postgresql-contrib

By default, the ``postgres`` user has no password and can hence only connect
if ran by the ``postgres`` system user. The following command will assign it:


sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'postgres';"


Assuming `brew <>`_ is installed:


brew update
brew install postgresql

Create the initial database:


initdb /usr/local/var/postgres

Install libffi


On debian / ubuntu based systems::

apt-get install libffi-dev


Assuming `brew <>`_ is installed, libffi installation becomes:


brew install libffi pkg-config

Run tests


make tests

Running in production

Recommended settings

Most default setting values in the application code base are suitable for production.

But the set of settings mentionned below might deserve some review or adjustments:


cliquet.http_scheme = https
cliquet.batch_max_requests = 25
cliquet.delete_collection_enabled = false
cliquet.basic_auth_enabled = false
fxa-oauth.cache_ttl_seconds = 3600


For an exhaustive list of available settings and their default values,
refer to `cliquet source code <>`_.

PostgreSQL setup

In production, it is wise to run the application with a dedicated database and


postgres=# CREATE USER produser;
postgres=# CREATE DATABASE proddb OWNER produser;

On the first app run, the tables and objects are created. Currently, this process
requires superuser privileges (or a ``BackendError`` might occur).

Grant superuser temporarily:


postgres=# ALTER USER produser SUPERUSER;

Run the application.

Revoke superuser privilege:


postgres=# ALTER USER produser NOSUPERUSER;


Alternatively the SQL initialization files can be found in the
*cliquet* source code (``cliquet/cache/postgresql/schemal.sql`` and


Using a `connection pool <>`_ is highly recommended to
boost performances and bound memory usage (*work_mem per connection*).

Running with uWsgi

If you want to run the application using uWsgi, you can use
the provided **app.wsgi** file and this command::

uwsgi --ini config/readinglist.ini

You can tweak the uWsgi configuration in the ini file in
the dedicated **[uwsgi]** section.

If you are using a different ini file, you need to set
its path in the **READINGLIST_INI** environment variable.


This document describes changes between each past release.

1.1.0 (2015-03-18)

**Breaking changes**

* `` now uses UUID as record primary key (mozilla-services/cliquet#70)
* Settings ``cliquet.session_backend`` and ``cliquet.session_url`` were
renamed ``cliquet.cache_backend`` and ``cliquet.cache_url`` respectively.
* FxA user ids are not hashed anymore (mozilla-services/cliquet#82)
* Setting ``cliquet.retry_after`` was renamed ``cliquet.retry_after_seconds``
* OAuth2 redirect url now requires to be listed in
``fxa-oauth.webapp.authorized_domains`` (e.g. ``*``)
* Batch are now limited to 25 requests by default (mozilla-services/cliquet#90)
* OAuth relier has been disabled by default (#193)

**New features**

* Every setting can be specified via an environment variable
(e.g. ``cliquet.storage_url`` with ``CLIQUET_STORAGE_URL``)
* Logging now relies on `structlog <>`_ (mozilla-services/cliquet#78)
* Logging output can be configured to stream JSON (mozilla-services/cliquet#78)
* New cache backend for PostgreSQL (mozilla-services/cliquet#44)
* Documentation was improved on various aspects (mozilla-services/cliquet#64, mozilla-services/cliquet#86)
* Handle every backend errors and return 503 errors (mozilla-services/cliquet#21)
* State verification for OAuth2 dance now expires after 1 hour (mozilla-services/cliquet#83)
* Add the preview field for an article (#156)
* Setup the readinglist OAuth scope (#16)
* Add a uwsgi file (#180)

**Bug fixes**

* FxA OAuth views errors are now JSON formatted (mozilla-services/cliquet#67)
* Prevent error when pagination token has bad format (mozilla-services/cliquet#72)
* List of CORS exposed headers were fixed in POST on collection (mozilla-services/cliquet#54)
* Fix environment variables not overriding configuration (mozilla-services/cliquet#100)
* Got rid of custom *CAST* in PostgreSQL storage backend to prevent installation
errors without superuser (ref #174, mozilla-services/cliquet#99)

1.0 (2015-03-03)

**Breaking changes**

- Most configuration entries were renamed, see `config/readinglist.ini`
example to port your configuration
- Status field was removed, archived and deleted fields were added
(requires a database flush.)
- Remove Python 2.6 support

**New features**

- Add the /fxa-oauth/params endpoint
- Add the DELETE /articles endpoint
(Needs cliquet.delete_collection_enabled configuration)
- Add the Response-Behavior header on PATCH /articles
- Add HTTP requests / responses examples in the documentation
- Use Postgresql as the default database backend

**Internal changes**

- Main code base was split into a separate project
`Cliquet <>`_
- Perform continuated pagination in loadtests
- Use PostgreSQL for loadtests

0.2.2 (2015-02-13)

**Bug fixes**

- Fix CORS preflight request permissions (PR #119)

0.2.1 (2015-02-11)

**Breaking changes**

- Internal user ids for FxA are now prefixed, all existing records
will be lost (refs #109)

**Bug fixes**

- Fix CORS headers on validation error responses (ref #104)
- Fix handling of defaults in batch requests (ref #111, #112)

0.2 (2015-02-09)

**Breaking changes**

- PUT endpoint was disabled (ref #42)
- ``_id`` field was renamed to ``id`` (ref PR #91)
- FxA now requires a redirection URL (ref PR #69)

**New features**

- URLs uniques by user (ref #20)
- Handle conflicts responses (ref #45)
- Conditional changes for some articles attributes (ref #6)
- Batching support (ref #2)
- Pagination support (ref #25)
- Online documentation available at (ref PR #73)
- Basic Auth nows support any user/password combination (ref PR #78)

**Bug fixes**

- ``marked_read_by`` was ignored on PATCH (ref PR #72)
- Timestamp was not incremented on DELETE (ref PR #95)
- Fix number of bugs regarding support of CORS in error views (ref PR #105)
- Previous Basic Auth could impersonate FxA user (ref PR #78)

0.1 (2015-01-30)

- Allow Cors (#67)
- Log incomming request to the console (#65)
- Add timestamp for 304 and 412 response (#40)
- Add time vector to GET /articles and GET /articles/<id> (#4)
- Preconditions Headers for Update and Creation (#60)
- Provide number of items in headers of GET /articles (#39)
- Check for filter values (#58)
- Handle article title length (#37)
- Support min, max and no keywords filters (#43)
- Prevent to modify read-only fields (#26)
- Filtering and sort querystring (#44)
- Redis storage (#50)
- Handle errors (#24 - #49)
- Add loadtests (#47)
- Handle API version in URL (#33)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for readinglist, version 1.1.0
Filename, size File type Python version Upload date Hashes
Filename, size readinglist-1.1.0.tar.gz (16.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page