Skip to main content

D2LValence client library for Python.

Project description

======================================
Desire2Learn Client Library for Python
======================================

Our Python client library SDK is currently in experimental form. Currently, we
use this libary as a quick way to rapidly, and interactively, prototype or
hand-test back-end LMS services for trouble shooting purposes: it's not intended
for rigorous production use.

**Feedback and contributions welcome**. If you have any feedback or additions
you'd like to make to the Python client library, please feel free to
contact Valence@Desire2Learn.com to coordinate with our development team.

.. note::

You can find the latest version of this documentation, and related
topics in our
`Valence API documentation <http://docs.valence.desire2learn.com/clients/python/index.html>`_.

Installation
============
You can find the
`latest build <http://code.google.com/p/desire2learn-valence/downloads/list?q=label:pythonlatestclient>`_
of the client library SDK on our repository download page.

**Dependencies**. In order to use the Python client library SDK, you'll need to
first ensure you have a working Python development environment:

* Python 3 (the reference environment uses Python 3.3).

* The `Requests Python package <http://docs.python-requests.org/en/latest/index.html>`_
gets used in our :py:mod:`service <d2lvalence.service>` module to make the
calls through to the back-end service, and in our :py:mod:`auth <d2lvalence.auth>`
module so that you can use a calling user context object as an authentication
helper for Requests.

* The `Bottle Python package <http://bottlepy.org/docs/dev/>`_ if you want to
use the samples available in conjunction with this client library (not a
dependency for the client library itself).


Modules
=======
The Python library divides functionality into a number of modules:

**Authentication**. The :py:mod:`d2lvalence.auth` module provides assistance for
the authentication needed to invoke Valence APIs. You use the module's functions
(and perhaps also classes) to create a
:py:class:`calling user context <d2lvalence.auth.D2LUserContext>` object that
you can then employ in conjunction with the Reqeusts package as an
authentication helper.

**Data**. The :py:mod:`d2lvalence.data` module provides classes to encapsulate
the JSON data structures passed back and forth through the Valence APIs. All the
classes inherit from a :py:class:`D2LStructure generic base class
<d2lvalence.data.D2LStructure>`.

Note that currently we drive additions to the `data` module by the needs of our
samples and ongoing testing: it does not cover all the structures present in the
Valence API.

**Service**. The :py:mod:`d2lvalence.service` module contains a suite of helper
functions you can use to make Valence API calls and partially digest the data
results passed back. In general, the data passed back by a service function is
either a pre-defined class inheriting from :py:class:`D2LStructure
<d2lvalence.data.D2LStructure>`, or one or more dictionaries formed from the
retrieved JSON data.


.. :changelog:

History
-------

0.1.13 (2013-04-17)
+++++++++++++++++++
* enhanced `service` functions to allow for passing keyword args down into the
requests library making the outgoing HTTP calls

* explicitly added 'application/json' content type header to service actions
sending JSON to the service

* modified multipart/mixed upload functions in `service` module to cope with
changes in requests v1.2.0 around setting the Content-Type header for the
upload action: now the functions use sessions around a prepped-request object,
consistent with requests library new pattern for messing with the headers/body
of an HTTP request

* added `data.D2LNewsAttachment` child of `data.D2LFile` to handle adding
attachments to news events; added `data.NewsItemData` structure to support
creation of news events; added new routes to support more news actions

* added `data.CreateEnrollmentData` structure to handle structure sent during
enrollment creation; added service routes around user enrollment (delete,
create)

* added `data.GroupCategoryDataFetch` and service methods to support some group
routes; added routes around group org units

* added `data.GradeObjectCreateData` and re-factored `data.GradeObject`, as well
as the derived grade object type classes, to separate structures for fetching
and creating grade objects; added `data.GradeObjectCategory` and
`data.GradeObjectCategoryData` to support grade object category routes; added
service routes around grade objects, grade categories, grade values


* added factory methods to the incoming-grade-value structures for easier
creation; added `data.IncomingFinalAdjustedGradeValue` structure for updating
final adjusted grade value

* added data structures and routes around course completion

* added routes around calendar events

* fixed `service.get_organization_info` to return an Organization JSON
structure, and not raw request content.

* fixed `service.get_all_my_grade_values_for_org` to return grade value
instances, instead of grade object instances

0.1.12 (2013-01-23)
+++++++++++++++++++
* fixed bug in D2LUserContext's implementation as a requests.auth.AuthBase so
that it more properly handles API routes that contain characters that would be
URL escaped by the requests library

0.1.11 (2013-01-04)
+++++++++++++++++++
* revised `auth.D2LAppContext.create_url_for_authentication` to include an
`encrypt_request` parameter (true by default) to allow generation of
for-authentication URLs that do not use HTTPS

* added `data.D2LDropboxSubsmission` and several service functions to fill out
support for the dropbox routes

* fixed parm name in get dropbox folder route

* fixed the `ExternalEmail` properties for `data.CreateUserData` and
`data.UpdateUserData` to provide better support for having `None` values
(which will translate to `null` when serialized to JSON)

* added `service.update_user()` for updating user records

* fixed the `RoleId` property for `data.CreateUserData` to have an empty default
value rather than a numeric default (which probably isn't a useful default for
anyone)

* added `data.UserPasswordData` and service methods to support the user password
routes (deleting, changing, resetting)

* added `data.Organization` and `data.OrgUnit` and service methods to support
routes that query the org structure

* added `data.EnrollmentData` and service functions to fill out support for
enrollment routes

* added `data.IncomingGradeValue` and its derived classes, and service functions
to fill out support for grades routes

* added `data.NewsItem` and several service functions to fill out support for
the news routes

* added support to `service` module to try and support pre-1.0.0 requests
package as well as post-1.0.0 versions.

0.1.10 (2012-12-18)
+++++++++++++++++++
* revised `data` and `service` modules to update for compatibility with requests
package post version 1.0.0

0.1.9 (2012-10-15)
++++++++++++++++++
* added data and service functions for Learning Repostory routes

* added data and service functions for course offering and content routes

* added data and service functions for discussion forum routes
* renamed utility functions in `data` module used for property set/getting to
suggest they should be internal and not directly used

* added default (empty) value for `DescriptorDict` property to the
`data.D2LLockerFile` class

* added `files` named parameter to post and put utility methods for simple file
post/puts

* fix `service.rename_group_locker_folder()` to properly form route

* cleanup service module to python-ify parameter names

0.1.8 (2012-08-30)
++++++++++++++++++
* added support to the `auth` module for building an anonymous user context
(context with no user ID/Key pair) -- clients can use such a context to make
calls to the various API Property/Version routes to query LMS for API versions

* moved auth to use direct `==` comparison to check for empty parameters instead
of use `in (singleItemList,)` pattern

* factored out process of fetching contents of Requests objects into a single
funtion, moved to examine `request.headers['content.type']` to determine how
to handle contents rather than just `try` to fetch r.JSON and default to
r.content

* repaired `service.check_versions()` to pass the `supported_version_request_array`
as json data

* fixed `service._simple_upload()` to seek underlying buffer stream to head
position before and after read, instead of trying to seek on the byte-string
we read the stream into

* added support to the `service` library for distinguishing between anonymous and
non-anonymous user contexts, and let version calls be made with anonymous
contexts, raise errors in the case of all other calls that demand a user context

* added more grade routes for fetching 'my' grades

0.1.7 (2012-08-10)
++++++++++++++++++
* added `service.get_profile_by_user_id()`

* added `data.LockerItem`, `data.LockerFolder`, `data.GroupLocker` to support
locker operations

* added to suite of locker functions to the `service` module to assist with locker
operations: this includes an example of how you might want to handle the
"simple upload" process for those Valence routes that use simple file upload

0.1.6 (2012-07-13)
++++++++++++++++++
* Fix bug in `update_social_media_url_by_url()`... we should look
for 'url'-keyed entries, not 'name'-keyed entries

* Some documentation revisions

* Remove 'exceptions' module as not utilized

0.1.5 (2012-07-11)
++++++++++++++++++
* Changed `D2LStructure.as_json()` to kick back a deep-copy of the encapsulated
data, instead of a ref to the instance's internal data structure

* Bug fixes

0.1.4 (2012-07-06)
++++++++++++++++++
* Refactoring and re-building of the libraries: moved data-structures into
`data` module and service-related functions into `service` module;
auth-related functionality remains in `auth`

* Re-worked samples to be more in line with design for the other client
libraries

0.1.0 (2012-06-02)
++++++++++++++++++
* Initial version

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 D2LValence, version 0.1.13
Filename, size File type Python version Upload date Hashes
Filename, size D2LValence-0.1.13.tar.gz (29.3 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