From 3e93e006b2bbf2a38c6aed7acc355689ee3dec42 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Tue, 18 Feb 2025 15:49:11 +0000 Subject: [PATCH] Move warnings discussion to its own file and rephrase duplicate ASDF warning --- docs/howto_guides/asdf_warnings.rst | 29 ++++++++++++++ docs/howto_guides/index.rst | 1 + docs/howto_guides/replacing_asdfs.rst | 54 ++++++++------------------- 3 files changed, 46 insertions(+), 38 deletions(-) create mode 100644 docs/howto_guides/asdf_warnings.rst diff --git a/docs/howto_guides/asdf_warnings.rst b/docs/howto_guides/asdf_warnings.rst new file mode 100644 index 00000000..899f409a --- /dev/null +++ b/docs/howto_guides/asdf_warnings.rst @@ -0,0 +1,29 @@ +.. _dkist:howto-guide:asdf-warnings + +Understanding version warnings when loading ASDFs +================================================= + +When you load a recently-downloaded ASDF file you may see a warning something like this: + +:: + + AsdfPackageVersionWarning: File '' was created with extension URI 'asdf://asdf-format.org/astronomy/gwcs/extensions/gwcs-1.2.0' (from package gwcs==0.24.0), but older package (gwcs==0.22.0) is installed. + + +Of course the extension and package it complains about will vary. +This warning means that an extension needed to properly parse the ASDF file is missing or outdated. +To correct this, you should update your Python tools installation with + +.. code-block:: bash + + pip install --upgrade dkist + + +if you installed using `pip` or + +.. code-block:: bash + + conda update dkist + + +if you used `conda`. diff --git a/docs/howto_guides/index.rst b/docs/howto_guides/index.rst index b2e2aa11..1d6ace5f 100644 --- a/docs/howto_guides/index.rst +++ b/docs/howto_guides/index.rst @@ -12,3 +12,4 @@ If you're starting fresh you might want to check out the :ref:`dkist:tutorial:in sample_data replacing_asdfs + asdf_warnings diff --git a/docs/howto_guides/replacing_asdfs.rst b/docs/howto_guides/replacing_asdfs.rst index 79c8ebe1..89231123 100644 --- a/docs/howto_guides/replacing_asdfs.rst +++ b/docs/howto_guides/replacing_asdfs.rst @@ -1,7 +1,7 @@ .. _dkist:howto-guide:replacing-asdfs: -Replacing Previously Downloaded ASDF Files -========================================== +Re-downloading ASDF files +========================= The DKIST Data Center will occasionally update the ASDF files for all the datasets it stores, due to changes or corrections to the metadata. This can lead to two possible problems. @@ -9,12 +9,20 @@ First, when you download ASDF metadata files from the Data Center those files mi Second, ASDF files you have downloaded previously might become outdated and need to be re-downloaded. -Re-downloading ASDF files -------------------------- - You should periodically re-download your local ASDF files to keep up to date with changes to the dataset metadata. To do so, you can use the `overwrite` keyword argument when downloading an ASDF file. -For example, to force a refresh of your local copy of the sample data: + +For example: + +.. code-block:: python + + Fido.fetch(res, path="~/sunpy/data/{instrument}/{dataset_id}", overwrite=True) # doctest: +SKIP + + +where `res` is the result of a `Fido` search for some dataset you already have saved locally. + +You might also need to force a refresh of the sample data which is included with the Python tools. +Again, we can use the `overwrite` keyword for this. .. code-block:: python @@ -23,10 +31,8 @@ For example, to force a refresh of your local copy of the sample data: download_all_sample_data(overwrite=True) # doctest: +REMOTE_DATA -`Fido.fetch` also takes the `overwrite` argument. - -Occasionally, the naming convention for the ASDF files might also change, meaning that the usual checks to stop you downloading a dataset you already have locally will fail and you will end up with two (likely identical) metadata files. -In this case, if the metadata file has been renamed then you may see a warning like this when you load the dataset: +Occasionally, the naming convention for the ASDF files has also changed, meaning that the usual checks to stop you downloading a dataset you already have locally may fail and you will end up with two (likely identical) metadata files. +If you re-download a dataset that you already had locally before the rename, you may see a warning like this when you load the dataset: .. code-block:: python @@ -42,31 +48,3 @@ However, to remove the warning the old file can simply be deleted or moved elsew Note that this behaviour is new in dkist v1.10.0. In older versions the loader will return a list containing the corresponding dataset for each ASDF file present, which is likely to cause problems. Deleting the old file will still solve the issue, although you should also update your Python tools installation to v1.10.1 or later if possible. - -Understanding version warnings when loading ASDFs -------------------------------------------------- - -When you load a recently-downloaded ASDF file you may see a warning something like this: - -:: - - AsdfPackageVersionWarning: File '' was created with extension URI 'asdf://asdf-format.org/astronomy/gwcs/extensions/gwcs-1.2.0' (from package gwcs==0.24.0), but older package (gwcs==0.22.0) is installed. - - -Of course the extension and package it complains about will vary. -This warning means that an extension needed to properly parse the ASDF file is missing or outdated. -To correct this, you should update your Python tools installation with - -.. code-block:: bash - - pip install --upgrade dkist - - -if you installed using `pip` or - -.. code-block:: bash - - conda update dkist - - -if you used `conda`.