teledetection 0.1.0__tar.gz

teledetection-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+.idea/
+*.egg-info/
+build/
+dist/
+draft
+.vscode/
+.coverage
+public*/
+*venv/
+*.xml
+*.tif

teledetection-0.1.0/.gitlab-ci.yml

@@ -0,0 +1,65 @@
+include:
+  - project: "cdos-pub/pycode-quality"
+    ref: "main"
+    file:
+      - ".gitlab/ci/static-analysis.yml"
+      - ".gitlab/ci/doc.yml"
+      - ".gitlab/ci/docker-compose-tests.yml"
+      - ".gitlab/ci/pip.yml"
+
+default:
+  tags:
+    - armageddon
+   
+variables:
+  PYTHON_IMG: python:3.12-slim
+  PACKAGE_INSTALL_EXTRAS: "[test,upload]"
+  PIP_PACKAGE_URL: "https://upload.pypi.org/legacy/"
+  TWINE_USERNAME: __token__
+  TWINE_PASSWORD: ${PYPI_TOKEN}
+  DOCKER_COMPOSE_CHDIR: "tests"
+
+  DOC_BUILD_SELF: true
+
+stages:
+  - Docker compose tests
+  - Test
+  - Static Analysis
+  - Documentation
+  - Pip
+
+.static_analysis_base:
+  allow_failure: false
+
+Tests with docker compose:
+  coverage: '/^TOTAL.+?(\d+\%)$/'
+  after_script:
+    - ls -lha
+  artifacts:
+    paths:
+      - .coverage
+    reports:
+      junit: report.xml
+
+Code coverage:
+  stage: Static Analysis
+  image: python:3.10-slim
+  script:
+    - ls -lha
+    - mkdir /app
+    - cp -r . /app
+    - pip install coverage
+    - coverage report
+    - coverage xml
+    - coverage html
+  needs:
+    - Tests with docker compose
+  except: [main, tags]
+  artifacts:
+    paths:
+      - htmlcov/
+    when: always
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml

teledetection-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 INRAE
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

teledetection-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: teledetection
+Version: 0.1.0
+Summary: Software development kit for the Geospatial Data Center of 'la Maison de la Teledetection'
+Author-email: Rémi Cresson <remi.cresson@inrae.fr>, Pablo Boizeau <pablo.boizeau@ird.fr>
+License: Apache-2.0
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+License-File: LICENSE
+Requires-Dist: setuptools>=61.2
+Requires-Dist: click>=7.1
+Requires-Dist: pydantic<3.0.0,>=1.7.3
+Requires-Dist: pystac>=1.0.0
+Requires-Dist: pystac-client>=0.2.0
+Requires-Dist: requests>=2.25.1
+Requires-Dist: packaging
+Requires-Dist: qrcode
+Requires-Dist: appdirs
+Requires-Dist: pydantic_settings
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: coverage; extra == "test"
+Provides-Extra: upload
+Requires-Dist: rich; extra == "upload"
+Requires-Dist: rasterio; extra == "upload"
+Requires-Dist: rio-cogeo; extra == "upload"
+Requires-Dist: rio-stac; extra == "upload"
+Dynamic: license-file

teledetection-0.1.0/README.md

@@ -0,0 +1,28 @@
+# Teledetection
+
+<p align="center">
+<img src="doc/logo.png" width="320px">
+<br>
+<a href="https://forgemia.inra.fr/cdos-pub/teledetection/-/releases">
+<img src="https://forgemia.inra.fr/cdos-pub/teledetection/-/badges/release.svg">
+</a>
+<a href="https://forgemia.inra.fr/cdos-pub/teledetection/-/commits/main">
+<img src="https://forgemia.inra.fr/cdos-pub/teledetection/badges/main/pipeline.svg">
+</a>
+<a href="LICENSE">
+<img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg">
+</a>
+<a href="https://forgemia.inra.fr/cdos-pub/teledetection/-/commits/main">
+<img src="https://forgemia.inra.fr/cdos-pub/teledetection/badges/main/coverage.svg">
+
+</p>
+
+**teledetection** enables to use the STAC based geospatial data infrastructure 
+of *la Maison de la Teledetection*.
+
+For more information read the [documentation](https://cdos-pub.pages.mia.inra.fr/teledetection).
+
+## Contact
+
+remi cresson @ inrae
+pablo boizeau @ ird

teledetection-0.1.0/RELEASE_NOTES.txt

@@ -0,0 +1,3 @@
+0.0.1
+
+- Initial commit

teledetection-0.1.0/doc/access.md

@@ -0,0 +1,30 @@
+# Get access to push data
+
+The *Maison de la Teledetection* STAC API is transactionnal: any user 
+can push STAC objects to the API. On the other end, the signing URLs 
+API allows to upload files to the servers. 
+
+To be able to push STAC objects and files, a policy must be defined for 
+the user to allow the operations on the `collections` (for STAC) and 
+`storages` (for files) resources, in 
+[this repository](https://forgemia.inra.fr/cdos-pub/admin/cdos-ops).
+To request the required permissions, the user can perform a 
+[merge request](https://docs.gitlab.com/ee/user/project/merge_requests/) 
+, to modify the `policies.yaml` file of the repository.
+
+## Example of `policies.yaml`
+
+```yaml
+rules:
+- user: user_name
+  collections:
+  - nom-collection-1
+  - nom-collection-2
+  storages:
+  - https://s3-data.meso.umontpellier.fr/bucket1/prefixe1
+  - https://s3-data.meso.umontpellier.fr/bucket1/prefixe2
+  - https://s3-data.meso.umontpellier.fr/bucket2
+
+```
+
+Note that `collections` and `storages` are completely independent.

teledetection-0.1.0/doc/additional_resources.md

@@ -0,0 +1,13 @@
+# Additional resources
+
+## API Documentation
+
+- [*Maison de la Teledetection* STAC API](https://stacapi.stac.teledetection.fr/api.html)
+- [*THEIA-MTD* STAC API](https://theia.stac.teledetection.fr/api.html)
+- [*Maison de la Teledetection* URL signing API](https://s3-signing.stac.teledetection.fr/docs)
+
+## STAC documentation
+
+- [PySTAC documentation](https://pystac.readthedocs.io/en/stable/api/pystac.html)
+- [PySTAC-Client documentation](https://pystac-client.readthedocs.io/en/stable/)
+- More information about the [STAC specification](https://stacspec.org/en/about/stac-spec/)

teledetection-0.1.0/doc/advanced.md

@@ -0,0 +1,114 @@
+# Advanced use
+
+## Sign after the search
+
+```python
+# See search described in previous sections
+items = search.item_collection()
+item = items.items[0]
+item = teledetection.sign_inplace(item)
+print(item.assets)
+```
+
+!!! Hint
+
+    `item = teledetection.sign(item)` also works.
+
+
+## Get headers
+
+For the developer it can be convenient just to grab headers (whatever the 
+authentication method is) to use them is various API endpoints.
+
+```python
+import teledetection as tld
+
+headers = tld.get_headers()
+requests.get(..., headers=headers)
+```
+
+
+## Under the hood
+
+The principle is to retrieve the signed URLs and use them to open remote
+rasters in QGIS.
+
+### Retrieve the signed URL
+
+The following code does a STAC search and displays the assets URLs:
+
+```python
+from pystac_client import Client
+from teledetection import sign_inplace
+
+api = Client.open(
+    'https://stacapi.stac.teledetection.fr', 
+    modifier=sign_inplace
+)
+res = api.search(
+    bbox=[4, 42.99, 5, 44.05], 
+    datetime=["2022-01-01", "2022-12-25"],
+    collections=["spot-6-7-drs"]
+)
+for item in res.items():
+    print(f"Links for {item.id}:")
+    print(item.assets['src_pan'].href)
+```
+
+Result has the following form: `https://minio-api-dinamis.apps.okd...?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Date=...&X-Amz-Expires=28800&X-Amz-SignedHeaders=host&X-Amz-Signature=...`
+
+### Bonus: Open COG files in QGIS
+
+To open one COG in QGIS, follow these steps:
+
+- Copy one link
+- In QGIS: *Layer* > *Add layer* > *Add raster layer*
+- In *Source type*, select *Protocol: HTTP(S), cloud, etc*
+- Paste the copied link in the *url* field
+
+You can then process the remote COGs as any raster with your favorite tool 
+from QGIS.
+
+!!! Warning
+
+    QGIS must be at least **3.18 (Firenze)** to open remote COG files
+
+!!! Hint
+
+    There is actually a simpler way to fetch our data using QGIS, check our [documentation](https://home-cdos.apps.okd.crocc.meso.umontpellier.fr/en/page/qgis/).
+
+
+
+## Environment variables
+
+- `TLD_TTL_MARGIN`: 
+Every signed URL has a TTL, returned by the signing URL API (`expiry`).
+To prevent the expiry of one signed URL during a long process, a margin of 
+1800 seconds (30 minutes) is used by default. This duration can be changed 
+setting this environment variable to a number of seconds. When one given 
+URL has to be signed again, the cached URL will not be used when the 
+previous TTL minus the margin is negative. 30 minutes should be enough 
+for most processing, however feel free to increase this value to prevent 
+your long process crashing, if it has started with one URL with a short TTL.
+
+- `TLD_URL_DURATION`: 
+Signed URLs have a default duration set by the signing API endpoint (in 
+general, a few hours). You can change the duration up to 6 days setting 
+this environment variable, in seconds.
+
+- `TLD_DISABLE_AUTH`: 
+Use this environment variable to disable authentication mechanism.
+
+- `TLD_CONFIG_DIR`: 
+The default config directory used to store authentication credentials (i.e. 
+jwt tokens and API key) is located in the user config folder (In linux: 
+`/home/user/.config/TLD_auth`). Set this environment variable to 
+set a different directory.
+
+- `TLD_ACCESS_KEY` and `TLD_SECRET_KEY` can be used to 
+set your API key from the environment.
+
+- `TLD_RETRY_TOTAL` and `TLD_RETRY_BACKOFF` can be set to 
+control the retry strategy of requests to the signing API endpoint.
+
+- `TLD_SIGNING_ENDPOINT`: use this to change the signing endpoint.

teledetection-0.1.0/doc/cli-ref.md

@@ -0,0 +1,6 @@
+# CLI reference
+
+::: mkdocs-click
+    :module: teledetection.cli
+    :command: tld
+    :depth: 1

teledetection-0.1.0/doc/credentials.md

@@ -0,0 +1,108 @@
+# Credentials
+
+There is two ways of authenticating to the MTD's CDS Geospatial data 
+infrastructure:
+
+- OAuth2
+- API key
+
+## OAuth2
+
+The credentials are retrieved using the device code flow on the first call of 
+`teledetection.sign_inplace()`. Just follow the instructions, i.e. click on the 
+HTTP link, or scan the QR-code.
+
+The credentials are valid for 5 days. Every time `teledetection.sign_inplace()` 
+is called, the credentials are renewed for another 5 days. After 5 days idle, 
+you will have to log in again.
+If you want something more persistent, or that you can use on several 
+computers, you should use an API key.
+
+## API key
+
+API key allow to sign URLs without being authenticated with the single sign on.
+Typically, you can use an API key on several machines without having to 
+authenticate each time you want to use the SDK.
+The SDK can read the API key in two ways:
+
+- From user settings file
+- From environment variables
+
+The command line interface (`teledetection`) enables to 
+manage API keys.
+
+### From user settings file
+
+Use `teledetection` to register an API key, that will be created and stored into 
+your local home directory.
+
+```commandline
+tld register
+```
+
+Typically on linux the generated API key will be stored in 
+`/home/username/.config/teledetection_auth/.apikey`.
+Optionally you can override the parent directory setting `TLD_SETTING_DIR`.
+
+Just follow the instructions to log in a single time, then the API key can be used forever on your local computer.
+You can duplicate the API key file on other computers.
+
+You can delete the registered API key with:
+
+```commandline
+tld delete
+```
+
+### From environment variables
+
+You can create a new API key with:
+
+```commandline
+tld create
+```
+
+!!! Warning
+
+    Note that once created, you won't be able to retrieve the secret key 
+    anymore. 
+
+You can then use the access and secret keys setting `TLD_ACCESS_KEY` 
+and `TLD_SECRET_KEY`. 
+
+### API key management
+
+List all generated API keys:
+
+```commandline
+tld list
+```
+
+Revoke a single API key:
+
+```commandline
+tld revoke
+```
+
+Revoke all generated API keys:
+
+```commandline
+tld revoke-all
+```
+
+## Signed URLs expiry
+
+The signed URLs for STAC objects assets are valid during 8 hours after 
+`teledetection.sign_inplace` is called. 
+
+!!! Info
+
+    `teledetection.sign_inplace()` can also be applied directly on a particular 
+    `pystac.item`, `pystac.collection`, `pystac.asset` or any URL as `str`, 
+    with the same outcome in term of expiry.
+
+!!! Warning
+
+    Do no confuse credentials validity with images URL token validity.
+    Both have different lifecycle. To read how to ask for longer 
+    URLs time-to-live, please read the API reference of 
+    `teledetection.sign_inplace()`.

teledetection-0.1.0/doc/doc_requirements.txt

@@ -0,0 +1,8 @@
+mkdocstrings
+mkdocstrings[crystal,python]
+mkdocs-click
+mkdocs-material
+mkdocs-gen-files
+mkdocs-section-index
+mkdocs-literate-nav
+mkdocs-mermaid2-plugin

teledetection-0.1.0/doc/examples/__init__.py

@@ -0,0 +1 @@
+"""Source codes of examples in [this section](#processing_examples.html)."""

teledetection-0.1.0/doc/examples/basic.md

@@ -0,0 +1,23 @@
+# Basic example
+
+The following example does a Stac search and returns usable Stac objects (Stac assets URLs are signed).
+
+```python
+from pystac_client import Client
+from teledetection import sign_inplace
+
+api = Client.open(
+    'https://stacapi.stac.teledetection.fr', 
+    modifier=sign_inplace
+)
+
+res = api.search(
+    bbox=[4, 42.99, 5, 44.05], 
+    datetime=["2022-01-01", "2022-12-25"],
+    collections=["spot-6-7-drs"]
+)
+items = search.item_collection()
+print(f"{len(items)} items found")
+item = items.items[0]
+```
+