Fix #374 by adding close() to SpiceKernel

CHANGELOG.rst

@@ -10,6 +10,11 @@ Future
   from which Skyfield will download a file.
   `#382 <https://github.com/skyfielders/python-skyfield/issues/382>`_
 
+* Added :meth:`~skyfield.jpllib.SpiceKernel.close()` to support
+  applications that need to do fine-grained resource management or that
+  need to run tests that check for dangling open files.
+  `#374 <https://github.com/skyfielders/python-skyfield/issues/374>`_
+
 1.21 — 2020 May 29
 ------------------
 

skyfield/documentation/api.rst

@@ -142,10 +142,12 @@ Planetary Ephemerides
 By downloading a `SpiceKernel` file,
 Skyfield users can build vector functions
 predicting the positions of the Moon, Sun, and planets.
+See :doc:`planets`.
 
 .. autosummary::
 
    SpiceKernel
+   SpiceKernel.close
    SpiceKernel.comments
    SpiceKernel.names
    SpiceKernel.decode

skyfield/documentation/planets.rst

@@ -181,6 +181,39 @@ Each time you ask this ``earth`` object for its position at a given time,
 Skyfield will compute both of these underlying vectors
 and add them together to generate the position.
 
+Closing the file automatically
+==============================
+
+If you need to close files as you finish using them
+instead of waiting until the application exits,
+each Skyfield ephemeris offers a
+:meth:`~skyfield.jpllib.SpiceKernel.close()` method.
+It can either be called manually when you are done with an ephemeris,
+or you can use Python’s |closing|_ context manager
+to call the method automatically
+at the completion of a ``with`` statement:
+
+.. |closing| replace:: ``closing()``
+.. _closing: https://docs.python.org/3/library/contextlib.html#contextlib.closing
+
+.. testcode::
+
+    from contextlib import closing
+
+    ts = load.timescale(builtin=True)
+    t = ts.J2000
+
+    with closing(planets):
+        planets['venus'].at(t)  # Ephemeris can be used here
+
+    planets['venus'].at(t)  # But it’s closed outside the “with”
+
+.. testoutput::
+
+    Traceback (most recent call last):
+      ...
+    ValueError: seek of closed file
+
 .. testcleanup::
 
    __import__('skyfield.tests.fixes').tests.fixes.teardown()

skyfield/jpllib.py

@@ -87,6 +87,10 @@ def __str__(self):
             lines.append(_format_segment(s))
         return '\n'.join(lines)
 
+    def close(self):
+        """Close this ephemeris file."""
+        self.spk.close()
+
     def comments(self):
         """Return the comments string of this kernel.