nasapower-s3 1.0.0__tar.gz

nasapower_s3-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Varenya Sri Mudumba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nasapower_s3-1.0.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: nasapower-s3
+Version: 1.0.0
+Summary: A universal, secure, and fast interface for NASA POWER S3 data.
+Author-email: Varenya Sri Mudumba <srivarenya.mudumba@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Varenya Sri Mudumba
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/srivarenya01/nasapower-s3
+Project-URL: Bug Tracker, https://github.com/srivarenya01/nasapower-s3/issues
+Keywords: nasa,power,s3,zarr,meteorology,solar,climate
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: xarray
+Requires-Dist: zarr
+Requires-Dist: s3fs
+Requires-Dist: fsspec
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: codespell; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Dynamic: license-file
+
+# nasapower-s3
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+A universal, secure, and fast interface for accessing NASA POWER data directly from AWS S3 Zarr stores.
+
+## Features
+
+- **High Speed**: Access data directly from S3 using Zarr (cloud-optimized file format).
+- **Universal**: Supports Daily, Hourly, and Monthly temporal scales.
+- **Easy**: Returns standard pandas DataFrames.
+- **Secure**: No AWS credentials required (anonymous access).
+
+## Installation
+
+```bash
+pip install nasapower-s3
+```
+
+## Usage
+
+```python
+from nasapower_s3 import NasaPowerS3
+
+# Initialize client
+client = NasaPowerS3()
+
+# Fetch data (Meteorology)
+df = client.get_data(
+    lat=30.6,
+    lon=-96.3,
+    start_date="2023-01-01",
+    end_date="2023-01-10",
+    variables=["T2M", "PRECTOTCORR"],
+    frequency="daily",
+    collection="meteorology"  # Default
+)
+
+# Fetch Solar data
+df_solar = client.get_data(
+    lat=30.6,
+    lon=-96.3,
+    start_date="2023-01-01",
+    end_date="2023-01-10",
+    variables=["ALLSKY_SFC_SW_DWN"],
+    frequency="daily",
+    collection="solar"
+)
+
+print(df.head())
+```
+
+## Available Data
+
+The library supports:
+- **Collections**: `meteorology` (MERRA-2) and `solar` (SRB)
+- **Frequencies**: `daily`, `hourly`, `monthly`, `climatology`
+
+For a full list of variables, refer to the [NASA POWER API Docs](https://power.larc.nasa.gov/docs/services/api/).
+
+## Data License & Attribution
+
+The code in this repository is licensed under **MIT**.
+The data accessed from NASA POWER is licensed under **Creative Commons Attribution 4.0 International (CC BY 4.0)**.
+
+**Attribution**:
+> "These data were obtained from the NASA Langley Research Center POWER Project funded through the NASA Earth Science Directorate Applied Science Program."
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+1. Fork the repo
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.

nasapower_s3-1.0.0/README.md

@@ -0,0 +1,82 @@
+# nasapower-s3
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+A universal, secure, and fast interface for accessing NASA POWER data directly from AWS S3 Zarr stores.
+
+## Features
+
+- **High Speed**: Access data directly from S3 using Zarr (cloud-optimized file format).
+- **Universal**: Supports Daily, Hourly, and Monthly temporal scales.
+- **Easy**: Returns standard pandas DataFrames.
+- **Secure**: No AWS credentials required (anonymous access).
+
+## Installation
+
+```bash
+pip install nasapower-s3
+```
+
+## Usage
+
+```python
+from nasapower_s3 import NasaPowerS3
+
+# Initialize client
+client = NasaPowerS3()
+
+# Fetch data (Meteorology)
+df = client.get_data(
+    lat=30.6,
+    lon=-96.3,
+    start_date="2023-01-01",
+    end_date="2023-01-10",
+    variables=["T2M", "PRECTOTCORR"],
+    frequency="daily",
+    collection="meteorology"  # Default
+)
+
+# Fetch Solar data
+df_solar = client.get_data(
+    lat=30.6,
+    lon=-96.3,
+    start_date="2023-01-01",
+    end_date="2023-01-10",
+    variables=["ALLSKY_SFC_SW_DWN"],
+    frequency="daily",
+    collection="solar"
+)
+
+print(df.head())
+```
+
+## Available Data
+
+The library supports:
+- **Collections**: `meteorology` (MERRA-2) and `solar` (SRB)
+- **Frequencies**: `daily`, `hourly`, `monthly`, `climatology`
+
+For a full list of variables, refer to the [NASA POWER API Docs](https://power.larc.nasa.gov/docs/services/api/).
+
+## Data License & Attribution
+
+The code in this repository is licensed under **MIT**.
+The data accessed from NASA POWER is licensed under **Creative Commons Attribution 4.0 International (CC BY 4.0)**.
+
+**Attribution**:
+> "These data were obtained from the NASA Langley Research Center POWER Project funded through the NASA Earth Science Directorate Applied Science Program."
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+1. Fork the repo
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.

nasapower_s3-1.0.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nasapower-s3"
+version = "1.0.0"
+description = "A universal, secure, and fast interface for NASA POWER S3 data."
+readme = "README.md"
+authors = [
+  { name = "Varenya Sri Mudumba", email = "srivarenya.mudumba@gmail.com"},
+]
+license = { file = "LICENSE" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+keywords = ["nasa", "power", "s3", "zarr", "meteorology", "solar", "climate"]
+requires-python = ">=3.8"
+dependencies = [
+    "pandas",
+    "xarray",
+    "zarr",
+    "s3fs",
+    "fsspec",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/srivarenya01/nasapower-s3"
+"Bug Tracker" = "https://github.com/srivarenya01/nasapower-s3/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "black",
+    "isort",
+    "codespell",
+    "pre-commit",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.isort]
+profile = "black"
+
+[tool.codespell]
+skip = "*.lock,*.zarr,.git,__pycache__"
+ignore-words-list = "fsspec"
+
+[tool.pytest.ini_options]
+markers = [
+    "integration: marks tests that require network access to S3 (deselect with '-m not integration')",
+]
+testpaths = ["tests"]

nasapower_s3-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nasapower_s3-1.0.0/src/nasapower_s3/__init__.py

@@ -0,0 +1,19 @@
+from .client import NasaPowerS3
+from .exceptions import (
+    DataAccessError,
+    InvalidCoordinateError,
+    InvalidFrequencyError,
+    NasaPowerError,
+    VariableNotFoundError,
+)
+
+__all__ = [
+    "NasaPowerS3",
+    "NasaPowerError",
+    "InvalidCoordinateError",
+    "InvalidFrequencyError",
+    "VariableNotFoundError",
+    "DataAccessError",
+]
+
+__version__ = "1.0.0"

nasapower_s3-1.0.0/src/nasapower_s3/client.py

@@ -0,0 +1,149 @@
+import logging
+from typing import Dict, List, Optional, Union
+
+import fsspec
+import pandas as pd
+import xarray as xr
+
+from .constants import BUCKETS as DEFAULT_BUCKETS
+from .exceptions import DataAccessError, VariableNotFoundError
+from .validators import validate_coordinates, validate_frequency
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+
+class NasaPowerS3:
+    """
+    A secure, high-speed interface for NASA POWER data via AWS S3.
+    """
+
+    def __init__(self):
+        """Initialize the NASA POWER S3 client."""
+        # Create a local copy of buckets to avoid global state mutation
+        self._buckets = DEFAULT_BUCKETS.copy()
+
+    def update_buckets(
+        self, collection: str, frequency: Optional[str] = None, url: Optional[str] = None
+    ) -> None:
+        """
+        Update or add a BUCKET mapping for this client instance.
+
+        Args:
+            collection: Collection name (e.g., "meteorology", "solar")
+            frequency: Optional specific frequency name (e.g., "daily"). 
+                       If None, the url is treated as a template.
+            url: Valid S3 Zarr store URL or template with {freq}
+        """
+        if frequency is None:
+            # Treat url as a template for all frequencies in this collection
+            self._buckets[collection] = url
+        else:
+            # Add/Update a specific frequency override
+            if collection not in self._buckets or isinstance(self._buckets[collection], str):
+                self._buckets[collection] = {}
+            self._buckets[collection][frequency] = url
+        
+        logger.info(f"Updated bucket mapping for collection '{collection}'")
+
+    def get_data(
+        self,
+        lat: float,
+        lon: float,
+        start_date: str,
+        end_date: str,
+        variables: List[str],
+        frequency: str = "daily",
+        collection: str = "meteorology",
+    ) -> pd.DataFrame:
+        """
+        Fetch data from NASA POWER S3 Zarr store.
+
+        Args:
+            lat: Latitude (-90 to 90)
+            lon: Longitude (-180 to 180)
+            start_date: Start date (YYYY-MM-DD or YYYY-MM-DDTHH:MM)
+            end_date: End date (YYYY-MM-DD or YYYY-MM-DDTHH:MM)
+            variables: List of variable names to fetch (e.g., ["T2M", "PRECTOTCORR"])
+            frequency: Data frequency ("daily", "hourly", "monthly")
+            collection: Data collection ("meteorology" or "solar"). Defaults to "meteorology".
+
+        Returns:
+            pd.DataFrame: DataFrame containing the requested data.
+
+        Raises:
+            InvalidCoordinateError: If coordinates are invalid.
+            InvalidFrequencyError: If frequency is not supported.
+            VariableNotFoundError: If a variable is not found.
+            DataAccessError: If there is an error accessing S3.
+        """
+        # Validate inputs
+        validate_coordinates(lat, lon)
+        validate_frequency(frequency)
+
+        ds = None
+        try:
+            # Get the URL/template for this collection
+            bucket_info = self._buckets.get(collection)
+            if not bucket_info:
+                raise ValueError(
+                    f"Invalid collection: '{collection}'. Supported: {list(self._buckets.keys())}"
+                )
+            
+            # Resolve the URL
+            if isinstance(bucket_info, str):
+                # It's a template
+                url = bucket_info.format(freq=frequency)
+            elif isinstance(bucket_info, dict):
+                # It's a dictionary of frequency-specific URLs
+                url = bucket_info.get(frequency)
+                if not url:
+                    raise DataAccessError(
+                        f"Frequency '{frequency}' is not mapped for collection '{collection}'."
+                    )
+            else:
+                raise DataAccessError(f"Malformed bucket configuration for '{collection}'")
+
+            logger.info(f"Connecting to NASA POWER S3: {url} (anonymous access)")
+            store = fsspec.get_mapper(url, anon=True)
+            ds = xr.open_zarr(store, consolidated=True)
+            
+            # Check if variables exist in dataset
+            missing_vars = [v for v in variables if v not in ds.data_vars]
+            if missing_vars:
+                raise VariableNotFoundError(
+                    f"Variables not found in {frequency} dataset: {missing_vars}"
+                )
+
+            logger.debug(f"Subsetting data for {lat}, {lon} from {start_date} to {end_date}")
+            # Subset data - select nearest lat/lon first, then slice time
+            subset = ds[variables].sel(
+                lat=lat,
+                lon=lon,
+                method="nearest",
+            ).sel(
+                time=slice(start_date, end_date)
+            )
+
+            # Convert to Pandas
+            df = subset.to_dataframe().reset_index()
+            return df
+
+        except (ValueError, VariableNotFoundError) as e:
+            # Re-raise validation or specific business logic errors
+            raise
+        except Exception as e:
+            # Distinguish between connection errors and processing errors
+            err_str = str(e).lower()
+            if "keyerror" in err_str or "404" in err_str or "nosuchkey" in err_str:
+                msg = (f"Frequency '{frequency}' may not be available for collection '{collection}'. "
+                       f"Attempted to access: {url if 'url' in locals() else 'Unknown'}")
+                logger.error(msg)
+                raise DataAccessError(msg) from e
+            
+            msg = f"Error accessing/processing NASA POWER S3 data: {e}"
+            logger.error(msg)
+            raise DataAccessError(msg) from e
+        finally:
+            if ds is not None:
+                ds.close()

nasapower_s3-1.0.0/src/nasapower_s3/constants.py

@@ -0,0 +1,43 @@
+"""
+Constants and mappings for NASA POWER S3 Zarr stores.
+"""
+
+# Zarr store URLs
+# Zarr store URLs
+# Structure matches S3: s3://nasa-power/{collection}/temporal/power_{collection}_{freq}_temporal_utc.zarr
+BUCKETS = {
+    "meteorology": "s3://nasa-power/merra2/temporal/power_merra2_{freq}_temporal_utc.zarr",
+    "solar": "s3://nasa-power/srb/temporal/power_srb_{freq}_temporal_utc.zarr",
+}
+
+# Coordinate boundaries
+MIN_LAT = -90.0
+MAX_LAT = 90.0
+MIN_LON = -180.0
+MAX_LON = 180.0
+
+# Supported frequencies
+FREQUENCIES = ["daily", "hourly", "monthly", "climatology", "annual"]
+
+
+# Common variables default collection map
+# If a variable is in this list, we can guess the collection.
+# Solar variables often start with ALLSKY, CLR, TOA, SZA
+# Meteorology variables are often T2M, PRECTOT, RH, WS
+VARIABLE_COLLECTION_MAP = {
+    # Default Meteorology (MERRA-2)
+    "T2M": "meteorology",
+    "T2M_MAX": "meteorology",
+    "T2M_MIN": "meteorology",
+    "PRECTOTCORR": "meteorology",
+    "RH2M": "meteorology",
+    "WS10M": "meteorology",
+    "PS": "meteorology",
+    
+    # Default Solar (SRB)
+    "ALLSKY_SFC_SW_DWN": "solar",
+    "CLR_SFC_SW_DWN": "solar",
+    "ALLSKY_KT": "solar",
+    "ALLSKY_SFC_LW_DWN": "solar",
+    "TOA_SW_DWN": "solar",
+}

nasapower_s3-1.0.0/src/nasapower_s3/exceptions.py

@@ -0,0 +1,23 @@
+class NasaPowerError(Exception):
+    """Base exception for NASA POWER library."""
+    pass
+
+
+class InvalidCoordinateError(NasaPowerError):
+    """Raised when coordinates are out of valid range."""
+    pass
+
+
+class InvalidFrequencyError(NasaPowerError):
+    """Raised when an invalid frequency is requested."""
+    pass
+
+
+class VariableNotFoundError(NasaPowerError):
+    """Raised when a requested variable is not found in the dataset."""
+    pass
+
+
+class DataAccessError(NasaPowerError):
+    """Raised when there is an issue accessing the data source."""
+    pass

nasapower_s3-1.0.0/src/nasapower_s3/validators.py

@@ -0,0 +1,44 @@
+"""
+Input validation utilities.
+"""
+from typing import Union
+
+from .constants import FREQUENCIES, MAX_LAT, MAX_LON, MIN_LAT, MIN_LON
+from .exceptions import InvalidCoordinateError, InvalidFrequencyError
+
+
+def validate_coordinates(lat: float, lon: float) -> None:
+    """
+    Validate latitude and longitude.
+    
+    Args:
+        lat: Latitude (-90 to 90)
+        lon: Longitude (-180 to 180)
+        
+    Raises:
+        InvalidCoordinateError: If coordinates are out of bounds.
+    """
+    if not (MIN_LAT <= lat <= MAX_LAT):
+        raise InvalidCoordinateError(
+            f"Invalid Latitude: {lat}. Must be between {MIN_LAT} and {MAX_LAT}."
+        )
+    if not (MIN_LON <= lon <= MAX_LON):
+        raise InvalidCoordinateError(
+            f"Invalid Longitude: {lon}. Must be between {MIN_LON} and {MAX_LON}."
+        )
+
+
+def validate_frequency(frequency: str) -> None:
+    """
+    Validate data frequency.
+
+    Args:
+        frequency: Data frequency string (e.g., 'daily', 'hourly')
+
+    Raises:
+        InvalidFrequencyError: If frequency is not supported.
+    """
+    if frequency not in FREQUENCIES:
+        raise InvalidFrequencyError(
+            f"Invalid frequency: '{frequency}'. Supported values: {FREQUENCIES}"
+        )

nasapower_s3-1.0.0/src/nasapower_s3.egg-info/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: nasapower-s3
+Version: 1.0.0
+Summary: A universal, secure, and fast interface for NASA POWER S3 data.
+Author-email: Varenya Sri Mudumba <srivarenya.mudumba@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Varenya Sri Mudumba
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/srivarenya01/nasapower-s3
+Project-URL: Bug Tracker, https://github.com/srivarenya01/nasapower-s3/issues
+Keywords: nasa,power,s3,zarr,meteorology,solar,climate
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: xarray
+Requires-Dist: zarr
+Requires-Dist: s3fs
+Requires-Dist: fsspec
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: codespell; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Dynamic: license-file
+
+# nasapower-s3
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+A universal, secure, and fast interface for accessing NASA POWER data directly from AWS S3 Zarr stores.
+
+## Features
+
+- **High Speed**: Access data directly from S3 using Zarr (cloud-optimized file format).
+- **Universal**: Supports Daily, Hourly, and Monthly temporal scales.
+- **Easy**: Returns standard pandas DataFrames.
+- **Secure**: No AWS credentials required (anonymous access).
+
+## Installation
+
+```bash
+pip install nasapower-s3
+```
+
+## Usage
+
+```python
+from nasapower_s3 import NasaPowerS3
+
+# Initialize client
+client = NasaPowerS3()
+
+# Fetch data (Meteorology)
+df = client.get_data(
+    lat=30.6,
+    lon=-96.3,
+    start_date="2023-01-01",
+    end_date="2023-01-10",
+    variables=["T2M", "PRECTOTCORR"],
+    frequency="daily",
+    collection="meteorology"  # Default
+)
+
+# Fetch Solar data
+df_solar = client.get_data(
+    lat=30.6,
+    lon=-96.3,
+    start_date="2023-01-01",
+    end_date="2023-01-10",
+    variables=["ALLSKY_SFC_SW_DWN"],
+    frequency="daily",
+    collection="solar"
+)
+
+print(df.head())
+```
+
+## Available Data
+
+The library supports:
+- **Collections**: `meteorology` (MERRA-2) and `solar` (SRB)
+- **Frequencies**: `daily`, `hourly`, `monthly`, `climatology`
+
+For a full list of variables, refer to the [NASA POWER API Docs](https://power.larc.nasa.gov/docs/services/api/).
+
+## Data License & Attribution
+
+The code in this repository is licensed under **MIT**.
+The data accessed from NASA POWER is licensed under **Creative Commons Attribution 4.0 International (CC BY 4.0)**.
+
+**Attribution**:
+> "These data were obtained from the NASA Langley Research Center POWER Project funded through the NASA Earth Science Directorate Applied Science Program."
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+1. Fork the repo
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.

nasapower_s3-1.0.0/src/nasapower_s3.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/nasapower_s3/__init__.py
+src/nasapower_s3/client.py
+src/nasapower_s3/constants.py
+src/nasapower_s3/exceptions.py
+src/nasapower_s3/validators.py
+src/nasapower_s3.egg-info/PKG-INFO
+src/nasapower_s3.egg-info/SOURCES.txt
+src/nasapower_s3.egg-info/dependency_links.txt
+src/nasapower_s3.egg-info/requires.txt
+src/nasapower_s3.egg-info/top_level.txt
+tests/test_nasapower.py

nasapower_s3-1.0.0/src/nasapower_s3.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nasapower_s3-1.0.0/src/nasapower_s3.egg-info/requires.txt

@@ -0,0 +1,13 @@
+pandas
+xarray
+zarr
+s3fs
+fsspec
+
+[dev]
+pytest
+pytest-cov
+black
+isort
+codespell
+pre-commit

nasapower_s3-1.0.0/src/nasapower_s3.egg-info/top_level.txt

@@ -0,0 +1 @@
+nasapower_s3

nasapower_s3-1.0.0/tests/test_nasapower.py

@@ -0,0 +1,152 @@
+"""
+Tests for the nasapower-s3 library.
+"""
+import pytest
+from unittest.mock import Mock, patch, MagicMock
+import pandas as pd
+import numpy as np
+
+from nasapower_s3 import NasaPowerS3
+from nasapower_s3.validators import validate_coordinates, validate_frequency
+from nasapower_s3.exceptions import (
+    InvalidCoordinateError,
+    InvalidFrequencyError,
+    VariableNotFoundError,
+    DataAccessError,
+)
+
+
+class TestValidators:
+    """Test input validation functions."""
+
+    def test_valid_coordinates(self):
+        """Valid coordinates should not raise."""
+        validate_coordinates(0, 0)
+        validate_coordinates(90, 180)
+        validate_coordinates(-90, -180)
+        validate_coordinates(30.6, -96.3)
+
+    def test_invalid_latitude(self):
+        """Latitude out of range should raise InvalidCoordinateError."""
+        with pytest.raises(InvalidCoordinateError):
+            validate_coordinates(91, 0)
+        with pytest.raises(InvalidCoordinateError):
+            validate_coordinates(-91, 0)
+
+    def test_invalid_longitude(self):
+        """Longitude out of range should raise InvalidCoordinateError."""
+        with pytest.raises(InvalidCoordinateError):
+            validate_coordinates(0, 181)
+        with pytest.raises(InvalidCoordinateError):
+            validate_coordinates(0, -181)
+
+    def test_valid_frequency(self):
+        """Valid frequencies should not raise."""
+        validate_frequency("daily")
+        validate_frequency("hourly")
+        validate_frequency("monthly")
+
+    def test_invalid_frequency(self):
+        """Invalid frequency should raise InvalidFrequencyError."""
+        with pytest.raises(InvalidFrequencyError):
+            validate_frequency("weekly")
+        with pytest.raises(InvalidFrequencyError):
+            validate_frequency("invalid")
+
+
+class TestNasaPowerS3Client:
+    """Test the main NasaPowerS3 client."""
+
+    def test_client_initialization(self):
+        """Client should initialize without errors."""
+        client = NasaPowerS3()
+        assert client is not None
+
+    def test_invalid_collection(self):
+        """Invalid collection should raise DataAccessError."""
+        client = NasaPowerS3()
+        with pytest.raises((ValueError, DataAccessError)):
+            client.get_data(
+                lat=30.6,
+                lon=-96.3,
+                start_date="2023-01-01",
+                end_date="2023-01-10",
+                variables=["T2M"],
+                collection="invalid_collection",
+            )
+
+    @pytest.mark.integration
+    def test_real_data_fetch(self):
+        """Integration test: Fetch real data from S3."""
+        client = NasaPowerS3()
+        df = client.get_data(
+            lat=30.6,
+            lon=-96.3,
+            start_date="2023-01-01",
+            end_date="2023-01-05",
+            variables=["T2M"],
+            frequency="daily",
+            collection="meteorology",
+        )
+        
+        # Verify structure
+        assert isinstance(df, pd.DataFrame)
+        assert len(df) == 5  # 5 days
+        assert "T2M" in df.columns
+        assert "time" in df.columns
+        assert "lat" in df.columns
+        assert "lon" in df.columns
+        
+        # Verify data types
+        assert df["T2M"].dtype in [np.float32, np.float64]
+
+
+    def test_update_buckets_template(self):
+        """Test updating a collection with a new template."""
+        client = NasaPowerS3()
+        new_template = "s3://new-bucket/power_{freq}.zarr"
+        client.update_buckets("new_collection", url=new_template)
+        
+        # We can't easily fetch from a fake S3 URL without more mocking,
+        # but we can verify the internal state.
+        assert client._buckets["new_collection"] == new_template
+        
+    def test_update_buckets_override(self):
+        """Test updating a specific frequency override."""
+        client = NasaPowerS3()
+        client.update_buckets("meteorology", frequency="daily", url="s3://custom-daily.zarr")
+        
+        assert isinstance(client._buckets["meteorology"], dict)
+        assert client._buckets["meteorology"]["daily"] == "s3://custom-daily.zarr"
+
+    def test_instance_isolation(self):
+        """Test that updating one client doesn't affect another."""
+        client1 = NasaPowerS3()
+        client2 = NasaPowerS3()
+        
+        client1.update_buckets("meteorology", frequency="daily", url="s3://custom-daily.zarr")
+        
+        # client1 should be updated
+        assert isinstance(client1._buckets["meteorology"], dict)
+        # client2 should still have the default template string
+        assert isinstance(client2._buckets["meteorology"], str)
+        assert "{freq}" in client2._buckets["meteorology"]
+
+
+class TestExceptions:
+    """Test custom exception classes."""
+
+    def test_invalid_coordinate_error(self):
+        """InvalidCoordinateError should be raisable with message."""
+        with pytest.raises(InvalidCoordinateError, match="test message"):
+            raise InvalidCoordinateError("test message")
+
+    def test_variable_not_found_error(self):
+        """VariableNotFoundError should be raisable."""
+        with pytest.raises(VariableNotFoundError):
+            raise VariableNotFoundError("Variable XYZ not found")
+
+    def test_data_access_error(self):
+        """DataAccessError should be raisable."""
+        with pytest.raises(DataAccessError):
+            raise DataAccessError("S3 connection failed")