Create a script that generates credentials templates

README.md

@@ -85,18 +85,101 @@ This package has been tested on Python 3.10, 3.11 and 3.12.
 
 ### Installation
 
-#### Using pip 
+#### From pypi, using pip
 
 `pip install earthdaily`
 
-#### Planned : Using conda/mamba
+#### From repository, using mamba, conda and pip
+
+```console
+# Clone the repository and go inside
+git clone git@github.com:earthdaily/earthdaily-python-client.git
+cd earthdaily-python-client
+
+# Create a virtual environment named earthdaily and install package dependencies
+mamba env create -n earthdaily -f requirements.yml
+conda activate earthdaily
+
+# Install package in editable mode
+pip install -e .
+```
 
 ### Authentication
-Authentication credentials are accessed from environment variables. As a convenience python-dotenv is supported. 
-Copy the `.env.sample` file and rename to simply `.env` and update with your credentials. This file is gitignored. 
+
+In order to generate a credentials file with the right variables and layout, you can use the `copy-credentials-template` script that is installed along the earthdaily package. It can generate credentials file as JSON, TOML or .env.
+Generate the credentials file of your liking and edit it to insert your credentials.
+
+
+#### From the default credentials file
+
+Create a TOML credentials file in the default location:
+* "$HOME/.earthdaily/credentials" on linux
+* "$USERPROFILE/.earthdaily/credentials" on Windows
+
+```console
+copy-credentials-template --default
+```
+
+Edit it to insert your credentials.
+The following code will automatically find and use the credentials for authentification.
+
+```python
+from earthdaily import EarthDataStore
+eds = EarthDataStore()
+```
+
+#### From a JSON file
+
+Authentication credentials can be given as an input JSON file.
+You can generate a JSON credentials file with the following command:
+
+```console
+copy-credentials-template --json "/path/to/the/credentials_file.json"
+```
+
+Edit it to insert your credentials.
+Then use it as input for authentification:
+
+```python
+from pathlib import Path
+from earthdaily import EarthDataStore
+eds = EarthDataStore(json_path = Path("/path/to/the/credentials_file.json"))
+```
+
+#### From a TOML file
+
+Authentication credentials can be given as input with a TOML file.
+You can generate a TOML credentials file with the following command:
+
+```console
+copy-credentials-template --toml "/path/to/the/credentials_file"
+```
+
+Edit it to insert your credentials.
+Then use it as input for authentification:
+
+```python
+from pathlib import Path
+from earthdaily import EarthDataStore
+eds = EarthDataStore(toml_path = Path("/path/to/the/credentials_file"))
+```
+
+#### From environment variables
+
+Authentication credentials can be automatically parsed from environment variables.
+As a convenience python-dotenv is supported. 
+
+You can generate a .env credentials file with the following command:
+
+```console
+copy-credentials-template --env "/path/to/the/.env"
+```
+
+Or you can copy the `.env.sample` file from the repository and rename it to `.env`.
+Edit it to insert your credentials.
 Then add to your script/notebook:
 
-```python3
+```python
 from dotenv import load_dotenv
 
 load_dotenv()  # take environment variables from .env.

earthdaily/utils/copy_credentials_template.py

@@ -0,0 +1,106 @@
+"""
+Utility script used for copying credentials templates to a user-defined path
+"""
+
+import click
+import dotenv
+import json
+import toml
+from pathlib import Path
+
+default_path = Path.home()/".earthdaily/credentials"
+
+default_configuration = {
+    "EDS_AUTH_URL" : "https://..",
+    "EDS_CLIENT_ID" : "123",
+    "EDS_SECRET" : "123",
+}
+
+def write_json(json_path: Path) -> None:
+    """
+    Write template JSON credentials file.
+
+    Parameters
+    ----------
+    json_path : Path
+        Path to output JSON file.
+    """
+    print(f"Try to write credentials template to {json_path}")
+
+    if json_path.exists():
+        print(f"{json_path} already exists")
+        return
+
+    with json_path.open("w") as f:
+        json.dump(default_configuration, f)
+
+    print(f"Credentials file written to {json_path}")
+    print("Please edit it to insert your credentials")
+
+def write_toml(toml_path: Path) -> None:
+    """
+    Write template TOML credentials file.
+
+    Parameters
+    ----------
+    toml_path : Path
+        Path to output TOML file.
+    """
+    print(f"Try to write credentials template to {toml_path}")
+
+    if toml_path.exists():
+        print(f"{toml_path} already exists")
+        return
+
+    with toml_path.open("w") as f:
+        toml.dump({"default" : default_configuration}, f)
+
+    print(f"Credentials file written to {toml_path}")
+    print("Please edit it to insert your credentials")
+
+def write_env(env_path: Path) -> None:
+    """
+    Write template .env credentials file.
+
+    Parameters
+    ----------
+    env_path : Path
+        Path to output .env file.
+    """
+    print(f"Try to write credentials template to {env_path}")
+
+    if env_path.exists():
+        print(f"{env_path} already exists")
+        return
+
+    with env_path.open("w") as f:
+        for key, value in default_configuration.items():
+            line = f'{key}="{value}"\n'
+            f.write(line)
+
+    print(f"Credentials file written to {env_path}")
+    print("Please edit it to insert your credentials")
+
+
+@click.command("Copy credentials templates in all accepted formats")
+@click.option("--json", "json_path", type = click.Path(path_type = Path, exists = False), required = False, help = "Path to the output JSON file containing the credentials keys (but no values)")
+@click.option("--toml", "toml_path", type = click.Path(path_type = Path, exists = False), required = False, help = "Path to the output TOML file containing the credentials keys (but no values)")
+@click.option("--env", "env_path", type = click.Path(path_type = Path, exists = False), required = False, help = "Path to the output .env file containing the credentials keys (but no values)")
+@click.option("--default", "default", is_flag=True, show_default=True, default = False, help=f"Copy the TOML template to {default_path}, with credential keys (and no values)")
+def cli(json_path:Path, toml_path: Path, env_path: Path, default: bool) -> None:
+
+    if json_path is not None:
+        write_json(json_path = json_path)        
+
+    if toml_path is not None:
+        write_toml(toml_path = toml_path)
+
+    if env_path is not None:
+        write_env(env_path = env_path)
+
+    if default:
+        default_path.parent.mkdir(exist_ok = True, parents = True)
+        write_toml(toml_path = default_path)
+
+if __name__ == "__main__":
+    cli()

requirements.yml

@@ -23,4 +23,5 @@ dependencies:
 - dask>=2024.4
 - spyndex
 - dask-image
-- toml
+- toml
+- click

requirements_dev.yml

@@ -51,4 +51,6 @@ dependencies:
   - dask-image
   - geocube
   - spyndex
-  - sphinx-rtd-theme
+  - sphinx-rtd-theme
+  - toml
+  - click

setup.py

@@ -38,11 +38,18 @@
         "spyndex",
         "dask-image",
         "numba",
-        "geocube"
+        "geocube",
+        "click",
+        "toml",
     ],
     include_package_data=True,
     package_data={"":['*.geojson','*.json']},
     license="MIT",
     zip_safe=False,
     keywords=["Earth Data Store", "earthdaily", "earthdailyagro", "stac"],
+    entry_points = {
+        'console_scripts': [
+            'copy-credentials-template=earthdaily.utils.copy_credentials_template:cli'
+        ],
+    },
 )