Related issues:
* issue526 (consistent use of shared pointers for plugins)
* issue740 (configurable output file of translator)
* issue509 (introduces the task class, in particular issue700
            will get rid of a lot of global variables)
* issue1081 (moving error handling to constructors)
* issue1082 (not using options in component constructors)

I created issue1081 for moving the error handling into the constructors
and issue1082 for introducing the constructors with explicit arguments.

We started looking into a Python interface during the current sprint, so let me dig up this issue again.

Gabi prepared a prototype solution for a Python binding with pybind11 that supports running a search with a heuristic implemented in Python.
https://github.com/aibasel/downward/pull/152

We also discussed some points about object creation, in particular where the boundary between the option parser, the Python interface, and the library code should be. I'm copying some notes on the results of that discussion:

* Among other things, we discussed how to automate the manual steps in the pybind11 code that replicate information that is already present in the code (about variable names, types, default values, documentation). We said that such automation is not something we need to solve immediately; it's not a blocker in the sense that if we couldn't automate these things and needed to specify them multiple times, we would still want to do the C++/Python integration.

* But we also noticed that the introspection capabilities we already have for creating the wiki documentation should be adaptable with reasonable effort to do the bulk of the pybind11 binding code. Basically, in the same way that we can ask the planner to generate the wiki documentation, we could ask it to generate the pybind11 code.

* This also answers the question whether we want the "Python library mode" to be the only build mode or if we want to support others (e.g. C++ library or C++ executable). We need a C++ library or executable with this idea to generate the pybind11 code without having a bootstrapping problem.

* We want constructors without options objects in the builders and the library interface eventually. We discussed the option of having two constructors (one taking individual arguments, one taking an option object and delegating to the other) and the alternative solution of having only one constructor and unpacking the options object in the feature class. The current plan is to go with the second option and move towards the structure we have for some of the search engines where the feature and plugin code is in a file separate from the implementation.

* We also discussed how errors and warning were handled during the construction of builders: We want to move most/all of the error checking into the constructors, so we don't have to duplicate code for checking for objects created by the parser and objects created through the Python interface. This means we have to throw exceptions from the constructors and catch them in the parser, so we can report them with the parser context. Warnings during parsing do not fit well in this setup, but the two warnings we have so far are not that important and can be dropped.

I added the related issues to the summary (and added issue509) where it's easier
to keep track of them and possible to update the list.

Also, FYI: if you just write issueXYZ for an issue number XYZ, the tracker will
create links and tool tips for you.

Just for the (mostly my own) record, I'm listing here a few issues the closing of which will be good for this project. I'll keep updating this list:

* http://issues.fast-downward.org/issue526 (having shared_ptr used consistently in those objects that we want to expose to the Python module, such as the heuristic, would simplify memory ownership issues)
* http://issues.fast-downward.org/issue740 (not a big thing, but will make the Python module initialization code slightly cleaner)

Sure, could be helpful as a starting / comparison point.

We developed an interface from PSVN to Fast Downward as part of a project once.
In that interface, PSVN used Fast Downward as a library. It wasn't super
efficient because the changes to the task class were not ready then.

But if it helps I can dig up the source code and the documentation from the project.

(Moved from summary field)

We'd like to offer the user the possibility of interacting "programmatically" 
with the planer. This is a high-level issue / wishlist of features that could 
be 
related to this goal, and which could include, for instance,

(1) Offering a Python interface (i.e. creating one or more Python modules with 
well-designed interfaces that bind with the C++ library) for creating planning 
problems programmatically. 

(2) Offering a Python / C++ interface for easily specifying the options of the 
different plugins, in a way alleviating the need for complex command-line 
option 
parsing.  

(3) Offering the possibility of subclassing certain interfaces in order to 
specify (in a possibly domain-dependent manner) the desired search behaviour, 
or 
additional control information.

(4) Offering the possibility of using symbols whose denotation is defined 
through 
C++ / Python functions.

(5) ...


Good examples/inspiration for some/all of the above points could include for 
instance:
(A) The Gecode CSP solver (http://www.gecode.org/doc-latest/MPG.pdf), which 
beyond the ability to process problems specified in declarative languages such 
as 
flatzinc, offers different ways to declare CSP problems by extending the 
appropriate C++ classes, etc., as well as to control the solving process.

(B) The z3 SMT solver, which offers an elegant Python API to declare SMT 
problems, instantiate solvers with different options, and solve the problems 
(simple example: 
https://github.com/Z3Prover/z3/blob/master/examples/python/socrates.py)