Bringing the whole file in at once was offering the error
OSError: [Errno 12] Cannot allocate memory
in experiments I was doing with Skyfield with Jovian moons, because of
the large size of jup310.bsp plus some other data that I was using. So
with this change, jplephem uses mmap() separately for each segment the
user needs, making it possible to map only one — or a few — segments of
a file at a time, discarding older ones as newer ones are needed and
limiting the amount of simultaneously mapped memory required.
This is kind of magic. Because it is now a generator, you have the
option of asking for position, then only proceeding to the velocity if
you need it, without having to repeat the work of getting to that point
again.
The great wonder of writing documentation once again asserts itself!
Only while writing up the documentation — frighteningly enough, the last
step before release — did I realize that the API was dangerously
misleading because it let you just ask the position of a target, without
any context as to where the measurement was from.
So the quick go-to indexing that the SPK object supports — which I now
like so very much that I have promoted it to the __getitem__ of the
kernel object — now makes the user name both the center and the target
that they want a vector between.
Because, what if they have an open file instead? The previous design
made it impossible to ever just keep their file open and have the SPK
class use it.
Now that the main point of this package is the "jplephem" module for
reading SPK kernels, we should go ahead and promote it to being a top
level directory.
Because bare directories with *.py files inside are now considered
packages to Python 3, these directories were being grabbed by the
"import" statement during certain tests, instead of letting Python find
the actual installed ephemerides packages. Bumping them down a level
solves the problem, and also unclutters the top level.