xee 0.0.2__tar.gz → 0.0.4__tar.gz

xee-0.0.4/.github/workflows/ci-build.yml

@@ -0,0 +1,75 @@
+# Copyright 2023 Google LLC
+#
+# 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
+#
+#     https://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.
+# ==============================================================================
+name: ci
+
+on:
+  # Triggers the workflow on push or pull request events but only for the main branch
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: "python ${{ matrix.python-version }} tests"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [
+          "3.8",
+          "3.9",
+          "3.10",
+          "3.11",
+          "3.12",
+        ]
+    permissions:
+      id-token: write  # This is required for requesting the JWT.
+    steps:
+    - name: Cancel previous
+      uses: styfle/cancel-workflow-action@0.7.0
+      with:
+        access_token: ${{ github.token }}
+      if: ${{github.ref != 'refs/head/main'}}
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Get pip cache dir
+      id: pip-cache
+      run: |
+        python -m pip install --upgrade pip wheel
+        echo "::set-output name=dir::$(pip cache dir)"
+    - name: pip cache
+      uses: actions/cache@v2
+      with:
+        path: ${{ steps.pip-cache.outputs.dir }}
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/setup.py') }}
+    - name: Install Xee
+      run: |
+        pip install -e .[tests]
+    - uses: 'actions/checkout@v4'
+    - id: 'auth'
+      name: 'Authenticate to Google Cloud'
+      uses: 'google-github-actions/auth@v1'
+      with:
+        service_account: ${{ secrets.SERVICE_ACCOUNT }}
+        workload_identity_provider: ${{ secrets.WORKLOAD_IDENTITY_PROVIDER }}
+    - name: Run unit tests
+      run: |
+        pytest xee

xee-0.0.4/.github/workflows/lint.yml

@@ -0,0 +1,60 @@
+# Copyright 2023 Google LLC
+#
+# 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
+#
+#     https://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.
+# ==============================================================================
+name: lint
+
+on:
+  # Triggers the workflow on push or pull request events but only for the main branch
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: "python ${{ matrix.python-version }} lint"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11"]
+    steps:
+    - name: Cancel previous
+      uses: styfle/cancel-workflow-action@0.7.0
+      with:
+        access_token: ${{ github.token }}
+      if: ${{github.ref != 'refs/head/main'}}
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Get pip cache dir
+      id: pip-cache
+      run: |
+        python -m pip install --upgrade pip wheel
+        echo "::set-output name=dir::$(pip cache dir)"
+    - name: pip cache
+      uses: actions/cache@v2
+      with:
+        path: ${{ steps.pip-cache.outputs.dir }}
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/setup.py') }}
+    - name: Install Xee
+      run: |
+        pip install -e .[tests]
+    - name: Lint with pyink
+      run: |
+        pyink --check .

xee-0.0.4/.github/workflows/publish.yml

@@ -0,0 +1,95 @@
+# Copyright 2023 Google LLC
+#
+# 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
+#
+#     https://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.
+name: Publish to PyPi
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-artifacts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2.3.1
+        with:
+          python-version: 3.9
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install setuptools setuptools-scm wheel twine check-manifest
+
+      - name: Build tarball and wheels
+        run: |
+          git clean -xdf
+          git restore -SW .
+          python -m build --sdist --wheel .
+      - name: Check built artifacts
+        run: |
+          python -m twine check dist/*
+          pwd
+      - uses: actions/upload-artifact@v2
+        with:
+          name: releases
+          path: dist
+
+  test-built-dist:
+    needs: build-artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v2.3.1
+        name: Install Python
+        with:
+          python-version: 3.9
+      - uses: actions/download-artifact@v2
+        with:
+          name: releases
+          path: dist
+      - name: List contents of built dist
+        run: |
+          ls -ltrh
+          ls -ltrh dist
+      - name: Publish package to TestPyPI
+        if: github.event_name == 'push'
+        uses: pypa/gh-action-pypi-publish@v1.4.2
+        with:
+          user: __token__
+          password: ${{ secrets.TESTPYPI_TOKEN }}
+          repository_url: https://test.pypi.org/legacy/
+          verbose: true
+
+      - name: Check uploaded package
+        if: github.event_name == 'push'
+        run: |
+          sleep 3
+          python -m pip install --upgrade pip
+          python -m pip install --extra-index-url https://test.pypi.org/simple --upgrade xee
+          python -c "import xee; print(xee.__version__)"
+  upload-to-pypi:
+    needs: test-built-dist
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v2
+        with:
+          name: releases
+          path: dist
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.4.2
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_TOKEN }}
+          verbose: true

xee-0.0.4/.gitignore

@@ -0,0 +1,11 @@
+*.egg-info
+.DS_Store
+build
+dist
+docs/.ipynb_checkpoints
+docs/_build
+docs/source/_autosummary
+docs/source/.ipynb_checkpoints
+docs/*.zarr
+__pycache__
+.pytest_cache

{xee-0.0.2 → xee-0.0.4}/PKG-INFO

@@ -1,12 +1,11 @@
 Metadata-Version: 2.1
 Name: xee
-Version: 0.0.2
+Version: 0.0.4
 Summary: A Google Earth Engine extension for Xarray.
-Home-page: https://github.com/google/xee
-Author: Google LLC
-Author-email: noreply@google.com
-License: Apache 2.0
-Project-URL: Issue Tracking, https://github.com/google/Xee/issues
+Author-email: Google LLC <noreply@google.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/google/xee
+Project-URL: Issues, https://github.com/google/Xee/issues
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Developers
@@ -18,11 +17,12 @@ Classifier: Operating System :: POSIX
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
-Requires-Python: >=3.9
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: xarray
+Requires-Dist: xarray[parallel]
 Requires-Dist: earthengine-api>=0.1.374
 Requires-Dist: pyproj
 Requires-Dist: affine
@@ -121,6 +121,13 @@ ds = xarray.open_mfdataset(['ee://ECMWF/ERA5_LAND/HOURLY', 'ee://NASA/GDDP-CMIP6
                            engine='ee', crs='EPSG:4326', scale=0.25)
 ```
 
+Open a single Image by passing it to an ImageCollection:
+
+```python
+i = ee.ImageCollection(ee.Image("LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318"))
+ds = xarray.open_dataset(i, engine='ee')
+```
+
 See [examples](examples/) or [docs](docs/) for more uses and integrations.
 
 ## License

{xee-0.0.2 → xee-0.0.4}/README.md

@@ -83,6 +83,13 @@ ds = xarray.open_mfdataset(['ee://ECMWF/ERA5_LAND/HOURLY', 'ee://NASA/GDDP-CMIP6
                            engine='ee', crs='EPSG:4326', scale=0.25)
 ```
 
+Open a single Image by passing it to an ImageCollection:
+
+```python
+i = ee.ImageCollection(ee.Image("LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318"))
+ds = xarray.open_dataset(i, engine='ee')
+```
+
 See [examples](examples/) or [docs](docs/) for more uses and integrations.
 
 ## License

xee-0.0.4/conftest.py

@@ -0,0 +1,21 @@
+# Copyright 2023 Google LLC
+#
+# 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
+#
+#     https://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.
+# ==============================================================================
+"""Configure FLAGS with default values for absltest."""
+from absl import app
+
+try:
+  app.run(lambda argv: None)
+except SystemExit:
+  pass

xee-0.0.4/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

xee-0.0.4/docs/README.md

@@ -0,0 +1,34 @@
+# Xee: A Google Earth Engine extension for Xarray
+
+Xee is an Xarray extension for Google Earth Engine. It aims to help users view
+Earth Engine's [data catalog](https://developers.google.com/earth-engine/datasets)
+through the lense of arrays.
+
+In this documentation, we assume readers have some familiarity with
+[Earth Engine](https://earthengine.google.com/), [Xarray](https://xarray.dev/),
+and Python. Here, we'll dive into core concepts related to the integration
+between these tools.
+
+## Contents
+
+<!-- TODO(#38): Documentation Plan
+- Why Xee?
+- Core features
+  - `open_dataset()`
+  - `open_mfdatasets()`
+  - Projections & Geometry
+  - Xarray slicing & indexing 101
+  - Combining ee.ImageCollection and Xarray APIs.
+  - Plotting
+  - Lazy Evaluation & `load()`
+- Advanced projections
+- Performance tuning: A tale of two chunks
+- Walkthrough: calculating NDVI
+- Integration with Xarray-Beam
+- Integration with ML pipeline clients -->
+
+```{toctree}
+:maxdepth: 1
+why-xee.md
+api.md
+```

xee-0.0.4/docs/api.md

@@ -0,0 +1,25 @@
+# API docs
+
+```{eval-rst}
+.. currentmodule:: xee
+```
+
+## Core extension
+
+```{eval-rst}
+.. autosummary::
+    :toctree: _autosummary
+
+    EarthEngineBackendEntrypoint
+    EarthEngineStore
+    EarthEngineBackendArray
+```
+
+## Utility functions
+
+```{eval-rst}
+.. autosummary::
+    :toctree: _autosummary
+
+    geometry_to_bounds
+```

xee-0.0.4/docs/code-of-conduct.md

@@ -0,0 +1,93 @@
+# Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+*   Using welcoming and inclusive language
+*   Being respectful of differing viewpoints and experiences
+*   Gracefully accepting constructive criticism
+*   Focusing on what is best for the community
+*   Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+*   The use of sexualized language or imagery and unwelcome sexual attention or
+    advances
+*   Trolling, insulting/derogatory comments, and personal or political attacks
+*   Public or private harassment
+*   Publishing others' private information, such as a physical or electronic
+    address, without explicit permission
+*   Other conduct which could reasonably be considered inappropriate in a
+    professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, or to ban temporarily or permanently any
+contributor for other behaviors that they deem inappropriate, threatening,
+offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+This Code of Conduct also applies outside the project spaces when the Project
+Steward has a reasonable belief that an individual's behavior may have a
+negative impact on the project or its community.
+
+## Conflict Resolution
+
+We do not believe that all conflict is bad; healthy debate and disagreement
+often yield positive results. However, it is never okay to be disrespectful or
+to engage in behavior that violates the project’s code of conduct.
+
+If you see someone violating the code of conduct, you are encouraged to address
+the behavior directly with those involved. Many issues can be resolved quickly
+and easily, and this gives people more control over the outcome of their
+dispute. If you are unable to resolve the matter for any reason, or if the
+behavior is threatening or harassing, report it. We are dedicated to providing
+an environment where participants feel welcome and safe.
+
+Reports should be directed to *[PROJECT STEWARD NAME(s) AND EMAIL(s)]*, the
+Project Steward(s) for *[PROJECT NAME]*. It is the Project Steward’s duty to
+receive and address reported violations of the code of conduct. They will then
+work with a committee consisting of representatives from the Open Source
+Programs Office and the Google Open Source Strategy team. If for any reason you
+are uncomfortable reaching out to the Project Steward, please email
+opensource@google.com.
+
+We will investigate every complaint, but you may not receive a direct response.
+We will use our discretion in determining when and how to follow up on reported
+incidents, which may range from not taking action to permanent expulsion from
+the project and project-sponsored spaces. We will notify the accused of the
+report and provide them an opportunity to discuss it before any action is taken.
+The identity of the reporter will be omitted from the details of the report
+supplied to the accused. In potentially harmful situations, such as ongoing
+harassment or threats to anyone's safety, we may take action without notice.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
+available at
+https://www.contributor-covenant.org/version/1/4/code-of-conduct/

xee-0.0.4/docs/conf.py

@@ -0,0 +1,83 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# Print Python environment info for easier debugging on ReadTheDocs
+
+import sys
+import subprocess
+import xee  # verify this works
+
+print('python exec:', sys.executable)
+print('sys.path:', sys.path)
+print('pip environment:')
+subprocess.run([sys.executable, '-m', 'pip', 'list'])  # pylint: disable=subprocess-run-check
+
+print(f'xee: {xee.__version__}, {xee.__file__}')
+
+# -- Project information -----------------------------------------------------
+
+project = 'Xee'
+copyright = '2023, Google LCC'  # pylint: disable=redefined-builtin
+author = 'The Xee authors'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.napoleon',
+    'myst_nb',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', '_templates', 'Thumbs.db', '.DS_Store']
+
+intersphinx_mapping = {
+    'xarray': ('https://xarray.pydata.org/en/latest/', None),
+}
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# -- Extension config
+
+autosummary_generate = True
+
+# https://myst-nb.readthedocs.io/en/latest/use/execute.html
+jupyter_execute_notebooks = 'cache'
+# https://myst-nb.readthedocs.io/en/latest/use/formatting_outputs.html#removing-stdout-and-stderr
+nb_output_stderr = 'remove-warn'
+
+# https://stackoverflow.com/a/66295922/809705
+autodoc_typehints = 'description'

xee-0.0.4/docs/contributing.md

@@ -0,0 +1,32 @@
+# How to Contribute
+
+We would love to accept your patches and contributions to this project.
+
+## Before you begin
+
+### Sign our Contributor License Agreement
+
+Contributions to this project must be accompanied by a
+[Contributor License Agreement](https://cla.developers.google.com/about) (CLA).
+You (or your employer) retain the copyright to your contribution; this simply
+gives us permission to use and redistribute your contributions as part of the
+project.
+
+If you or your current employer have already signed the Google CLA (even if it
+was for a different project), you probably don't need to do it again.
+
+Visit <https://cla.developers.google.com/> to see your current agreements or to
+sign a new one.
+
+### Review our Community Guidelines
+
+This project follows [Google's Open Source Community
+Guidelines](https://opensource.google/conduct/).
+
+## Contribution process
+
+### Code Reviews
+
+All submissions, including submissions by project members, require review. We
+use [GitHub pull requests](https://docs.github.com/articles/about-pull-requests)
+for this purpose.

xee-0.0.4/docs/index.md

@@ -0,0 +1,34 @@
+# Xee: A Google Earth Engine extension for Xarray
+
+Xee is an Xarray extension for Google Earth Engine. It aims to help users view
+Earth Engine's [data catalog](https://developers.google.com/earth-engine/datasets)
+through the lense of arrays.
+
+In this documentation, we assume readers have some familiarity with
+[Earth Engine](https://earthengine.google.com/), [Xarray](https://xarray.dev/),
+and Python. Here, we'll dive into core concepts related to the integration
+between these tools.
+
+## Contents
+
+<!-- TODO(#38): Documentation Plan
+- Why Xee?
+- Core features
+  - `open_dataset()`
+  - `open_mfdatasets()`
+  - Projections & Geometry
+  - Xarray slicing & indexing 101
+  - Combining ee.ImageCollection and Xarray APIs.
+  - Plotting
+  - Lazy Evaluation & `load()`
+- Advanced projections
+- Performance tuning: A tale of two chunks
+- Walkthrough: calculating NDVI
+- Integration with Xarray-Beam
+- Integration with ML pipeline clients -->
+
+```{toctree}
+:maxdepth: 1
+why-xee.md
+api.md
+```