Adjust docs to account for SHConfig changes (#443)

* fix installation docs * rename config.json to config.toml * adjust readme a bit * update configuration documentation * adjust font types * some minor visual changes * fix wrong name in docstring * Apply suggestions from code review Co-authored-by: Matic Lubej <[email protected]> * Apply suggestions from code review Co-authored-by: Matic Lubej <[email protected]> * Update sentinelhub/aws/client.py Co-authored-by: Matic Lubej <[email protected]> * manually apply correction for notebook * add line for `--show` --------- Co-authored-by: Matic Lubej <[email protected]>
sentinel-hub · Apr 3, 2023 · 18a62e2 · 18a62e2
1 parent 40265a6
commit 18a62e2
Show file tree

Hide file tree

Showing 9 changed files with 56 additions and 66 deletions.
diff --git a/README.md b/README.md
@@ -19,8 +19,7 @@ The main package resources are [GitHub repository](https://github.com/sentinel-h
 
 ## Installation
 
-The package requires a Python version >= 3.8 and an installed C/C++ compiler. The package is available at
-the PyPI package index and can be installed with
+The package requires a Python version >= 3.8. The package is available at the PyPI package index and can be installed with
 
 ```
 $ pip install sentinelhub

diff --git a/docs/source/configure.rst b/docs/source/configure.rst
@@ -1,14 +1,7 @@
 Configuration
 =============
 
-
-The package contains a configuration file ``config.json``. After the package is installed you can check the initial
-configuration parameters using the command line::
-
-$ sentinelhub.config --show
-
-The same configuration can be seen by instantiating an instance of :class:`~sentinelhub.config.SHConfig`;
-without passing parameters the ``config.json`` will be used to populate the values:
+Part of the package configuration is represented by the :class:`~sentinelhub.config.SHConfig` class. It can be adjusted and passed to most of the functions and constructors of the ``sentinelhub`` package to either provide credentials or modify behavior such as the number of download processes.
 
 .. code-block:: python
 
@@ -22,90 +15,94 @@ without passing parameters the ``config.json`` will be used to populate the valu
     >    instance_id='',
     >    sh_client_id='',
     >    sh_client_secret='',
-    >    aws_access_key_id='',
-    >    aws_secret_access_key='',
+    >    sh_base_url='https://services.sentinel-hub.com',
+    >    sh_auth_base_url='https://services.sentinel-hub.com',
     >    ...
     > )
 
+To avoid the need of constant reconfiguration in the code, we also support adjusting the values in a ``config.toml`` file.
 
-Sentinel Hub Configuration
-**************************
+Configuration File
+******************
 
+Whenever a new ``SHConfig`` object is created, the default values of the fields are updated with the contents of the configuration file. The configuration file also supports multiple profiles, which can be used with ``SHConfig("myprofile")``. If no profile is specified, the default profile is used (``sentinelhub.config.DEFAULT_PROFILE``, currently set to ``"default-profile"``). This is also used whenever no explicit ``SHConfig`` is provided to a function/class, unless the preferred profile is set via the `SH_PROFILE` environment variable (more about that in a later section).
 
-In order to use Sentinel Hub services you will need a Sentinel Hub account. If you do not have one yet, you can
-create a free trial account at `Sentinel Hub`_. If you are a researcher you can even apply for a free non-commercial
-account at `ESA OSEO page`_. The following configurations are then linked to your account.
+The configuration file can be found at ``~/.config/sentinelhub/config.toml``. On Windows this usually translates to ``C:/Users/<USERNAME>/.config/sentinelhub/config.toml``. You can get the precise location of the file by calling ``SHConfig.get_config_location()``.
 
-By default parameters ``instance_id``, ``sh_client_id`` and ``sh_client_secret`` will be empty.
+The configuration file follows the standard TOML structure. Sections are denoted by the profile name in square brackets, while the following lines specify ``key=value`` pairs for any fields that should be updated, for example:
 
-Parameter ``instance_id`` is used when using OGC endpoints of the `Sentinel Hub services`_. It is the identifier of a
-configuration users can set up in the `Sentinel Hub Dashboard`_ under "Configuration Utility".
+.. code-block:: toml
 
-The ``sh_client_id`` and ``sh_client_secret`` parameters can also be created in the `Sentinel Hub Dashboard`_ under
-"User settings". The two parameters are needed when accessing protected endpoints of the service (Process, Catalog,
-Batch, BYOC, and other APIs). There is "OAuth clients" frame where we can create a new OAuth client.
+    [default-profile]
+    instance_id = "my-instance-id"
+    max_download_attempts = 3
 
-You can set any of these parameters with::
+    [custom-profile]
+    instance_id = "something-else"
 
-$ sentinelhub.config --instance_id <your instance id>
-$ sentinelhub.config --sh_client_id <your client id> --sh_client_secret <your client secret>
+One can also view the settings for a given profile in the CLI with the command ``sentinelhub.config --profile my-profile --show``.
 
-or set them up by configuring an instance of :class:`~sentinelhub.config.SHConfig`:
+The file can also be updated programmatically by using the ``save`` method.
 
 .. code-block:: python
 
     from sentinelhub import SHConfig
 
     config = SHConfig()
+    config.instance_id = "my-instance-id"
+    config.save("my-profile")
 
-    config.instance_id = '<your instance id>'
-    config.sh_client_id = '<your client id>'
-    config.sh_client_secret = '<your client secret>'
 
+Another option is to update the configuration file via CLI. However this approach can only modify existing profiles, any new profiles need to be added manually or through the Python interface.::
 
-One can save these into the package ``config.json`` file by calling:
+$ sentinelhub.config --profile my-profile --instance_id my-instance-id
 
-.. code-block:: python
+Environment Variables
+*********************
 
-    config.save()
+We generally suggest using the configuration file, but we offer limited support for environmental variables to simplify situations such as building docker images.
 
-Once set (either with command line or as described above), the default parameters to interact with Sentinel Hub
-will be read from ``config.json``, unless you purposely specify an instance of :class:`~sentinelhub.config.SHConfig`
-object containing different parameters.
+The ``SHConfig`` class reads the following environmental variables during initialization:
 
-.. admonition:: Additional information on creating OAuth client
+- ``SH_PROFILE`` that dictates which profile should be used when not explicitly provided.
+- ``SH_CLIENT_ID`` and ``SH_CLIENT_SECRET`` for setting the SentinelHub credentials.
 
-    For detailed instructions on how to obtain credentials, you can see the `Sentinel Hub webinar`_.
 
+Precedence
+**********
 
+The general precedence order is ``explicit parameters > environment > configuration file > defaults``.
 
-Amazon S3 Configuration
-***********************
+This means that ``SHConfig(profile="my-profile", sh_client_id="my-id")`` will be taken into account over ``SH_PROFILE`` and ``SH_CLIENT_ID`` environment variables, which would take precedence over what is specified in the ``configuration.toml``.
 
-The package enables downloading Sentinel-2 L1C and L2A data from `Amazon S3`_ storage buckets. The data is contained in
-Requester Pays buckets therefore `AWS credentials`_ are required to use these capabilities. The credentials
-can be set in the package configuration file with parameters ``aws_access_key_id`` and ``aws_secret_access_key``. This
-can be configured using the command line as::
 
-$ sentinelhub.config --aws_access_key_id <your access key> --aws_secret_access_key <your secret access key>
+Sentinel Hub Configuration
+**************************
 
-or again as above:
 
-.. code-block:: python
+In order to use Sentinel Hub services you will need a Sentinel Hub account. If you do not have one yet, you can
+create a free trial account at `Sentinel Hub`_. If you are a researcher you can even apply for a free non-commercial
+account at `ESA OSEO page`_. The following configurations are then linked to your account.
 
-    from sentinelhub import SHConfig
+Parameter ``instance_id`` is used when using OGC endpoints of the `Sentinel Hub services`_. It is the identifier of a
+configuration users can set up in the `Sentinel Hub Dashboard`_ under "Configuration Utility".
 
-    config = SHConfig()
+The ``sh_client_id`` and ``sh_client_secret`` parameters can also be created in the `Sentinel Hub Dashboard`_ under
+"User settings". The two parameters are needed when accessing protected endpoints of the service (Process, Catalog,
+Batch, BYOC, and other APIs). There is "OAuth clients" frame where we can create a new OAuth client.
 
-    config.aws_access_key_id = '<your access key>
-    config.aws_secret_access_key = '<your secret access key>'
+.. admonition:: Additional information on creating OAuth client
 
+    For detailed instructions on how to obtain credentials, you can see the `Sentinel Hub webinar`_.
 
-possibly storing this information into the package ``config.json`` file (for simpler re-use) by calling:
 
-.. code-block:: python
 
-    config.save()
+Amazon S3 Configuration
+***********************
+
+The package enables downloading Sentinel-2 L1C and L2A data from `Amazon S3`_ storage buckets. The data is contained in
+Requester Pays buckets, therefore `AWS credentials`_ are required to use these capabilities. The credentials
+can be set in the package configuration file with parameters ``aws_access_key_id`` and ``aws_secret_access_key``.
 
 In case the credentials are not set, the package will instead automatically try to use **locally stored AWS credentials**,
 if they were configured according to `AWS configuration instructions`_. Any other configuration parameters (e.g. region)

diff --git a/docs/source/custom_reference/sentinelhub.rst b/docs/source/custom_reference/sentinelhub.rst
@@ -24,7 +24,6 @@ Modules
     sentinelhub.geometry
     sentinelhub.geopedia
     sentinelhub.io_utils
-    sentinelhub.os_utils
     sentinelhub.testing_utils
     sentinelhub.time_utils
     sentinelhub.types
diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -1,7 +1,7 @@
 Installation
 ============
 
-This package requires Python >=3.8 and can be installed with PyPI package manager::
+This package requires Python >=3.8 and can be installed with the PyPI package manager::
 
 $ pip install sentinelhub
 
@@ -17,11 +17,6 @@ In order to install the latest (development) version clone the GitHub_ repositor
 
 $ pip install -e . --upgrade
 
-or manually::
-
-$ python setup.py build
-$ python setup.py install
-
 Before installing ``sentinelhub-py`` on **Windows** it is recommended to install ``shapely`` package from
 Unofficial Windows wheels repository (link_).
 

diff --git a/examples/byoc_request.ipynb b/examples/byoc_request.ipynb
@@ -72,7 +72,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Insert your credentials here in case you don't already have them in config.json file:\n",
+    "# Insert your credentials here in case you don't already have them in the config.toml file:\n",
     "SH_CLIENT_ID = \"\"\n",
     "SH_CLIENT_SECRET = \"\"\n",
     "AWS_ACCESS_KEY_ID = \"\"\n",

diff --git a/examples/data_collections.ipynb b/examples/data_collections.ipynb
@@ -127,7 +127,7 @@
    "source": [
     "from sentinelhub import CRS, BBox, MimeType, SentinelHubRequest, SHConfig\n",
     "\n",
-    "# Write your credentials here if you haven't already put them into config.json\n",
+    "# Write your credentials here if you haven't already put them into config.toml\n",
     "CLIENT_ID = \"\"\n",
     "CLIENT_SECRET = \"\"\n",
     "\n",

diff --git a/sentinelhub/aws/client.py b/sentinelhub/aws/client.py
@@ -86,7 +86,7 @@ def _do_download(self, request: DownloadRequest, s3_client: Any) -> bytes:
         except NoCredentialsError as exception:
             raise ValueError(
                 "The requested data is in Requester Pays AWS bucket. In order to download the data please set "
-                "your access key either in AWS credentials file or in sentinelhub config.json file using "
+                "your access key either in the AWS credentials file or in the sentinelhub config.toml file using "
                 "command line:\n"
                 "$ sentinelhub.config --aws_access_key_id <your AWS key> --aws_secret_access_key "
                 "<your AWS secret key>"

diff --git a/sentinelhub/commands.py b/sentinelhub/commands.py
@@ -30,7 +30,7 @@ def main_help() -> None:
 
 
 def _config_options(func: FC) -> FC:
-    """A helper function which joins click.option functions of each parameter from config.json"""
+    """A helper function which joins `click.option` functions of each parameter from `SHConfig`."""
     for param in list(SHConfig().to_dict())[-1::-1]:
         func = click.option(f"--{param}", param, help=f"Set new values to configuration parameter `{param}`")(func)
     return func

diff --git a/sentinelhub/config.py b/sentinelhub/config.py
@@ -176,7 +176,7 @@ def copy(self) -> SHConfig:
     def to_dict(self, mask_credentials: bool = True) -> Dict[str, Union[str, float]]:
         """Get a dictionary representation of the `SHConfig` class.
 
-        :param hide_credentials: Wether to mask fields containing credentials.
+        :param mask_credentials: Wether to mask fields containing credentials.
         :return: A dictionary with configuration parameters
         """
         config_params = asdict(self)