Discourage and eventually deprecate "low-level" API

[kbarbary]

In the long term, I think it will become a nightmare having the dual interface that currently exists in this package. Instead, we should ensure that the high-level interface has all the functionality and performance possible in the low-level interface and eventually deprecate the low-level interface for public use. (I've been putting off having this discussion because it might be contentious, but it will be better to resolve sooner rather than later!)

Obviously there are still gaps in the high-level interface, the most glaring of which is support for tables. I'm currently working on a PR to support tables in the high-level interface (at least at the level available in the low-level interface). The other thing I can think of off the top of my head is a way to get "raw" header values as strings.

What else is missing from the high-level interface, in terms of either functionality or performance? If you're currently using the low-level API, could you switch?

[emmt]

I agree and I have avoided mixing low and high level interface. The current OIFITS has been fixed to cope with that.

[ziotom78]

As a matter of fact, I never used FITSIO.jl's high-level interface as I work with tables 99% of time. I usually prefer working with high-level interfaces, but the case of CFITSIO is somewhat difference in my opinion. The advantage of the low-level interface is its being a 1-to-1 mapping to the C/Fortran functions provided by CFITSIO, which are widely used and well known. It is extremely easy for me to port some FITS-based code from/to Julia if this mapping still exists.

To provide a concrete example, I find pyfits annoying to use, because of the very abstractions it provides. The few times I have used it, I have always had to dig into the documentation to know how to do things. Had it provided a low-level interface, I would have probably knew by hearth which function to use and what parameter it expected.

[kbarbary]

@ziotom78 I agree about pyfits/astropy.io.fits being "too-abstracted". In the FITSIO.jl high-level interface, I've been mimicing the fitsio python package, which I think is less abstracted and makes it easier to understand what is happening. For example, I'm interested in keeping it very clear when read/write operations actually happen, which is something I find difficult to understand in astropy.io.fits.

(As an aside that is related to this, I'm thinking about deprecating the use of hdu[i:j] as a way to read image subsections, and replacing it with read(hdu, i:j), again to make clear that there is a read operation happening. The current behavior is a bit too cute.)

I hope we can make the high-level API easy enough to understand so that the mapping from cfitsio is easy, but maybe not. Another possibily is that we could mimic what base Julia does for direct wrappers like BLAS, Libc and Libdl, which is to put the direct wrapper functions in a submodule, called something like Libcfitsio. We could still export the submodule, so that you would call, e.g.,

using FITSIO
Libcfitsio.open_file(...)

Just some ideas. Any such changes would be a ways off and we'll carefully consider them.

[ziotom78]

@kbarbary, I like very much your idea of putting the wrapper functions into a sub-module!

[kbarbary]

Closed by #30