letterboxd 0.3.0
Python 3 wrapper for the Letterboxd API
License: MIT
Requires Python: >=3.6
Keywords: api,movie,film,movie database,movie review,watchlist,letterboxd,moviedb

.. Semaphore Build Status
.. image:: https://semaphoreci.com/api/v1/bobtiki/letterboxd/branches/master/badge.svg
   :target: https://semaphoreci.com/bobtiki/letterboxd

.. Travis CI build status
.. image:: https://travis-ci.org/bobtiki/letterboxd.svg?branch=master
   :target: https://travis-ci.org/bobtiki/letterboxd

.. ReadTheDocs document status
.. image:: https://readthedocs.org/projects/letterboxd/badge/?version=latest
   :target: https://letterboxd.readthedocs.io/en/latest/?badge=latest

Letterboxd
==========

Python 3 implementation of the `Letterboxd API v0 <http://api-docs.letterboxd.com/>`_.

* PyPI package: https://pypi.org/project/letterboxd/
* GitHub repo: https://github.com/bobtiki/letterboxd
* Documentation: https://letterboxd.readthedocs.io
* Free software: MIT license

Python ≥3.6 is required.

.. warning::

    **THIS PROJECT IS CURRENTLY IN ALPHA:**

    - It may be broken.
    - What is working now may break between now and v1.0
    - Initial focus is on implementing endpoints related to retrieving watchlists and other lists for users.

Letterboxd API Access
---------------------

Letterboxd has posted an `example Ruby client <https://github.com/grantyb/letterboxd-api-example-ruby-client>`_, but as they say in the readme there:

    Although the Letterboxd API isn’t public yet (as at 2017-06-12), we have seeded some developers with API keys.

If you need more information about API access, please see `<https://letterboxd.com/api-coming-soon/>`_.


Changelog
=========

All notable changes to this project will be documented in this file.

The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_
and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.

[Unreleased]
-----------------------------

[0.3.0] - 2018-07-22
-----------------------------

ADDED
.....

- Issue and pull request templates
- Code of Conduct
- Coverage for Letterboxd API endpoints
    - /auth/forgotten-password-request
    - /auth/username-check
    - /list/{id}
    - /list/{id} [PATCH]
    - /list/{id} [DELETE]
    - /list/{id}/comments
    - /list/{id}/comments [POST]
    - /list/{id}/entries
    - /list/{id}/me
    - /list/{id}/me [PATCH]
    - /list/{id}/report [POST]
    - /list/{id}/statistics
    - /lists
    - /lists [POST]
    - /me [PATCH]
- A TON more pytest unit tests, and made existing ones more comprehensive

CHANGED
.......

- Internally refactored API object definitions into their own file, for pytest
- Internally changed some variable names to better reflect Letterboxd API nomenclature (I don't *think* this affects any method arguments.)

FIXED
.....

- Removed mutable default arguments on several methods


[0.2.6] - 2018-07-04
-----------------------------

CHANGED
.......

- Getting the Travis CI integration with PyPI to work properly.

[0.2.5] - 2018-07-04 [YANKED]
-----------------------------

[0.2.4] - 2018-07-04
-----------------------------

CHANGED
.......

- Getting ``bumpversion`` to work properly.

[0.2.3] - 2018-07-04 [YANKED]
-----------------------------

[0.2.2] - 2018-07-04 [YANKED]
-----------------------------

[0.2.1] - 2018-07-04 [YANKED]
-----------------------------

[0.2.0] - 2018-07-04
--------------------

Added
.....

- This ``CHANGELOG.rst``
- Converted ``README.md`` to ``.rst``
- Documentation written with reStructuredText and Sphinx, being built to `Read the Docs <https://letterboxd.readthedocs.io/>`_
- Added a number of defaults and tests as provided in `cookiecutter-pypackage <https://github.com/audreyr/cookiecutter-pypackage>`_
- Added an easy initializer with ``import letterboxd`` and then ``letterboxd.new()``
- ``User.refresh_token()`` to refresh the user authentication oAuth token
- Coverage for Letterboxd API endpoints:
    - /film/{id}/members
    - /film/{id}/report
    - /film/{id}/statistics
    - /films
    - /films/film-services
    - /films/genres
    - /film-collection/{id}
    - /search

Changed
.......

- All api-calling methods now return the dictionary from the response JSON, instead of the entire ``requests.Response``.

[0.1.0] - 2018-06-24
--------------------

Added
.....

- First public version! Version 0.1.0a `tagged on GitHub <https://github.com/bobtiki/letterboxd/releases/tag/v0.1.0a>`_, and `posted to PyPI <https://pypi.org/project/letterboxd/>`_.
- letterboxd, api, user, auth, member, and film modules.
- coverage for Letterboxd API endpoints:
    - film
    - /film/{id}
    - /film/{id}/availability — this data is first-party only
    - /film/{id}/me
    - /me
    - /member/{id}/watchlist

Changelog format
----------------

- Each version should:
    - List its release date in ISO 8601 format (YYYY-MM-DD).
    - Group changes to describe their impact on the project, as follows:
        - ``Added`` for new features.
        - ``Changed`` for changes in existing functionality.
        - ``Deprecated`` for once-stable features removed in upcoming releases.
        - ``Removed`` for deprecated features removed in this release.
        - ``Fixed`` for any bug fixes.
        - ``Security`` to invite users to upgrade in case of vulnerabilities.
    - Take a look at `this checklist for packaging a new version <http://www.sherifsoliman.com/2016/09/30/Python-package-with-GitHub-PyPI/>`_, and `this one <https://cookiecutter-pypackage.readthedocs.io/en/latest/pypi_release_checklist.html>`_