Tinycards Python API

Build Status Coverage Status Codacy Badge Python Versions PyPI Version PyPI Status License: MIT

An unofficial Python API for Tinycards by Duolingo.


Install from PyPI

The easiest way to get started is to simple install the library like so:

$ pip install tinycards

Install from source

If you want to modify the library's source code and try out your changes locally, you might want to consider building from source which works like follows:

  1. Make sure Python with Setuptools is installed.
  2. From the project's root folder, install using pip:
    $ pip install .


Below is a list of some of the most common functions. For a more practical example, see the csv_to_deck.py script.

Initialise a new client

>>> # A new client with the given identification (e.g., mail address) and password.
>>> client  = tinycards.Tinycards('identification', 'password')
'Logged in as 'username' (user@email.com)'
>>> # If no identification or password are specified, they are taken from ENV.
>>> client  = tinycards.Tinycards()
'Logged in as 'username' (user@email.com)'

Get info about the currently logged in user.

>>> user = client.get_user_info()
  username: 'bachman',
  email: 'bachman@aviato.com',
  fullname: 'Erlich Bachman',

Get all decks of a user

>>> all_decks = client.get_decks()
>>> [deck.title for deck in all_decks]
['Deck 1', 'Deck 2', 'Deck 3']

Update an existing deck

>>> deck_1 = client.find_deck_by_title('Deck 1')
>>> deck_1.title = 'Deck 1.1'
>>> client.update_deck(deck_1)
  'title': 'Deck 1.1',

Delete an existing deck

>>> deck = client.find_deck_by_title('Some Deck')
  'title': 'Some Deck',
  'id': '8176b324-addc-495d-aadc-fad005e5b439'
>>> client.delete_deck(deck.id)
  'title': 'Some Deck',
  'id': '8176b324-addc-495d-aadc-fad005e5b439'
>>> deck = client.find_deck_by_title('Some Deck')

Release a new Version

  1. Bump the version in setup.py.
  2. Push a new tag to GitHub:
    1. git tag 0.01
    2. git push origin 0.01
  3. The Travis build will deploy the release to PyPI.


Local setup

Run Tests

  1. In order to run the integration tests, you need to set the enviroment variables TINYCARDS_IDENTIFIER and TINYCARDS_PASSWORD. direnv may be useful to set these automatically & permanently:

    $ touch .envrc
    $ echo "export TINYCARDS_IDENTIFIER=<id>" >> .envrc
    $ echo "export TINYCARDS_PASSWORD=<pass>" >> .envrc
    $ direnv allow
    direnv: loading .envrc
  2. Then, from the project's root directory:

    1. run the unit tests:

      $ pytest --ignore tests/client_test.py --ignore tests/integration_test.py --cov tinycards
    2. run all tests: WARNING: the integration tests DELETE all the decks in the account used to test. Please ensure you either are using a dedicated test account, or do not care about losing your existing decks.

      $ pytest --cov tinycards
  3. When all tests were successful, pytest will exit with 0.