ialirt-data-access 0.1.0__tar.gz

ialirt_data_access-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 IMAP Science Operations Center
+
+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.

ialirt_data_access-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.3
+Name: ialirt-data-access
+Version: 0.1.0
+Summary: I-ALiRT Data Access
+License: MIT
+Keywords: IMAP,SDC,SOC,SDS,Science Operations
+Author: IMAP SDC Developers
+Author-email: imap-sdc@lists.lasp.colorado.edu
+Requires-Python: >=3.9,<4
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development
+Provides-Extra: dev
+Provides-Extra: test
+Requires-Dist: pre-commit (>=3.3.3,<4.0.0) ; extra == "dev"
+Requires-Dist: pytest (>=6.2.5) ; extra == "test"
+Requires-Dist: pytest-cov (>=4.0.0,<5.0.0) ; extra == "test"
+Requires-Dist: ruff (==0.2.1) ; extra == "dev"
+Project-URL: homepage, https://github.com/IMAP-Science-Operations-Center
+Description-Content-Type: text/markdown
+
+# I-ALiRT Data Access Package
+
+This lightweight Python package allows users to query and download log data.
+
+## Command Line Utility
+
+### To install
+
+```bash
+pip install ialirt-data-access
+ialirt-data-access -h
+```
+
+### Query / Search for logs
+
+Find all files from a given year, day of year, and instance
+
+```bash
+$ ialirt_data_access --url <url> ialirt-log-query --year <year> --doy <doy> --instance <instance>
+```
+
+### Download logs
+
+Download a log and place in Downloads directory or optionally specify another local directory by appending --downloads_dir <directory> to the command
+
+```bash
+$ ialirt_data_access --url <url> ialirt-log-download ----filename <filename>
+```
+
+## Importing as a package
+
+```python
+import ialirt_data_access
+
+# Search for files
+results = ialirt_data_access.query(year="2024", doy="045", instance="1")
+```
+
+## Configuration
+
+### Data Access URL
+
+To change the default URL that the package accesses, you can set
+the environment variable ``IALIRT_DATA_ACCESS_URL`` or within the
+package ``ialirt_data_access.config["DATA_ACCESS_URL"]``. The default
+is the development server ``https://ialirt.dev.imap-mission.com``.
+
+## Troubleshooting
+
+### Network issues
+
+#### SSL
+
+If you encounter SSL errors similar to the following:
+
+```text
+urllib.error.URLError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:997)>
+```
+
+That generally means the Python environment you're using is not finding your system's root
+certificates properly. This means you need to tell Python how to find those certificates
+with the following potential solutions.
+
+1. **Upgrade the certifi package**
+
+    ```bash
+    pip install --upgrade certifi
+    ```
+
+2. **Install system certificates**
+    Depending on the Python version you installed the program with the command will look something like this:
+
+    ```bash
+    /Applications/Python\ 3.10/Install\ Certificates.command
+    ```
+
+#### HTTP Error 502: Bad Gateway
+
+This could mean that the service is temporarily down. If you
+continue to encounter this, reach out to the IMAP SDC at
+<imap-sdc@lasp.colorado.edu>.
+

ialirt_data_access-0.1.0/README.md

@@ -0,0 +1,81 @@
+# I-ALiRT Data Access Package
+
+This lightweight Python package allows users to query and download log data.
+
+## Command Line Utility
+
+### To install
+
+```bash
+pip install ialirt-data-access
+ialirt-data-access -h
+```
+
+### Query / Search for logs
+
+Find all files from a given year, day of year, and instance
+
+```bash
+$ ialirt_data_access --url <url> ialirt-log-query --year <year> --doy <doy> --instance <instance>
+```
+
+### Download logs
+
+Download a log and place in Downloads directory or optionally specify another local directory by appending --downloads_dir <directory> to the command
+
+```bash
+$ ialirt_data_access --url <url> ialirt-log-download ----filename <filename>
+```
+
+## Importing as a package
+
+```python
+import ialirt_data_access
+
+# Search for files
+results = ialirt_data_access.query(year="2024", doy="045", instance="1")
+```
+
+## Configuration
+
+### Data Access URL
+
+To change the default URL that the package accesses, you can set
+the environment variable ``IALIRT_DATA_ACCESS_URL`` or within the
+package ``ialirt_data_access.config["DATA_ACCESS_URL"]``. The default
+is the development server ``https://ialirt.dev.imap-mission.com``.
+
+## Troubleshooting
+
+### Network issues
+
+#### SSL
+
+If you encounter SSL errors similar to the following:
+
+```text
+urllib.error.URLError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:997)>
+```
+
+That generally means the Python environment you're using is not finding your system's root
+certificates properly. This means you need to tell Python how to find those certificates
+with the following potential solutions.
+
+1. **Upgrade the certifi package**
+
+    ```bash
+    pip install --upgrade certifi
+    ```
+
+2. **Install system certificates**
+    Depending on the Python version you installed the program with the command will look something like this:
+
+    ```bash
+    /Applications/Python\ 3.10/Install\ Certificates.command
+    ```
+
+#### HTTP Error 502: Bad Gateway
+
+This could mean that the service is temporarily down. If you
+continue to encounter this, reach out to the IMAP SDC at
+<imap-sdc@lasp.colorado.edu>.

ialirt_data_access-0.1.0/ialirt_data_access/__init__.py

@@ -0,0 +1,25 @@
+"""Data Access for I-ALiRT.
+
+This package contains the data access tools for the I-ALiRT logs.
+Provides a convenient way to query and download log files.
+"""
+
+import os
+
+from ialirt_data_access.io import download, query
+
+__all__ = [
+    "query",
+    "download",
+]
+__version__ = "0.1.0"
+
+
+config = {
+    "DATA_ACCESS_URL": os.getenv("IALIRT_DATA_ACCESS_URL")
+    or "https://ialirt.dev.imap-mission.com",
+}
+"""Settings configuration dictionary.
+
+DATA_ACCESS_URL : This is the URL of the data access API.
+"""

ialirt_data_access-0.1.0/ialirt_data_access/cli.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+
+"""Command line interface to query IALIRT logs in the s3 bucket.
+
+Usage:
+    ialirt_data_access --debug --url <url> ialirt-log-query
+    --year <year> --doy <doy> --instance <instance>
+"""
+
+import argparse
+import logging
+from pathlib import Path
+
+import ialirt_data_access
+
+logger = logging.getLogger(__name__)
+logging.basicConfig(level=logging.INFO)
+
+
+def _download_parser(args: argparse.Namespace):
+    """Download an I-ALiRT log.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        An object containing the parsed arguments and their values
+    """
+    try:
+        ialirt_data_access.download(args.filename, args.downloads_dir)
+    except ialirt_data_access.io.IALIRTDataAccessError as e:
+        print(e)
+
+
+def _query_parser(args: argparse.Namespace):
+    """Query the I-ALiRT log API.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments including year, doy, and instance.
+
+    Returns
+    -------
+    None
+    """
+    query_params = {
+        "year": args.year,
+        "doy": args.doy,
+        "instance": args.instance,
+    }
+    try:
+        query_results = ialirt_data_access.query(**query_params)
+        logger.info("Query results: %s", query_results)
+        print(query_results)
+    except ialirt_data_access.io.IALIRTDataAccessError as e:
+        logger.error("An error occurred: %s", e)
+        print(e)
+        return
+
+
+def main():
+    """Parse the command line arguments.
+
+    Run the command line interface to the I-ALiRT Data Access API.
+    """
+    url_help = (
+        "URL of the IALIRT API. "
+        "The default is https://ialirt.dev.imap-mission.com. This can also be "
+        "set using the IALIRT_DATA_ACCESS_URL environment variable."
+    )
+
+    parser = argparse.ArgumentParser(prog="ialirt-data-access")
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {ialirt_data_access.__version__}",
+    )
+    parser.add_argument("--url", type=str, required=False, help=url_help)
+    # Logging level
+    parser.add_argument(
+        "--vv",
+        "--debug",
+        help="Print lots of debugging statements",
+        action="store_const",
+        dest="loglevel",
+        const=logging.DEBUG,
+        default=logging.WARNING,
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        help="Add verbose output",
+        action="store_const",
+        dest="loglevel",
+        const=logging.INFO,
+    )
+
+    subparsers = parser.add_subparsers(required=True)
+
+    # Query command
+    query_parser = subparsers.add_parser("ialirt-log-query")
+    query_parser.add_argument(
+        "--year", type=str, required=True, help="Year of the logs (e.g., 2024)."
+    )
+    query_parser.add_argument(
+        "--doy", type=str, required=True, help="Day of year of the logs (e.g., 045)."
+    )
+    query_parser.add_argument(
+        "--instance",
+        type=str,
+        required=True,
+        help="Instance number (e.g., 1).",
+        choices=[
+            "1",
+            "2",
+        ],
+    )
+    query_parser.set_defaults(func=_query_parser)
+
+    # Download command
+    download_parser = subparsers.add_parser("ialirt-log-download")
+    download_parser.add_argument(
+        "--filename",
+        type=str,
+        required=True,
+        help="Example: flight_iois.log.YYYY-DOYTHH:MM:SS.ssssss",
+    )
+    download_parser.add_argument(
+        "--downloads_dir",
+        type=Path,
+        required=False,
+        help="Example: flight_iois.log.YYYY-DOYTHH:MM:SS.ssssss",
+    )
+    download_parser.set_defaults(func=_download_parser)
+
+    # Parse the arguments and set the values
+    args = parser.parse_args()
+    logging.basicConfig(level=args.loglevel)
+
+    if args.url:
+        # Explicit url from the command line
+        ialirt_data_access.config["DATA_ACCESS_URL"] = args.url
+
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

ialirt_data_access-0.1.0/ialirt_data_access/io.py

@@ -0,0 +1,147 @@
+"""The ``io`` module."""
+
+import contextlib
+import json
+import logging
+import urllib.request
+from pathlib import Path
+from typing import Optional
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+
+import ialirt_data_access
+
+logger = logging.getLogger(__name__)
+
+
+class IALIRTDataAccessError(Exception):
+    """Base class for exceptions in this module."""
+
+    pass
+
+
+@contextlib.contextmanager
+def _get_url_response(request: urllib.request.Request):
+    """Get the response from a URL request.
+
+    This is a helper function to make it easier to handle
+    the different types of errors that can occur when
+    opening a URL and write out the response body.
+    """
+    try:
+        # Open the URL and yield the response
+        with urllib.request.urlopen(request) as response:
+            yield response
+
+    except HTTPError as e:
+        message = (
+            f"HTTP Error: {e.code} - {e.reason}\n"
+            f"Server Message: {e.read().decode('utf-8')}"
+        )
+        raise IALIRTDataAccessError(message) from e
+    except URLError as e:
+        message = f"URL Error: {e.reason}"
+        raise IALIRTDataAccessError(message) from e
+
+
+def _validate_query_params(year: str, doy: str, instance: str):
+    """Validate the query parameters for the IALIRT log API.
+
+    Parameters
+    ----------
+    year : str
+        Year, must be a 4-digit string (e.g., '2024').
+    doy : str
+        Day of year, must be a string between '001' and '365'.
+    instance : str
+        Instance number, must be either '1' or '2'.
+
+    Raises
+    ------
+    ValueError
+        If any parameter is invalid.
+    """
+    if not (year.isdigit() and len(year) == 4):
+        raise ValueError("Year must be a 4-digit string (e.g., '2024').")
+    if not (doy.isdigit() and 1 <= int(doy) <= 366):
+        raise ValueError("DOY must be a string between '001' and '365'.")
+    if instance not in {"1", "2"}:
+        raise ValueError("Instance must be '1' or '2'.")
+
+
+def query(*, year: str, doy: str, instance: str) -> list[str]:
+    """Query the logs.
+
+    Parameters
+    ----------
+    year : str
+        Year
+    doy : str
+        Day of year
+    instance : str
+        Instance number
+
+    Returns
+    -------
+    list
+        List of files matching the query
+    """
+    query_params = {
+        "year": year,
+        "doy": doy,
+        "instance": instance,
+    }
+    _validate_query_params(**query_params)
+
+    url = f"{ialirt_data_access.config['DATA_ACCESS_URL']}"
+    url += f"/ialirt-log-query?{urlencode(query_params)}"
+
+    logger.info("Querying for %s with url %s", query_params, url)
+    request = urllib.request.Request(url, method="GET")
+    with _get_url_response(request) as response:
+        # Retrieve the response as a list of files
+        items = response.read().decode("utf-8")
+        logger.debug("Received response: %s", items)
+        # Decode the JSON string into a list
+        items = json.loads(items)
+        logger.debug("Decoded JSON: %s", items)
+    return items
+
+
+def download(filename: str, downloads_dir: Optional[Path] = None) -> Path:
+    """Download the logs.
+
+    Parameters
+    ----------
+    filename : str
+        Filename
+    downloads_dir : Path
+        Directory to save the file
+
+    Returns
+    -------
+    destination: pathlib.Path
+        Path to the downloaded file
+    """
+    if downloads_dir is None:
+        downloads_dir = Path.home() / "Downloads"
+
+    url = f"{ialirt_data_access.config['DATA_ACCESS_URL']}"
+    url += f"/ialirt-log-download/logs/{filename}"
+
+    downloads_dir.mkdir(parents=True, exist_ok=True)
+    destination = downloads_dir / filename
+
+    if destination.exists():
+        logger.info("File already exists: %s", destination)
+        return destination
+
+    logger.info("Downloading %s with url %s", filename, url)
+    request = urllib.request.Request(url, method="GET")
+    with _get_url_response(request) as response:
+        logger.debug("Received response: %s", response)
+        with open(destination, "wb") as local_file:
+            local_file.write(response.read())
+            print(f"Successfully downloaded the file to: {destination}")
+
+    return destination

ialirt_data_access-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "ialirt-data-access"
+version = "0.1.0"
+description = "I-ALiRT Data Access"
+authors = ["IMAP SDC Developers <imap-sdc@lists.lasp.colorado.edu>"]
+readme = "README.md"
+license = "MIT"
+keywords = ["IMAP", "SDC", "SOC", "SDS", "Science Operations"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+    "Topic :: Scientific/Engineering",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX",
+    "Operating System :: Unix",
+    "Operating System :: MacOS",
+]
+
+[tool.poetry.scripts]
+ialirt-data-access = "ialirt_data_access.cli:main"
+
+[tool.poetry.urls]
+homepage = "https://github.com/IMAP-Science-Operations-Center"
+
+[tool.poetry.dependencies]
+python = ">=3.9,<4"
+# Optional dependencies
+pre-commit = {version="^3.3.3", optional=true}
+pytest = {version=">=6.2.5", optional=true}
+pytest-cov = {version="^4.0.0", optional=true}
+ruff = {version="==0.2.1", optional=true}
+
+[tool.poetry.extras]
+dev = ["pre-commit", "ruff"]
+test = ["pytest", "pytest-cov"]
+
+[tool.pytest.ini_options]
+testpaths = [
+  "tests",
+]
+addopts = "-ra"
+
+[tool.ruff]
+target-version = "py39"
+lint.select = ["B", "E", "D", "F", "I", "N", "S", "W", "PL", "PT", "UP", "RUF"]
+# D104: Missing docstring in public package
+# D203: 1 blank line required before class docstring
+# D213: Multi-line docstring summary should start at the second line
+# D413: Missing blank line after last section
+# PLR2004: Magic value in comparison
+lint.ignore = ["D104", "D203", "D213", "D413", "PLR2004"]
+
+[tool.ruff.lint.per-file-ignores]
+# S101: Use of assert detected
+"tests/*" = ["S101"]
+# S310: Audit URL open for permitted schemes.
+"ialirt_data_access/*" = ["S310"]