Release version 3.9.0, Merge pull request #445 from sentinel-hub/develop

Release version 3.9.0

.flake8

@@ -2,7 +2,7 @@
 # B028 is ignored because !r flags cannot be used in python < 3.8
 ignore = E203, W503, C408, B028
 exclude = .git, __pycache__
-min_python_version = 3.7.0
+min_python_version = 3.8.0
 max-line-length= 120
 max-complexity = 13
 per-file-ignores =

.github/workflows/ci_action.yml

@@ -55,7 +55,7 @@ jobs:
         run: pip install -e .[AWS,DEV]
 
       - name: Run mypy
-        run: mypy sentinelhub setup.py
+        run: mypy sentinelhub
 
       - name: Run pylint
         run: pylint sentinelhub

.pre-commit-config.yaml

@@ -40,13 +40,13 @@ repos:
     hooks:
       - id: flake8
         additional_dependencies:
-          - flake8-bugbear
-          - flake8-comprehensions
-          - flake8-simplify
-          - flake8-typing-imports
+          - flake8-bugbear==23.2.13
+          - flake8-comprehensions==3.10.1
+          - flake8-simplify==0.19.3
+          - flake8-typing-imports==1.14.0
 
   - repo: https://github.com/nbQA-dev/nbQA
-    rev: 1.6.1
+    rev: 1.6.3
     hooks:
       - id: nbqa-black
       - id: nbqa-isort

Makefile

@@ -1,22 +1,15 @@
 # Makefile for creating a new release of the package and uploading it to PyPI
-# This way is preferred to manual because it also resets config.json
-
-PYTHON = python3
-CONFIG = sentinelhub.config
 
 help:
-	@echo "Use 'make upload' to reset config.json and upload the package to PyPi"
-
-reset-config:
-	$(CONFIG) --reset
+	@echo "Use 'make upload' to upload the package to PyPi"
 
-upload: reset-config
+upload:
 	rm -r dist | true
-	$(PYTHON) setup.py sdist
+	python -m build --sdist --wheel
 	twine upload --skip-existing dist/*
 
 # For testing:
-test-upload: reset-config
+test-upload:
 	rm -r dist | true
-	$(PYTHON) setup.py sdist
+	python -m build --sdist --wheel
 	twine upload --repository testpypi --skip-existing dist/*

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.7 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

docs/source/conf.py

@@ -22,7 +22,7 @@
 
 # General information about the project.
 project = "Sentinel Hub"
-project_copyright = "2018, Sentinel Hub"
+project_copyright = "2017, Sinergise"
 author = "Sinergise EO research team"
 doc_title = "sentinelhub Documentation"
 
@@ -58,9 +58,9 @@
     "sphinx.ext.coverage",
     "sphinx.ext.mathjax",
     "sphinx.ext.githubpages",
+    "sphinx_mdinclude",
     "nbsphinx",
     "sphinx_rtd_theme",
-    "m2r2",
 ]
 
 # Include typehints in descriptions

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)

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

docs/source/install.rst

@@ -1,7 +1,7 @@
 Installation
 ============
 
-This package requires Python >=3.7 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_).