astropy/astropy — pull request #2992 by eteq (2014-09-29 07:54:13+00:00)
Title: Auto-generated ERFA wrappers

This isn't necessarily ready to be merged yet, but it's most of the way there, at least for what I think we want for 1.0.

This PR adapts the approach (and much of the code) from @jwoillez in liberfa/erfa-wrapping-experiments#6, which uses jinja2 to generate a Cython wrapper around ERFA. The resulting Cython file is pretty straightforward to use: typically it's just ``outarr = func(arr1,arr2)`` or similar, using numpy arrays where relevant.

There's a fair amount of discussion in liberfa/erfa-wrapping-experiments#6 about ways to improve this more, but in the name of moving forward with coordinates work for 1.0, I suggest we table those for now (or at least integrate this soon and allow the two efforts to move in parallel). So I think it's ok for us to use this but *not* consider it part of the public API yet (or with big warnings that say it's likely to change), and work towards a full wrapper for public consumption in future versions.

A few things that need to be dealt with before this is even mergeable:

- [ ] `erfa_time` needs to work. Right now it's just a re-naming scheme to map `erfa_time` names to the base `erfa` names, which seems to get about 2/3 of the tests to pass, but I don't really understand many of the failures... Perhaps @taldcroft or @mhvk can provide some guidance there? (Hopefully once travis runs you'll see the failures/errors come up there.)
- [ ] The current version of these wrappers is missing functionality like the `check_errors` that's in the current `erfa_time.pyx`. That could be implemented fairly easily in the template that generates the functions, *but* to clone the funcationality of the current `check_errors`, there needs to either be some clever parsing of the ERFA documentation strings, or some way to manually specify what the error codes mean.

And a few items from liberfa/erfa-wrapping-experiments#6 that I think could be *separate* issues to be addressed later:
* @jwoillez mentioned "I am not quite happy yet with the way matrices and vectors are handled". This might be problematic to tack on later as it alters the API, but hopefully find-and-replace will help a lot? Or, if anyone can figure out a way to do this quickly now, I'm happy to hear that too.
* The documentation should be amenable to parsing to convert it to our docstring format. Then we can get pretty sphinx docs that show the whole ERFA API.
* A documentation section on erfa. We may want to leave it out for now if we don't get the above bullet working, though.
* Mapping from the arcane ERFA/SOFA function names to something more readable would be nice. That could be done now by just setting aliases in ``astropy/erfa/__init__.py``, but it might be better to do something fancier.
* Right now I have ``erfa.pyx`` actually checked in as source code. In theory, we could instead have it be auto-generated as part of the build process, just like Cython does in generating ``.c`` file from ``.pyx`` files. Of course, that might lead to awkwardness given that we now need to go from ``erfa.pyx.templ`` -> ``erfa.pyx`` -> ``erfa.c`` in the build process... I'm not sure how hard that will be, but ERFA updates are uncommon enough that I think we could just say "run the `cython_generator.py` script when there's a new ERFA" and keep ``erfa.pyx`` constantly in source.

cc @astrofrog @mhvk @taldcroft @mdboom @embray @jwoillez