Merge branch 'development' into atl14-data-download

doc/source/contributing/icepyx_internals.rst

@@ -0,0 +1,70 @@
+icepyx Internals
+================
+
+Authentication
+--------------
+Authentication in icepyx is handled using a Mixin class. A Mixin class is a class
+which defines functionality that may be desired by multiple other classes within 
+a library. For example, at this time both the Query and Variables classes need
+to be able to authenticate. Instead of defining the same properties and
+functionality twice, icepyx has an EarthdataAuthMixin class that is inherited
+by both modules.
+
+**Property Access**
+
+Even though they aren't explicity defined in the init method, properties
+like ``.session`` are accessible on a Query object because they are inherited. The
+code that indicates this to Python is ``EarthdataAuthMixin.__init__(self)``.
+
+For example:
+
+.. code-block:: python
+
+ import icepyx as ipx
+
+ region_a = ipx.Query('ATL06',[-45, 74, -44,75],['2019-11-30','2019-11-30'], \
+ start_time='00:00:00', end_time='23:59:59')
+
+ # authentication can be accessed via the Query object
+ region_a.session
+ region_a.s3login_credentials
+
+
+**Adding authentication to a new class**
+
+To add authentication to an additional icepyx class, one needs to add the Mixin
+to the class. To do this:
+
+1. Add the EarthdataAuthMixin class to the ``class`` constructor (and import the mixin)
+2. Add the EarthdataAuthMixin init method within the init method of the new class ``EarthdataAuthMixin.__init__(self)``
+3. Access the properties using the **public** properties (Ex. ``self.session``, not ``self._session``.)
+
+A minimal example of the new class (saved in ``icepyx/core/newclass.py``) would be:
+
+.. code-block:: python
+
+ from icepyx.core.auth import EarthdataAuthMixin
+
+ class MyNewClass(EarthdataAuthMixin):
+ def __init__(self):
+ self.mynewclassproperty = True
+
+ EarthdataAuthMixin.__init__(self)
+
+ def my_exciting_new_method(self):
+ # This method requires login
+ s = self.session
+ print(s)
+ return 'We authenticated inside the method!'
+
+
+The class would then be accessible with:
+
+.. code-block:: python
+
+ from icepyx.core.newclass import MyNewClass
+
+ n = MyNewClass()
+
+ n.session
+ n.my_exciting_new_method()

doc/source/example_notebooks/IS2_DEM_comparison_WIP.ipynb

@@ -148,17 +148,6 @@
  "### Log in to Earthdata"
  ]
  },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "earthdata_uid = 'Jessica.scheick'\n",
- "email = 'jessica.scheick@maine.edu'\n",
- "region_a.earthdata_login(earthdata_uid, email)"
- ]
- },
  {
  "cell_type": "code",
  "execution_count": null,
@@ -180,6 +169,19 @@
  "region_a.granules.avail"
  ]
  },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "user_expressions": []
+ },
+ "source": [
+ "```{admonition} Important Authentication Update\n",
+ "Previously, icepyx required you to explicitly use the `.earthdata_login()` function to login. Running this function is no longer required, as icepyx will call the login function as needed. The user will still need to provide their credentials using one of the three methods decribed in the [ICESat-2 Data Access Notebook](https://icepyx.readthedocs.io/en/latest/example_notebooks/IS2_data_access.html) example. The `.earthdata_login()` function is still available for backwards compatibility.\n",
+ "\n",
+ "If you are unable to remove `earthdata_login()` calls from your workflow, note that certain inputs, such as `earthdata_uid` and `email`, are no longer required. e.g. `region_a.earthdata_login(earthdata_uid, email)` becomes `region_a.earthdata_login()`\n",
+ "```"
+ ]
+ },
  {
  "cell_type": "markdown",
  "metadata": {},
@@ -895,7 +897,7 @@
  "name": "python",
  "nbconvert_exporter": "python",
  "pygments_lexer": "ipython3",
- "version": "3.9.4"
+ "version": "3.10.12"
  }
  },
  "nbformat": 4,

doc/source/example_notebooks/IS2_cloud_data_access.ipynb

@@ -2,7 +2,9 @@
  "cells": [
  {
  "cell_type": "markdown",
- "metadata": {},
+ "metadata": {
+ "user_expressions": []
+ },
  "source": [
  "# ICESat-2 AWS cloud data access\n",
  "This notebook ({nb-download}`download <IS2_cloud_data_access.ipynb>`) illustrates the use of icepyx for accessing ICESat-2 data currently available through the AWS (Amazon Web Services) us-west2 hub s3 data bucket.\n",
@@ -74,23 +76,37 @@
  },
  {
  "cell_type": "markdown",
- "metadata": {},
+ "metadata": {
+ "user_expressions": []
+ },
  "source": [
  "## Log in to Earthdata and generate an s3 token\n",
- "You can use icepyx's existing login functionality to generate your s3 data access token, which will be valid for *one* hour.\n",
+ "You can use icepyx's existing login functionality to generate your s3 data access token, which will be valid for *one* hour. The icepyx module will renew the token for you after an hour, but if viewing your token over the course of several hours you may notice the values will change.\n",
  "\n",
- "We currently do not have this set up to automatically renew, but [earthaccess](https://nsidc.github.io/earthaccess/), which icepyx uses under the hood for authentication, is working on handling the limits imposed by expiring s3 tokens. If you're interested in working on helping icepyx and earthaccess address these challenges, please get in touch or submit a PR. Documentation/example testers are always appreciated (so you don't have to understand the code)!"
+ "You can access your s3 credentials using:"
  ]
  },
  {
  "cell_type": "code",
  "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# uncommenting the line below will print your temporary login credentials\n",
+ "# reg.s3login_credentials"
+ ]
+ },
+ {
+ "cell_type": "markdown",
  "metadata": {
- "scrolled": true
+ "user_expressions": []
  },
- "outputs": [],
  "source": [
- "reg.earthdata_login(s3token=True)"
+ "```{admonition} Important Authentication Update\n",
+ "Previously, icepyx required you to explicitly use the `.earthdata_login()` function to login. Running this function is no longer required, as icepyx will call the login function as needed. The user will still need to provide their credentials using one of the three methods decribed in the [ICESat-2 Data Access Notebook](https://icepyx.readthedocs.io/en/latest/example_notebooks/IS2_data_access.html) example. The `.earthdata_login()` function is still available for backwards compatibility.\n",
+ "\n",
+ "If you are unable to remove `earthdata_login()` calls from your workflow, note that certain inputs, such as `earthdata_uid` and `email`, are no longer required. e.g. `region_a.earthdata_login(earthdata_uid, email)` becomes `region_a.earthdata_login()`\n",
+ "```"
  ]
  },
  {
@@ -106,7 +122,7 @@
  "metadata": {},
  "outputs": [],
  "source": [
- "s3 = earthaccess.get_s3fs_session(daac='NSIDC', provider=reg._s3login_credentials)"
+ "s3 = earthaccess.get_s3fs_session(daac='NSIDC', provider=reg.s3login_credentials)"
  ]
  },
  {
@@ -176,7 +192,7 @@
  "name": "python",
  "nbconvert_exporter": "python",
  "pygments_lexer": "ipython3",
- "version": "3.10.8"
+ "version": "3.10.12"
  }
  },
  "nbformat": 4,