Tinycards Python API

An unofficial Python API for Tinycards by Duolingo.

Installation

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 .

Usage

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')
None

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.

Development

Local setup

• Install virtualenv and create a so-called "virtual", dedicated environment for the tinycards-python-api project:

  $ pip install -U virtualenv
  $ cd /path/to/tinycards-python-api
  $ virtualenv .
  $ source bin/activate
  (tinycards-python-api) $

• Install dependencies within the virtual environment:

  (tinycards-python-api) $ pip install -e .
  (tinycards-python-api) $ pip install -r test-requirements.txt

• Develop and test at will.

• Leave the virtualenv:

  (tinycards-python-api) $ deactivate
  $

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
   direnv: export +TINYCARDS_IDENTIFIER +TINYCARDS_PASSWORD

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.