Python Client

To simplify your life, webplan comes with a simple python client implementation for its REST API. The python client maps URL hooks to python functions, takes care of authentication, serialization and converts errors to exceptions. At its current state it does not does not feature much higher level abstractions. It’s provides just a simple way to call the REST API from python. For more details have look at REST API.

Examples

Importing Problems

Let’s assume you have some Problems that you want to import. You can do that like that:

>>> from webplanclient import Client
>>> from wpcommon import util

>>> # create a client
>>> client = Client('http://example.com', 'user', 'password')
>>> # import a problem
>>> problem = client.create_problem(
>>>   util.readfile('/somepath/problem1.pddl'),
>>>   util.readfile('/somepath/domain1.pddl'))
>>> # problem is just a dict as returned by the rest api
>>> problem
{u'equivalents': [], u'best_costs': None, u'hash': u'bc805cc705ecb4f60ecc156c9e77cb4f370b7908',
  u'tags': [
    {u'type': u'pddl_requirement', u'name': u'typing', u'number': None},
    {u'type': u'pddl_requirement', u'name': u'durative-actions', u'number': None},
    {u'type': u'pddl_requirement', u'name': u'numeric-fluents', u'number': None}
  ]
}

Add some tags to our problem:

>>> from webplanclient import Tags
>>> # Tags just helps us to build a list of dicts with the required attributes
>>> # you can also build that dict in another way if you prefer
>>> tags = Tags()
>>> tags.add_tag('user', 'hard problems')
[{'type': 'user', 'name': 'hard problems'}]
>>> # add tag to problem
>>> client.problem_add_tags(problem_hash, tags)
{u'equivalents': [], u'best_costs': None, u'hash': u'bc805cc705ecb4f60ecc156c9e77cb4f370b7908',
  u'tags': [
    {u'type': u'pddl_requirement', u'name': u'typing', u'number': None},
    {u'type': u'pddl_requirement', u'name': u'durative-actions', u'number': None},
    {u'type': u'pddl_requirement', u'name': u'numeric-fluents', u'number': None},
    {u'type': u'user', u'name': u'hard problems', u'number': None}
  ]
}

The problem is returned by problem_add_tags, as you can see our tag was added. Let’s now see how many problems tagged with our hard problems tag are known:

>>> len(client.get_problems(tags=tags))
1
>>> # this was not that surprising, as we just tagged one problem
>>> # after removing the tag from the problem, there should be none
>>> client.problem_remove_tags(problem_hash, tags)
# {...}
>>> len(client.get_problems(tags=tags))
0

Downloading Problem PDDL files

You can download the problem and domain pddl files like this:

>>> client.get_problem_pddl(problem_hash)
"(define (problem..."
>>> client.get_domain_pddl(problem_hash)
"(define (domain..."

There’s an example script download-problems.py shipped with the python client, that shows how this can be used to download all Problems with given tags.

Uploading Results

After having downloaded and solved some problems with your planner, you can submit your results back to webplan. Here, we’ll create an upload named myresults. We could also add results to an existing upload if we had one:

from webplanclient import ResultUpload
# create upload named 'myresults'
upload = ResultUpload.create(client, 'myresults')
# read plan from file
plan = util.read_file('plan.sol')
# hash of the problem we solved
hash = 'bc805c...'
upload.add_problem_result(plan, problem_hash=hash,
                                planner_name='myplanner')


# if you don't know the problem hash, you can pass problem
# and domain pddl files instead. The has will then be computed for you.
upload.add_problem_result(plan, domain_file='domain.pddl',
                                problem_file='problem.pddl',
                                planner_name='myplanner')

# we're done with uploading results, so compute the scores
upload.compute_scores()
# Now our scores are ready. We could now evaluate them using the
# gui.

# get scores
print upload.get_problem_results()
 [
   {u'costs': 3851224.0,
   u'created_at': u'2012-01-27T10:15:30.743671',
   u'id': 1714,
   u'planner_name': u'myplanner',
   u'problem_hash': u'bc805cc705ecb4f60ecc156c9e77cb4f370b7908',
   u'score': 0.8707,
   u'upload_id': 1},
   // ...
 ]

Don’t forget to call compute_scores, before accessing scores. After that you can also evaluate your results using the gui as described in Reports.