Skip to content

Commit

Permalink
Issue #264/#187 add basic docs on configuration files
Browse files Browse the repository at this point in the history
  • Loading branch information
soxofaan committed Mar 30, 2022
1 parent 6068835 commit 4c9c40c
Show file tree
Hide file tree
Showing 4 changed files with 97 additions and 0 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
([#279](https://github.com/Open-EO/openeo-python-client/issues/279))
- Added `DataCube.resample_cube_temporal` ([#284](https://github.com/Open-EO/openeo-python-client/issues/284))
- Add `target_dimension` argument to `DataCube.aggregate_spatial` ([#288](https://github.com/Open-EO/openeo-python-client/issues/288))
- Add basic configuration file system to define a default back-end URL and enable auto-authentication ([#264](https://github.com/Open-EO/openeo-python-client/issues/264), [#187](https://github.com/Open-EO/openeo-python-client/issues/187))

### Changed

Expand Down
40 changes: 40 additions & 0 deletions docs/auth.rst
Original file line number Diff line number Diff line change
Expand Up @@ -408,6 +408,9 @@ when authenticating with the Refresh Token Flow like this::
You can also bootstrap the refresh token file
as described in :ref:`oidc_auth_get_refresh_token`


.. _auth_configuration_files:

Config files and ``openeo-auth`` helper tool
=============================================

Expand Down Expand Up @@ -551,6 +554,43 @@ For example::
Stored refresh token in '/home/john/.local/share/openeo-python-client/refresh-tokens.json'



.. _default_url_and_auto_auth:

Default openEO back-end URL and auto-authentication
=====================================================

.. versionadded:: 0.10.0


If you often use the same openEO back-end URL and authentication scheme,
it can be handy to put these in a configuration file as discussed at :ref:`configuration_files`.

.. note::
Note that these (INI) configuration files are different from the JSON config files
discussed earlier under :ref:`auth_configuration_files`.
The latter are for storing authentication related secrets and are mostly
managed automatically.
The former are not for storing secrets, are usually edited manually,
can be placed at various locations and it is ok to store them in version control.

For example, to define a default back-end and automatically use OpenID Connect authentication
add these configuration options to the :ref:`desired configuration file <configuration_file_locations>`::

[Connection]
default_backend = openeo.cloud
auto_authenticate = oidc

Getting an authenticated connection is now as simple as::

>>> import openeo
>>> con = openeo.connect()
Loaded openEO client config from openeo-client-config.ini
Using default back-end URL 'openeo.cloud' (from config)
Doing auto-authentication 'oidc' (from config)
Authenticated using refresh token.


Troubleshooting tips
====================

Expand Down
55 changes: 55 additions & 0 deletions docs/configuration.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@

===============
Configuration
===============

.. warning::
Configuration files are an experimental feature
and some details are subject to change.

.. versionadded:: 0.10.0


.. _configuration_files:

Configuration files
====================

Some functionality of the openEO Python client library can customized
through a configuration file.

Format
-------

At the moment, only INI-style configs are supported.
This is a simple configuration format, easy to maintain
and it is supported out of the box in Python (without additional libraries).

Example (note the use of sections and support for comments)::

[General]
# Print loaded configuration file and default back-end URLs in interactive mode
verbose = auto

[Connection]
default_backend = openeo.cloud


.. _configuration_file_locations:

Location
---------

The following configuration locations are probed (in this order) for an existing configuration file. The first successful hit will be loaded:

- the path in environment variable ``OPENEO_CLIENT_CONFIG`` if it is set (filename must end with extension ``.ini``)
- the file ``openeo-client-config.ini`` in the current working directory
- the file ``${OPENEO_CONFIG_HOME}/openeo-client-config.ini`` if the environment variable ``OPENEO_CONFIG_HOME`` is set
- the file ``${XDG_CONFIG_HOME}/openeo-python-client/openeo-client-config.ini`` if environment variable ``XDG_CONFIG_HOME`` is set
- the file ``.openeo-client-config.ini`` in the home folder of the user


Configuration options
----------------------

TODO
1 change: 1 addition & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ OpenEO Python Client
udf
datacube_construction
machine_learning
configuration
cookbook/index
api
development
Expand Down

0 comments on commit 4c9c40c

Please sign in to comment.