Clever Python bindings
Python Shell
Latest commit a754b29 Sep 18, 2017 @meliaj meliaj Bump version

Clever Python bindings


Clever is moving to a community supported model with our client libraries. We will still respond to and merge incoming PRs but are looking to turn over ownership of these libraries to the community. If you are interested, please contact our partner-engineering team at


From PyPi:

    $ pip install clever


    $ easy_install clever

Or from source:

    $ python install


Get started by importing the clever module and setting your authentication method:

    import clever

The clever module exposes classes corresponding to resources:

  • Contact
  • District
  • DistrictAdmin
  • School
  • SchoolAdmin
  • Section
  • Student
  • Teacher
  • Event

Each exposes a class method all that returns a list of all data in that resource that you have access to. Keyword arguments correspond to the same query parameters supported in the HTTP API, except that limit and page are not supported (pagination is handled automatically).

    schools = clever.School.all() # gets information about all schools you have access to
    schools = clever.School.all(where=json.dumps({'name': 'Of Hard Knocks'}))
    schools = clever.School.all(sort='state')

If you'd like more control over pagination, or to limit the number of resources returned, use the iter class method:

    students = clever.Student.iter()
    for i in range(0,2000):

You may also use the starting_after or ending_before parameters with the iter method:

    students = clever.Student.iter(starting_after="530e5960049e75a9262cff1d")
    for s in students:

The retrieve class method takes in a Clever ID and returns a specific resource. The object (or list of objects in the case of all) supports accessing properties using either dot notation or dictionary notation:

    demo_school = clever.School.retrieve("4fee004cca2e43cf27000001")
    assert == 'Clever Academy'
    assert demo_school['name'] == 'Clever Academy'


The library comes with a basic command-line interface:

    $ clever districts all
    Running the equivalent of:
    curl -H "Authorization: Bearer DEMO_TOKEN"
    Starting new HTTPS connection (1):
    API request to returned (response code, response body)     of (200, '{"data":[{"data":{"name":"Demo District","id":"4fd43cc56d11340000000005"},"uri":"/v1.1/districts/4fd43cc56d11340000000005"}],"links":[{"rel":"self","uri":"/v1.1/districts"}]}')
    Result (HTTP status code 200):
    {"data":[{"data":{"name":"Demo District","id":"4fd43cc56d11340000000005"},"uri":"/v1.1/districts/4fd43cc56d11340000000005"}],"links":[{"rel":"self","uri":"/v1.1/districts"}]}

Run clever -h to see a full list of commands.


Questions, feature requests, or feedback of any kind is always welcome! We're available at



pip install -r requirements.txt


python -m unittest discover test


Update VERSION and and run to publish a new version of the library.

In order to publish to PyPI you will need a .pypirc file in your $HOME directory with the following contents:

index-servers =

username: ****
password: ****

The username and password are in 1Password for Teams under PyPI.