Python wrapper for the Liquid Planner REST API.
The code is inspired by PyXero, and aims to offer an ORM style of accessing the API.
The library is available on PyPI and can be installed with either pip or easy_install:
pip install pyliquidplanner
Alternatively, if you'd like to install the latest from source:
pip install --upgrade https://github.com/impulse-cloud/pyliquidplanner/tarball/master
In addition to the instructions shown here, you will need to follow the Liquid Planner API Guide and the Types Documentation to see which fields are available.
Use your Liquid Planner login to construct some credentials:
>>> from liquidplanner.auth import BasicCredentials
>>> credentials = BasicCredentials(<email>, <password>)
Then create an API instance:
>>> from liquidplanner import LiquidPlanner
>>> lp = LiquidPlanner(credentials)
You can then access the various types of entities by name. For example, here is a list of all the projects in your workspace:
>>> projects = lp.projects.all()
>>> for p in projects:
>>> print p['name']
With the exception of account
and workspaces
, all other entities require a workspace to be specified. When instantiated, the API requests a list of available workspaces and defaults to the first returned. You can disable this check by passing the use_first_workspace
argument.
>>> lp = LiquidPlanner(credentials, use_first_workspace=False)
You must then set the API's workspace_id
manually.
>>> workspaces = lp.workspaces.all()
>>> lp.workspace_id = workspaces[1]['id']
The following entities are supported at present:
- Account
- Workspaces
- Activities
- Checklist Items
- Clients
- Comments
- Custom Fields
- Documents
- Events
- Folders
- Links
- Members
- Milestones
- Packages
- Projects
- Tags
- Tasks
- Teams
- Timesheets
- Tree Items
- Webhooks
This library wraps the objects returned in a dict
like object. This is done so that related
items can be accessed via the objects returned (see Associated Objects below). Otherwise the data is returned as-is, except for dates which are converted into Python datetime.datetime
objects.
Use all()
to get a full list of entities.
>>> all_clients = lp.clients.all()
Most API options are supported, including:
include
- fetch related entities toofilters
- filter the list of items returnedorder
- sort order of resultslimit
- limit the number of objects returned
Use get()
to fetch a specific entity by id.
>>> client = lp.clients.get(1234)
Most API options are supported, including:
include
- fetch related entities toodepth
- max depth when fetching tree items
Use create()
to insert a new entity.
Note: The LiquidPlanner REST API requires the data to be wrapped with the single entity name. For example {'client': {'name': 'My Client'}}
. This library takes care of the outer part, so you only need to worry about {'name': 'My Client'}}
.
>>> client = lp.clients.create({'name': 'My Client'})
Updating records is similar to creating, but the record id must be supplied.
>>> client = lp.clients.update(1234, {'name': 'New Client Name'})
The objects returned by all()
and get()
look and behave like Python dict
s, but have a few properties available that allow access to associated objects. These properties have all the functionality of the main API endpoints.
For example, you can retrieve comments for a given task:
>>> task = lp.tasks.get(1234)
>>> comments = task.comments.all()
Or create a comment for a given task:
>>> task = lp.tasks.get(1234)
>>> comment = task.comments.create({"description": "This is my comment"})
Updating and deleting works similarly.
Note: This functionality is not available when you use the include
parameter to make associated objects available for an all()
or get()
request. Only the outer object(s) have associated objects available.
For certain objects, the API supports various convenince methods. The wrapper does not attempt to filter the convenience methods to their applicable object types, it is up to the developer to use the Liquid Planner API Guide.
Supported convenience methods:
- Tree Items
- Update Assignment
- Reorder Assignments
- Delete Assignment
- Events, Projects, Tasks, etc.
- Move Before / After
- Tasks
- Package Before / After
- Track Time
- Timer Start / Stop / Commit / Clear
- Documents
- Thumbnail
- Download
- Workspaces
- Comment Stream
- Upcoming Tasks
- Changes
This library is very new and still a work in progress. Some things I would like to support in future include:
- Support for the 'convenience methods' (e.g. assignments, re-ordering)
- Save and retrieve of attachments
- More tests
To run the unit tests, run the following from the root directory of the project:
$ python setup.py test
This is will install any test dependencies (Mock) into your environment and execute the unit tests.
Contributions are most welcome by submitting a pull request. Please try to include test coverage of any new features or bug fixes.
If you have any problems with PyLiquidPlanner, you can log an issue on GitHub.