From 1f126e9639f924e7802b072cf70d319053ce0693 Mon Sep 17 00:00:00 2001 From: Daniel Garcia Briseno Date: Mon, 22 Aug 2022 12:22:52 -0400 Subject: [PATCH 01/13] Add user guide --- docs/api.rst | 2 ++ docs/guide.rst | 88 +++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 89 insertions(+), 1 deletion(-) diff --git a/docs/api.rst b/docs/api.rst index 32ed4b4..3a6aa79 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,3 +1,5 @@ +.. _api-reference: + ************* API Reference ************* diff --git a/docs/guide.rst b/docs/guide.rst index 25d4288..7f60264 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -2,4 +2,90 @@ User Guide ********** -This user guide provides a walkthrough of the major features in the ``hvpy`` package. +Welcome to ``hvpy``! + +This guide provides a walkthrough of the major features in the ``hvpy`` package. +``hvpy`` is a python wrapper for the `Helioviewer API `_. +This is the same API that powers `helioviewer.org `_. + +Basic Usage +----------- +Each API endpoint has a function in ``hvpy`` that shares the same name and has +the same input parameters. So, for example if you are looking at +`getJP2Image `_ +in the Helioviewer documentation, you would execute this in ``hvpy`` with +the following command + +.. code-block:: Python + + import hvpy + from hvpy.datasources import DataSources + from datetime import datetime + + jp2 = hvpy.getJP2Image(datetime.now(), DataSources.AIA_94.value) + +Managing Return Types +--------------------- +``hvpy`` will attempt to coerce the result into a Python datatype +for you. In general, there are 3 types of results you can expect +from the API + +1. Raw Data +2. Strings +3. JSON + +In ``hvpy`` these return types map to + +1. bytearray +2. str +3. dict + +Sometimes the return type will change dependending on the input parameters +you specify, so make sure to review your input parameters carefully. +The descriptions in both our :ref:`api-reference` and the `API Docs `_ +will say whether certain parameters change the output type + +Helper Functions +---------------- +``hvpy`` provides a few helper functions for certain actions that generally +require multiple API reqeusts, or for actions that may require more work +than a simple API call. + +Helper Flows +^^^^^^^^^^^^ +For example, creating a movie requires +calling `hvpy.queueMovie` followed by `hvpy.getMovieStatus` to see +if the movie is done, and then calling `hvpy.downloadMovie` to get +the result. ``hvpy`` provides some helper functions to perform these flows +for you. (TODO: Update ref) + +Datasource & Event Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Some API requests accept a list of datasources and events. These +are in a very specific format. For example layering an AIA_94 image +over an AIA_304 image would look like "[13,1,50],[8,1,50]". Since +our API provides a one to one mapping, you would have to go figure out +how helioviewer likes its layer strings, and find the IDs for +each source. + +``hvpy`` makes this easy by providing a function for you. hvpy.util.create_layers (TODO: update ref) will +create the datasources for you, you simply specify a tuple with the source enum you +want, and the opacity it should be in the image. + +.. code-block:: Python + + from hvpy.util import create_layers + from hvpy.datasources import DataSources + layer_string = create_layers([(DataSources.AIA_304, 50), (DataSources.AIA_94, 50)] + # layer_string = [13,1,50],[8,1,50] + +There is a similar function for choosing events that you want to have displayed +in hvpy.util.create_events (TODO: Update ref) + +Miscellaneous Helpers +^^^^^^^^^^^^^^^^^^^^^ +``hvpy`` also provides some miscellaneous helper functions. +For example, since many API endpoints return raw data like images or videos, +we've implemented a simple save_file (TODO: Update ref) to save +this binary data to disk. + From 12c9d30825670c3825164e19fe6a56c79471bc2e Mon Sep 17 00:00:00 2001 From: Daniel Garcia Briseno Date: Mon, 22 Aug 2022 12:30:43 -0400 Subject: [PATCH 02/13] Update file ending for precommit --- docs/guide.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/guide.rst b/docs/guide.rst index 7f60264..b07f563 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -88,4 +88,3 @@ Miscellaneous Helpers For example, since many API endpoints return raw data like images or videos, we've implemented a simple save_file (TODO: Update ref) to save this binary data to disk. - From 5d0a0dbd337bce879a58930f757f46ba94030aec Mon Sep 17 00:00:00 2001 From: Daniel Garcia Briseno Date: Mon, 22 Aug 2022 12:41:04 -0400 Subject: [PATCH 03/13] One sentence per line --- docs/guide.rst | 59 ++++++++++++++++++++------------------------------ 1 file changed, 23 insertions(+), 36 deletions(-) diff --git a/docs/guide.rst b/docs/guide.rst index b07f563..364d30f 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -10,12 +10,8 @@ This is the same API that powers `helioviewer.org `_. Basic Usage ----------- -Each API endpoint has a function in ``hvpy`` that shares the same name and has -the same input parameters. So, for example if you are looking at -`getJP2Image `_ -in the Helioviewer documentation, you would execute this in ``hvpy`` with -the following command - +Each API endpoint has a function in ``hvpy`` that shares the same name and has the same input parameters. +For example if you are looking at `getJP2Image `_ in the Helioviewer documentation, you would execute this in ``hvpy`` with the following command: .. code-block:: Python import hvpy @@ -26,51 +22,45 @@ the following command Managing Return Types --------------------- -``hvpy`` will attempt to coerce the result into a Python datatype -for you. In general, there are 3 types of results you can expect -from the API +``hvpy`` will attempt to coerce the result into a Python datatype for you. +In general, there are 3 types of results you can expect from the API: 1. Raw Data 2. Strings 3. JSON -In ``hvpy`` these return types map to +In ``hvpy`` these return types map to: 1. bytearray 2. str 3. dict -Sometimes the return type will change dependending on the input parameters -you specify, so make sure to review your input parameters carefully. -The descriptions in both our :ref:`api-reference` and the `API Docs `_ -will say whether certain parameters change the output type +Sometimes the return type will change dependending on the input parameters you specify. +Make sure to review your input parameters carefully. +The descriptions in both our :ref:`api-reference` and the `API Docs `_ will say whether certain parameters change the output type. Helper Functions ---------------- -``hvpy`` provides a few helper functions for certain actions that generally -require multiple API reqeusts, or for actions that may require more work -than a simple API call. +``hvpy`` provides a few helper functions for certain actions that generally require multiple API reqeusts. +There are also helper functions for actions that may require more work than a simple API call. Helper Flows ^^^^^^^^^^^^ -For example, creating a movie requires -calling `hvpy.queueMovie` followed by `hvpy.getMovieStatus` to see -if the movie is done, and then calling `hvpy.downloadMovie` to get -the result. ``hvpy`` provides some helper functions to perform these flows -for you. (TODO: Update ref) +For example, creating a movie requires calling `hvpy.queueMovie` followed by `hvpy.getMovieStatus` to see if the movie is done. +Then you would call `hvpy.downloadMovie` to get the result. +``hvpy`` provides some helper functions to perform these flows for you. Datasource & Event Selection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Some API requests accept a list of datasources and events. These -are in a very specific format. For example layering an AIA_94 image -over an AIA_304 image would look like "[13,1,50],[8,1,50]". Since -our API provides a one to one mapping, you would have to go figure out -how helioviewer likes its layer strings, and find the IDs for -each source. +Some API requests accept a list of datasources and events. +These are in a very specific format. +For example layering an AIA_94 and an AIA_304 image might look like "[13,1,50],[8,1,50]". +Since ``hvpy`` provides a one to one mapping, you would have to understand and create this string yourself. +To do this, you would have to go figure out how helioviewer likes its layer strings, and find the IDs for each source. -``hvpy`` makes this easy by providing a function for you. hvpy.util.create_layers (TODO: update ref) will -create the datasources for you, you simply specify a tuple with the source enum you -want, and the opacity it should be in the image. +``hvpy`` makes this easy by providing a function for you. +hvpy.util.create_layers (TODO: update ref) will create this string for you. +You simply specify a tuple with the source enum you want, and the opacity it should have the end result. .. code-block:: Python @@ -79,12 +69,9 @@ want, and the opacity it should be in the image. layer_string = create_layers([(DataSources.AIA_304, 50), (DataSources.AIA_94, 50)] # layer_string = [13,1,50],[8,1,50] -There is a similar function for choosing events that you want to have displayed -in hvpy.util.create_events (TODO: Update ref) +There is a similar function for choosing events that you want to have displayed in hvpy.util.create_events (TODO: Update ref) Miscellaneous Helpers ^^^^^^^^^^^^^^^^^^^^^ ``hvpy`` also provides some miscellaneous helper functions. -For example, since many API endpoints return raw data like images or videos, -we've implemented a simple save_file (TODO: Update ref) to save -this binary data to disk. +For example, since many API endpoints return raw data like images or videos, we've implemented a simple save_file (TODO: Update ref) to save this binary data to disk. From 40118e2dc815cc57faa2a0d9a670158910ce8e1f Mon Sep 17 00:00:00 2001 From: Daniel Garcia Briseno Date: Wed, 24 Aug 2022 09:31:19 -0400 Subject: [PATCH 04/13] Update links to double underscores datasources -> datasource AIA_* -> SDO/AIA * Added ref to hvpy.utils.create_layers update code block example to print layer_string util -> utils --- docs/guide.rst | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/guide.rst b/docs/guide.rst index 364d30f..24e97ab 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -5,20 +5,20 @@ User Guide Welcome to ``hvpy``! This guide provides a walkthrough of the major features in the ``hvpy`` package. -``hvpy`` is a python wrapper for the `Helioviewer API `_. -This is the same API that powers `helioviewer.org `_. +``hvpy`` is a python wrapper for the `Helioviewer API `__. +This is the same API that powers `helioviewer.org `__. Basic Usage ----------- Each API endpoint has a function in ``hvpy`` that shares the same name and has the same input parameters. -For example if you are looking at `getJP2Image `_ in the Helioviewer documentation, you would execute this in ``hvpy`` with the following command: +For example if you are looking at `getJP2Image `__ in the Helioviewer documentation, you would execute this in ``hvpy`` with the following command: .. code-block:: Python import hvpy - from hvpy.datasources import DataSources + from hvpy.datasource import DataSource from datetime import datetime - jp2 = hvpy.getJP2Image(datetime.now(), DataSources.AIA_94.value) + jp2 = hvpy.getJP2Image(datetime.now(), DataSource.AIA_94.value) Managing Return Types --------------------- @@ -37,7 +37,7 @@ In ``hvpy`` these return types map to: Sometimes the return type will change dependending on the input parameters you specify. Make sure to review your input parameters carefully. -The descriptions in both our :ref:`api-reference` and the `API Docs `_ will say whether certain parameters change the output type. +The descriptions in both our :ref:`api-reference` and the `API Docs `__ will say whether certain parameters change the output type. Helper Functions ---------------- @@ -54,22 +54,24 @@ Datasource & Event Selection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Some API requests accept a list of datasources and events. These are in a very specific format. -For example layering an AIA_94 and an AIA_304 image might look like "[13,1,50],[8,1,50]". +For example layering an SDO/AIA 94 and an SDO/AIA 304 image might look like "[13,1,50],[8,1,50]". Since ``hvpy`` provides a one to one mapping, you would have to understand and create this string yourself. To do this, you would have to go figure out how helioviewer likes its layer strings, and find the IDs for each source. ``hvpy`` makes this easy by providing a function for you. -hvpy.util.create_layers (TODO: update ref) will create this string for you. +`hvpy.utils.create_layers` will create this string for you. You simply specify a tuple with the source enum you want, and the opacity it should have the end result. .. code-block:: Python - from hvpy.util import create_layers - from hvpy.datasources import DataSources - layer_string = create_layers([(DataSources.AIA_304, 50), (DataSources.AIA_94, 50)] - # layer_string = [13,1,50],[8,1,50] + from hvpy.utils import create_layers + from hvpy.datasource import DataSource + layer_string = create_layers([(DataSource.AIA_304, 50), (DataSource.AIA_94, 50)] + print(layer_string) -There is a similar function for choosing events that you want to have displayed in hvpy.util.create_events (TODO: Update ref) + "[13,1,50],[8,1,50]" + +There is a similar function for choosing events that you want to have displayed in hvpy.utils.create_events (TODO: Update ref) Miscellaneous Helpers ^^^^^^^^^^^^^^^^^^^^^ From 00c89195bdb5a5413e198eccbff9c19aa9511bf4 Mon Sep 17 00:00:00 2001 From: Daniel Garcia Briseno Date: Wed, 24 Aug 2022 09:34:41 -0400 Subject: [PATCH 05/13] Removed welcome message on user guide --- docs/guide.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/guide.rst b/docs/guide.rst index 24e97ab..9688d53 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -2,8 +2,6 @@ User Guide ********** -Welcome to ``hvpy``! - This guide provides a walkthrough of the major features in the ``hvpy`` package. ``hvpy`` is a python wrapper for the `Helioviewer API `__. This is the same API that powers `helioviewer.org `__. From 02628d360d646a950c7bcb5c44dc8d0a01ca6eb3 Mon Sep 17 00:00:00 2001 From: Daniel Garcia Briseno Date: Wed, 24 Aug 2022 09:36:28 -0400 Subject: [PATCH 06/13] Add refs to python docs for types --- docs/guide.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guide.rst b/docs/guide.rst index 9688d53..e49d9e6 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -29,9 +29,9 @@ In general, there are 3 types of results you can expect from the API: In ``hvpy`` these return types map to: -1. bytearray -2. str -3. dict +1. `bytearray` +2. `str` +3. `dict` Sometimes the return type will change dependending on the input parameters you specify. Make sure to review your input parameters carefully. From 943aba9e42bad0eb42c4a4e4770bb6c48b896720 Mon Sep 17 00:00:00 2001 From: Daniel Garcia Briseno Date: Wed, 24 Aug 2022 09:45:13 -0400 Subject: [PATCH 07/13] Need line break before code-block --- docs/guide.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/guide.rst b/docs/guide.rst index e49d9e6..0636dc3 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -10,6 +10,7 @@ Basic Usage ----------- Each API endpoint has a function in ``hvpy`` that shares the same name and has the same input parameters. For example if you are looking at `getJP2Image `__ in the Helioviewer documentation, you would execute this in ``hvpy`` with the following command: + .. code-block:: Python import hvpy From 26b0b4187ccc1b727d48eed31b111e0735e1046f Mon Sep 17 00:00:00 2001 From: Daniel Garcia Briseno Date: Wed, 24 Aug 2022 09:45:47 -0400 Subject: [PATCH 08/13] Update sentence in how the api relates to helioviewer --- docs/guide.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/guide.rst b/docs/guide.rst index 0636dc3..bed7ced 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -3,8 +3,7 @@ User Guide ********** This guide provides a walkthrough of the major features in the ``hvpy`` package. -``hvpy`` is a python wrapper for the `Helioviewer API `__. -This is the same API that powers `helioviewer.org `__. +``hvpy`` is a python wrapper for the `Helioviewer API `__, which is the same API that powers `helioviewer.org `__. Basic Usage ----------- From f4b2817247ef19166cb4e56b2884a057c321a024 Mon Sep 17 00:00:00 2001 From: Daniel Garcia Briseno <94071409+dgarciabriseno@users.noreply.github.com> Date: Wed, 24 Aug 2022 09:56:01 -0400 Subject: [PATCH 09/13] Update docs/guide.rst Co-authored-by: Nabil Freij --- docs/guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide.rst b/docs/guide.rst index bed7ced..56c474a 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -64,9 +64,9 @@ You simply specify a tuple with the source enum you want, and the opacity it sho from hvpy.utils import create_layers from hvpy.datasource import DataSource + layer_string = create_layers([(DataSource.AIA_304, 50), (DataSource.AIA_94, 50)] print(layer_string) - "[13,1,50],[8,1,50]" There is a similar function for choosing events that you want to have displayed in hvpy.utils.create_events (TODO: Update ref) From 21881c2e9fd47c8f4f7d8ba2bdf50ea242d7b2de Mon Sep 17 00:00:00 2001 From: Daniel Garcia Briseno Date: Wed, 24 Aug 2022 09:56:36 -0400 Subject: [PATCH 10/13] Add missing closing parenthesis in the example --- docs/guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide.rst b/docs/guide.rst index 56c474a..507fc59 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -65,7 +65,7 @@ You simply specify a tuple with the source enum you want, and the opacity it sho from hvpy.utils import create_layers from hvpy.datasource import DataSource - layer_string = create_layers([(DataSource.AIA_304, 50), (DataSource.AIA_94, 50)] + layer_string = create_layers([(DataSource.AIA_304, 50), (DataSource.AIA_94, 50)]) print(layer_string) "[13,1,50],[8,1,50]" From 81d7901add208b08f937b37260538927a37d56fc Mon Sep 17 00:00:00 2001 From: Daniel Garcia Briseno Date: Wed, 7 Sep 2022 10:44:22 -0400 Subject: [PATCH 11/13] Update guide for latest references --- docs/guide.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/guide.rst b/docs/guide.rst index 507fc59..3e89938 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -62,16 +62,16 @@ You simply specify a tuple with the source enum you want, and the opacity it sho .. code-block:: Python - from hvpy.utils import create_layers - from hvpy.datasource import DataSource + >> from hvpy.utils import create_layers + >> from hvpy.datasource import DataSource - layer_string = create_layers([(DataSource.AIA_304, 50), (DataSource.AIA_94, 50)]) - print(layer_string) + >> layer_string = create_layers([(DataSource.AIA_304, 50), (DataSource.AIA_94, 50)]) + >> print(layer_string) "[13,1,50],[8,1,50]" -There is a similar function for choosing events that you want to have displayed in hvpy.utils.create_events (TODO: Update ref) +There is a similar function for choosing events that you want to have displayed in `hvpy.utils.create_events` Miscellaneous Helpers ^^^^^^^^^^^^^^^^^^^^^ ``hvpy`` also provides some miscellaneous helper functions. -For example, since many API endpoints return raw data like images or videos, we've implemented a simple save_file (TODO: Update ref) to save this binary data to disk. +For example, since many API endpoints return raw data like images or videos, we've implemented a simple `hvpy.utils.save_file` to save this binary data to disk. From 8bf9ce1a3a983f92288ae6ccd23a750d89c751e1 Mon Sep 17 00:00:00 2001 From: Nabil Freij Date: Thu, 8 Sep 2022 16:07:31 +0100 Subject: [PATCH 12/13] Apply suggestions from code review --- docs/guide.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guide.rst b/docs/guide.rst index 3e89938..47bad6b 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -62,11 +62,11 @@ You simply specify a tuple with the source enum you want, and the opacity it sho .. code-block:: Python - >> from hvpy.utils import create_layers - >> from hvpy.datasource import DataSource + >>> from hvpy.utils import create_layers + >>> from hvpy.datasource import DataSource - >> layer_string = create_layers([(DataSource.AIA_304, 50), (DataSource.AIA_94, 50)]) - >> print(layer_string) + >>> layer_string = create_layers([(DataSource.AIA_304, 50), (DataSource.AIA_94, 50)]) + >>> print(layer_string) "[13,1,50],[8,1,50]" There is a similar function for choosing events that you want to have displayed in `hvpy.utils.create_events` From 4828cfd42844922e06cc086de9377bb928acedd1 Mon Sep 17 00:00:00 2001 From: Nabil Freij Date: Thu, 8 Sep 2022 16:10:08 +0100 Subject: [PATCH 13/13] Update docs/guide.rst --- docs/guide.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guide.rst b/docs/guide.rst index 47bad6b..82b9577 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -62,11 +62,11 @@ You simply specify a tuple with the source enum you want, and the opacity it sho .. code-block:: Python - >>> from hvpy.utils import create_layers - >>> from hvpy.datasource import DataSource + from hvpy.utils import create_layers + from hvpy.datasource import DataSource - >>> layer_string = create_layers([(DataSource.AIA_304, 50), (DataSource.AIA_94, 50)]) - >>> print(layer_string) + layer_string = create_layers([(DataSource.AIA_304, 50), (DataSource.AIA_94, 50)]) + print(layer_string) "[13,1,50],[8,1,50]" There is a similar function for choosing events that you want to have displayed in `hvpy.utils.create_events`