Merge pull request #358 from ASFHyP3/develop

Release v7.7.0

Author: jtherrmann

CHANGELOG.md

@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [PEP 440](https://www.python.org/dev/peps/pep-0440/)
 and uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.7.0]
+
+### Added
+* Added support for using an [Earthdata Login Bearer Token](https://urs.earthdata.nasa.gov/documentation/for_users/user_token) when authenticating the `HyP3` object. 
+
 ## [7.6.0]
 ### Changed
 * `ARIA-S1-GUNW` jobs now uses `reference_date` and `secondary_date` as input instead of a list of granules

docs/hyp3_authentication.ipynb

@@ -0,0 +1,213 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "c71ac86b03faa125",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "# Authenticating a HyP3 Session with the SDK\n",
+    "\n",
+    "When initializing a HyP3 object with the HyP3 SDK, you have three options:\n",
+    "1. Input your EDL username and password\n",
+    "2. Input your EDL Bearer Token\n",
+    "3. Store your credentials locally in a .netrc file in your home directory\n",
+    "\n",
+    "This tutorial will walk you through each of these authentication methods. If you have not created an Earthdata Login account yet, make sure to do so here: https://urs.earthdata.nasa.gov/users/new.\n",
+    "\n",
+    "Likewise, before starting, make sure you have `hyp3-sdk` installed locally and ensure the version is >=7.7.0."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6b0bbf63de13b184",
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "!pip install 'hyp3-sdk>=7.7.0'"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "import hyp3_sdk as sdk"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "a38df62d8552468b"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6a29e00aa30bdf90",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "## Using your username and password\n",
+    "This option requires minimal amount of set up. All you need is to know your EDL username and password. You can either prompt for a username and password by passing `password` in as `prompt`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3fa21cf01ff3ca32",
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "HyP3 = sdk.HyP3(prompt='password')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1095f5668639490b",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "Or pass them directly:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f2b96d74e0d60fc1",
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "username = 'myusername'\n",
+    "password = 'mypassword'\n",
+    "\n",
+    "HyP3 = sdk.HyP3(username=username, password=password)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4d0b9fa22a7d6aa",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "## Using your EDL Bearer Token\n",
+    "Alternatively, you can authenticate your HyP3 object using your EDL token. Follow this documentation to create one: https://urs.earthdata.nasa.gov/documentation/for_users/user_token.\n",
+    "\n",
+    "Once that token is set up, prompt for an EDL token:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "HyP3 = sdk.HyP3(prompt='token')"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "7805f87763471220"
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "Or pass it directly:"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "19f255f3f2c1a7c4"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ae92262a7e05b711",
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "token = 'mytoken'\n",
+    "HyP3 = sdk.HyP3(token=token)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c9fd77b21a1122bb",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "## Using a local .netrc file\n",
+    "This option take a bit more effort to set up but saves time in the long run. You will create a .netrc file in your local home directory. \n",
+    "\n",
+    "You can do this by running the following commands, replacing `USER` and `PASSWORD` with your EDL username and password:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "561b0abd53726fec",
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "%%bash\n",
+    "echo 'machine urs.earthdata.nasa.gov login USER password PASSWORD' > ~/.netrc\n",
+    "chmod 0600 ~/.netrc"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "27ee6339a540cb39",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "Now, when you initialize the HyP3 object, your credentials will be pulled from the .netrc file:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e7bb4b87181a5660",
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "HyP3 = sdk.HyP3()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/hyp3_job_name_change.ipynb

@@ -21,7 +21,7 @@
    },
    "outputs": [],
    "source": [
-    "!pip install 'hyp3-sdk>=7.3.0' \n",
+    "!pip install 'hyp3-sdk>=7.7.0' \n",
     "\n",
     "import hyp3_sdk as sdk"
    ]
@@ -45,7 +45,7 @@
    },
    "outputs": [],
    "source": [
-    "hyp3 = sdk.HyP3(prompt=True)\n",
+    "hyp3 = sdk.HyP3(prompt='token')\n",
     "\n",
     "project_name = 'renameDemo'\n",
     "reference = 'S1_136231_IW2_20200604T022312_VV_7C85-BURST'\n",

docs/sdk_example.ipynb

@@ -86,7 +86,7 @@
    "outputs": [],
    "source": [
     "# or enter your credentials\n",
-    "hyp3 = sdk.HyP3(prompt=True)"
+    "hyp3 = sdk.HyP3(prompt='token')"
    ]
   },
   {

docs/search_other_user_jobs.ipynb

@@ -14,7 +14,7 @@
     "from hyp3_sdk import HyP3\n",
     "\n",
     "\n",
-    "hyp3 = HyP3()\n",
+    "hyp3 = HyP3(prompt='token')\n",
     "my_rtc_jobs = hyp3.find_jobs(name='rtc-example')"
    ]
   },

src/hyp3_sdk/hyp3.py

@@ -30,7 +30,8 @@ def __init__(
         api_url: str = PROD_API,
         username: str | None = None,
         password: str | None = None,
-        prompt: bool = False,
+        token: str | None = None,
+        prompt: Literal['password', 'token'] | bool | None = None,
     ):
         """If username and password are not provided, attempts to use credentials from a `.netrc` file.
 
@@ -40,17 +41,31 @@ def __init__(
                 Both username and password must be provided if either is provided.
             password: Password for authenticating to `urs.earthdata.nasa.gov`.
                 Both username and password must be provided if either is provided.
-            prompt: Prompt for username and/or password interactively when they
-                are not provided as keyword parameters
+            token: Earthdata Login Bearer Token for authenticating to `urs.earthdata.nasa.gov`
+            prompt: Either 'password' or 'token' to prompt for EDL username and password or EDL bearer token, respectively.
         """
         self.url = api_url
 
-        if username is None and prompt:
-            username = input('NASA Earthdata Login username: ')
-        if password is None and prompt:
-            password = getpass('NASA Earthdata Login password: ')
+        if prompt not in (True, False, 'password', 'token', None):
+            raise ValueError(f'Unexpected value {prompt} for `prompt`')
 
-        self.session = hyp3_sdk.util.get_authenticated_session(username, password)
+        if prompt is True:
+            warnings.warn(
+                'Passing `prompt=True` is deprecated. Please use either `prompt="password"` or `prompt="token"`',
+                UserWarning,
+            )
+            prompt = 'password'
+
+        if prompt == 'password':
+            if username is None:
+                username = input('NASA Earthdata Login username: ')
+            if password is None:
+                password = getpass('NASA Earthdata Login password: ')
+
+        if prompt == 'token' and token is None:
+            token = getpass('NASA Earthdata Login bearer token: ')
+
+        self.session = hyp3_sdk.util.get_authenticated_session(username, password, token)
         self.session.headers.update({'User-Agent': f'{hyp3_sdk.__name__}/{hyp3_sdk.__version__}'})
 
         hostname = urlsplit(self.url).hostname

src/hyp3_sdk/util.py

@@ -71,7 +71,9 @@ def get_tqdm_progress_bar():
     return tqdm
 
 
-def get_authenticated_session(username: str | None, password: str | None) -> requests.Session:
+def get_authenticated_session(
+    username: str | None = None, password: str | None = None, token: str | None = None
+) -> requests.Session:
     """Log into HyP3 using credentials for `urs.earthdata.nasa.gov` from either the provided
      credentials or a `.netrc` file.
 
@@ -80,10 +82,14 @@ def get_authenticated_session(username: str | None, password: str | None) -> req
     """
     s = requests.Session()
 
+    if token is not None:
+        s.headers.update({'Authorization': f'Bearer {token}'})
+        return s
+
     if username is not None and password is not None:
         response = s.get(AUTH_URL, auth=(username, password))
         auth_error_message = (
-            'Was not able to authenticate with credentials provided\n'
+            'Was not able to authenticate with username and password provided\n'
             'This could be due to invalid credentials or a connection error.'
         )
     else:

tests/conftest.py

@@ -13,7 +13,7 @@
 
 @pytest.fixture(autouse=True)
 def get_mock_hyp3():
-    def mock_get_authenticated_session(username, password):
+    def mock_get_authenticated_session(username, password, token):
         session = requests.Session()
         session.cookies.set('asf-urs', 'test-cookie', domain='.asf.alaska.edu')
         return session

tests/test_hyp3.py

@@ -8,7 +8,7 @@
 
 import hyp3_sdk
 from hyp3_sdk import Batch, HyP3, Job
-from hyp3_sdk.exceptions import HyP3Error
+from hyp3_sdk.exceptions import AuthenticationError, HyP3Error
 
 
 @responses.activate
@@ -24,6 +24,25 @@ def test_session_headers(get_mock_hyp3):
     assert responses.calls[1].request.headers['User-Agent'] == f'hyp3_sdk/{hyp3_sdk.__version__}'
 
 
+def test_invalid_prompt():
+    with pytest.raises(ValueError, match=r'^Unexpected value'):
+        HyP3(prompt='prompt')  # type: ignore[arg-type]
+
+
+@responses.activate
+def test_no_prompt():
+    responses.add(responses.GET, hyp3_sdk.util.AUTH_URL, status=401)
+
+    with pytest.raises(AuthenticationError, match=r'^Was not able to authenticate with \.netrc file'):
+        HyP3()
+
+    with pytest.raises(AuthenticationError, match=r'^Was not able to authenticate with \.netrc file'):
+        HyP3(prompt=False)
+
+    with pytest.raises(AuthenticationError, match=r'^Was not able to authenticate with \.netrc file'):
+        HyP3(prompt=None)
+
+
 @responses.activate
 def test_find_jobs(get_mock_hyp3, get_mock_job):
     api_response_mock = {