Merge pull request #2384 from bsipocz/utils_cleanup_docs_downloads

Utils to cleanup docs downloads

Author: bsipocz

CHANGES.rst

@@ -24,9 +24,12 @@ jplsbdb
 - Fix a bug for jplsdbd query when the returned physical quantity contains
   a unit with exponential. [#2377]
 
+
 Infrastructure, Utility and Other Changes and Additions
 -------------------------------------------------------
 
+- New function, ``utils.cleanup_downloads.cleanup_saved_downloads``, is
+  added to help the testcleanup narrative in narrative documentations. [#2384]
 
 
 0.4.6 (2022-03-22)

astroquery/utils/__init__.py

@@ -11,3 +11,4 @@
 from .commons import *
 from .process_asyncs import async_to_sync
 from .docstr_chompers import prepend_docstr_nosections
+from .cleanup_downloads import cleanup_saved_downloads

astroquery/utils/cleanup_downloads.py

@@ -0,0 +1,30 @@
+# Licensed under a 3-clause BSD style license - see LICENSE.rst
+"""
+Utility to cleanup files created during doctesting.
+"""
+import glob
+import os
+import shutil
+
+__all__ = ['cleanup_saved_downloads']
+
+
+def cleanup_saved_downloads(names):
+    """ Function to clean up save files.
+
+    Parameters
+    ----------
+    names : str or list of str
+        Files or directories to clean up. Wildcards are accepted.
+    """
+
+    if isinstance(names, str):
+        names = [names]
+
+    for path in names:
+        files = glob.glob(path)
+        for saved_download in files:
+            try:
+                shutil.rmtree(saved_download)
+            except NotADirectoryError:
+                os.remove(saved_download)

docs/cadc/cadc.rst

@@ -490,14 +490,6 @@ More details about temporary table upload can be found in the IVOA TAP specifica
     tess2021167190903-s0039-1-3-0210-s science
                              tu1657207 science
 
-
-.. testcleanup::
-
-    >>> import os
-    >>> if os.path.isfile('my_observations.xml'):
-    ...    os.remove('my_observations.xml')
-
-
 The feature allows a user to save the results of a query to use them later or
 correlate them with data in other TAP services.
 
@@ -665,3 +657,9 @@ Reference/API
 
 .. automodapi:: astroquery.cadc
     :no-inheritance-diagram:
+
+
+.. testcleanup::
+
+    >>> from astroquery.utils import cleanup_saved_downloads
+    >>> cleanup_saved_downloads(['my_observations.xml', 'test_output_noauth.xml'])

docs/esa/hsa/hsa.rst

@@ -203,7 +203,9 @@ First retrieve the observation IDs based on a position on the sky. To achive thi
 
   >>> from astroquery.esa.hsa import HSA
   >>>
-  >>> HSA.query_hsa_tap("select top 10 observation_id from hsa.v_active_observation where contains(point('ICRS', hsa.v_active_observation.ra, hsa.v_active_observation.dec),circle('ICRS', 100.2417,9.895, 1.1))=1", output_format='csv', output_file='results.cvs')
+  >>> HSA.query_hsa_tap("select top 10 observation_id from hsa.v_active_observation where "
+  ...                   "contains(point('ICRS', hsa.v_active_observation.ra, hsa.v_active_observation.dec), "
+  ...                   "circle('ICRS', 100.2417,9.895, 1.1))=1", output_format='csv', output_file='results.csv')
   <Table length=9>
   observation_id
       int64
@@ -238,3 +240,9 @@ Reference/API
 
 .. automodapi:: astroquery.esa.hsa
     :no-inheritance-diagram:
+
+
+.. testcleanup::
+
+    >>> from astroquery.utils import cleanup_saved_downloads
+    >>> cleanup_saved_downloads(['1342195355*', 'results.csv'])

docs/ipac/irsa/sha/sha.rst

@@ -100,3 +100,8 @@ Reference/API
     :no-inheritance-diagram:
 
 .. _API: http://sha.ipac.caltech.edu/applications/Spitzer/SHA/help/doc/api.html
+
+.. testcleanup::
+
+    >>> from astroquery.utils import cleanup_saved_downloads
+    >>> cleanup_saved_downloads(['sha_tmp'])

docs/mast/mast.rst

@@ -304,7 +304,7 @@ with a `~astropy.table.Table` of data products, or a list (or single) obsid as t
 
    >>> from astroquery.mast import Observations
    ...
-   >>> single_obs = Observations.query_criteria(obs_collection="IUE",obs_id="lwp13058")
+   >>> single_obs = Observations.query_criteria(obs_collection="IUE", obs_id="lwp13058")
    >>> data_products = Observations.get_product_list(single_obs)
    ...
    >>> manifest = Observations.download_products(data_products, productType="SCIENCE")
@@ -1259,3 +1259,10 @@ Reference/API
 .. automodapi:: astroquery.mast
     :no-inheritance-diagram:
     :inherited-members:
+
+
+.. testcleanup::
+
+    >>> from astroquery.utils import cleanup_saved_downloads
+    >>> cleanup_saved_downloads(['mastDownload*', 'tess-*', 'lwp13058*', '3dhst*'])
+

docs/testing.rst

@@ -101,3 +101,13 @@ This file only needs the ``get_package_data()`` function, which will tell
         paths_test = [os.path.join('data', '*.xml')]
 
         return {'astroquery.module.tests': paths_test}
+
+
+Doctesting
+----------
+
+Narrative documentation should also be tested, the ``doctest-remote-data`` directive provides a way
+to mark code snippets that relies on remote data access.
+
+If any of the examples include saving data files locally, use the ``testcleanup`` directive and the
+`~astroquery.utils.cleanup_saved_downloads` function at the end of the narrative documentation.

setup.cfg

@@ -41,6 +41,7 @@ filterwarnings =
     ignore::pytest.PytestUnraisableExceptionWarning
     ignore::numpy.VisibleDeprecationWarning
     ignore: unclosed file:ResourceWarning
+    ignore:unclosed <ssl.SSLSocket:ResourceWarning
     ignore::UserWarning
     ignore::astroquery.exceptions.InputWarning
     ignore::astropy.utils.exceptions.AstropyDeprecationWarning