Skip to content

Commit

Permalink
release(0.3.2)
Browse files Browse the repository at this point in the history 
release(0.3.2)
  • Loading branch information
@nkarasiak
nkarasiak authored Dec 10, 2024
2 parents f01b2a9 + 4acebf7 commit 0a48428
Show file tree
Hide file tree
Showing 13 changed files with 326 additions and 207 deletions.
5 changes: 3 additions & 2 deletions .env.sample
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
EDS_AUTH_URL="https://.."
EDS_CLIENT_ID="123"
EDS_SECRET="123"
EDS_CLIENT_ID="XXX"
EDS_SECRET="XXX"
EDS_API_URL="https://api.earthdaily.com/platform/v1/stac/collections"
21 changes: 0 additions & 21 deletions CONTRIBUTING.md
View file

This file was deleted.

210 changes: 38 additions & 172 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,219 +1,85 @@
<div id="top"></div>
<!-- PROJECT SHIELDS -->
<!--
*** See the bottom of this document for the declaration of the reference variables
*** https://www.markdownguide.org/basic-syntax/#reference-style-links
-->


<!-- PROJECT LOGO -->
<br />
<p>
<h1 >EarthDaily Python Client</h3>

<p>
Your gateway to the Earth Data Store STAC Catalog.
<br />
<a href="https://earthdailyagro.com/"><strong>Who we are</strong></a>
<br />
<br />
<a href="https://github.com/earthdaily/earthdaily-python-client/">Project description</a>
·
<a href="https://github.com/earthdaily/earthdaily-python-client/issues">Report Bug</a>
·
<a href="https://github.com/earthdaily/earthdaily-python-client/issues">Request Feature</a>
</p>
</p>


<div>

[![PyPI version](https://badge.fury.io/py/earthdaily.png)](https://badge.fury.io/py/earthdaily)
[![Documentation](https://img.shields.io/badge/Documentation-html-green.svg)](https://earthdaily.github.io/earthdaily-python-client/)
[![pytest-main](https://github.com/earthdaily/earthdaily-python-client/actions/workflows/pytest-prod.yaml/badge.svg)](https://github.com/earthdaily/earthdaily-python-client/actions/workflows/pytest-prod.yaml)

</div>


<!--[![Stargazers][GitStars-shield]][GitStars-url]-->
<!--[![Forks][forks-shield]][forks-url]-->
<!--[![Stargazers][stars-shield]][stars-url]-->
[![PyPI version](https://badge.fury.io/py/earthdaily.svg)](https://badge.fury.io/py/earthdaily)
[![Documentation](https://img.shields.io/badge/Documentation-Online-brightgreen.svg)](https://earthdaily.github.io/earthdaily-python-client/)
[![Build Status](https://github.com/earthdaily/earthdaily-python-client/actions/workflows/pytest-prod.yaml/badge.svg)](https://github.com/earthdaily/earthdaily-python-client/actions)
![Python Versions](https://img.shields.io/badge/Python-3.10%20|%203.11%20|%203.12-blue)
[![Issues](https://img.shields.io/github/issues/earthdaily/earthdaily-python-client.svg)](https://github.com/earthdaily/earthdaily-python-client/issues)
[![License](https://img.shields.io/badge/license-MIT-blue)](#license)

# EarthDaily Python Client

<!-- TABLE OF CONTENTS -->
<details open>
<summary>Table of Contents</summary>
<ol>
<li>
<a href="#about-the-project">About The Project</a>
</li>
<li>
<a href="#getting-started">Getting Started</a>
<ul>
<li><a href="#prerequisites">Prerequisites</a></li>
<li><a href="#installation">Installation</a></li>
</ul>
</li>
<li><a href="#usage">Usage</a></li>
<li><a href="#support-development">Support development</a></li>
<li><a href="#license">License</a></li>
<li><a href="#contact">Contact</a></li>
<li><a href="#copyrights">Copyrights</a></li>
</ol>
</details>
Your gateway to the Earth Data Store STAC Catalog.

<!-- ABOUT THE PROJECT -->
## About The Project
[EarthDaily Homepage](https://earthdaily.com) |
[Report Bug](https://github.com/earthdaily/earthdaily-python-client/issues) |
[Request Feature](https://github.com/earthdaily/earthdaily-python-client/issues)

In the realm of geospatial data analysis and Earth observation, the EarthDaily Python package emerges as a powerful toolset that seamlessly connects you to the vast and invaluable Stac catalog Earth Data Store. This package is designed with the vision of simplifying and optimizing your workflow, ensuring that you can harness the full potential of Earth observation data with ease and efficiency.

Our package is built upon a foundation of best practices, meticulously crafted to elevate your data analysis experience. With EarthDaily, you can effortlessly navigate the complexities of datacube creation, including crucial processes like conversion to reflectance and automatic clipping to your area of interest. Additionally, we've taken care to make EarthDaily fully compatible with Dask, enabling you to scale your data preprocessing tasks with confidence and precision.
---

The **EarthDaily Python client** simplifies access to the Earth Data Store STAC catalog and streamlines workflows for geospatial data analysis and Earth observation. It automates key preprocessing tasks, making it easier to work with Earth observation data.

## Features

See [documentation](https://earthdaily.github.io/earthdaily-python-client/) for more information
- **Easy Data Access**: Connect directly to the Earth Data Store STAC catalog.
- **Automated Datacube Creation**: Includes reflectance conversion and clipping to areas of interest.
- **Scalable Processing**: Fully compatible with Dask for handling large datasets.

## Getting started
This package is designed to make geospatial workflows more efficient and accessible for researchers and analysts working with Earth observation data.

### Prerequisites

Make sure you have valid EDS credentials. If you need to get trial access, please contact us.

This package has been tested on Python 3.10, 3.11 and 3.12.
Make sure you have valid Earth Data Store authentication credentials. These can be retrieved from the [EarthDaily Account Management](https://console.earthdaily.com/account) page.

<p align="center">
<img src="docs/assets/images/account.png" width="450">
</p>

### Installation
## Installation

#### From pypi, using pip
### From PyPI, using pip

`pip install earthdaily`

#### From repository, using mamba, conda and pip
### From Repository using Conda and pip

```console
# Clone the repository and go inside
# Clone the repository and navigate 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
# Create a conda environment and install dependencies
conda env create -n earthdaily -f requirements.yml
conda init
conda activate earthdaily

# Install package in editable mode
pip install -e .
```

### Authentication

In order to generate a credentials file with the right variables and layout, you can use the `copy-earthdaily-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-earthdaily-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-earthdaily-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-earthdaily-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 from Environment Variables

Authentication credentials can be automatically parsed from environment variables.
As a convenience python-dotenv is supported.
The [python-dotenv](https://github.com/theskumar/python-dotenv) package is supported for convenience.

You can generate a .env credentials file with the following command:
Rename the `.env.sample` file in this repository to `.env` and enter your Earth Data Store authentication credentials.
Note this file is gitingored and will not be committed.

```console
copy-earthdaily-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:
In your script or notebook, add:

```python
from dotenv import load_dotenv

load_dotenv() # take environment variables from .env.
load_dotenv(".env") # Load environment variables from .env file
```

### Usage

See the documentation for more information.
## Quickstart
To help you get started quickly, we provide a `quickstart.ipynb` Jupyter notebook that demonstrates how to use the EarthDaily Python client. You only need your `.env` file with your authentication credentials to run it.

### Support development
Simply open the notebook, load your environment variables as shown above, and follow the instructions to begin accessing and analyzing Earth observation data.

If you find this package useful, please consider supporting its development.

<!-- CONTRIBUTING -->
## Support development

If this project has been useful, that it helped you or your business to save precious time, don't hesitate to give it a star.

<p align="right">(<a href="#top">back to top</a>)</p>

## License

Distributed under the MIT License.

<p align="right">(<a href="#top">back to top</a>)</p>

## Contact

For any additonal information, please [email us](mailto:sales@earthdailyagro.com).

<p align="right">(<a href="#top">back to top</a>)</p>
If this project has been helpful and saved you time, please consider giving it a star ⭐

## Copyrights

© EarthDaily | All Rights Reserved.

<p align="right">(<a href="#top">back to top</a>)</p>
76 changes: 76 additions & 0 deletions docs/AUTHENTICATION.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
### Authentication

Advanced users can use the `earthdaily/utils/copy_credentials_template.py` script to generate credentials file as JSON, TOML or .env. Alternatively use one of the approaches listed below.

#### Authentication from the default credentials file

Using a TOML file for authentication has the advantage that the authentication is handled seamlessly by the client and it is not necessary to point to the authentication file.
A TOML credentials file will be created in the following locations:

* "$HOME/.earthdaily/credentials" on linux
* "$USERPROFILE/.earthdaily/credentials" on Windows

Run from the root of the repository:
```console
copy-earthdaily-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()
```

#### Authentication 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-earthdaily-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"))
```

#### Authentication 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-earthdaily-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"))
```

#### Authentication from Environment Variables

Authentication credentials can be automatically parsed from environment variables.
The [python-dotenv](https://github.com/theskumar/python-dotenv) package is supported for convenience.

Rename the `.env.sample` file in this repository to `.env` and enter your Earth Data Store authentication credentials.
Note this file is gitingored and will not be committed.

In your script or notebook, add:

```python
from dotenv import load_dotenv

load_dotenv(".env") # Load environment variables from .env file
```
6 changes: 6 additions & 0 deletions CHANGELOG.md → docs/CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.3.2] - 2024-12-10

### Added

- `~/.earthdaily/credentials` ini file support.

## [0.3.1] - 2024-11-22

### Fixed
Expand Down
2 changes: 0 additions & 2 deletions docs/CHANGELOG.rst
View file

This file was deleted.

Loading

0 comments on commit 0a48428

Please sign in to comment.