openspeleo-lib 0.0.12__py3-none-any.whl

openspeleo_lib/__init__.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+
+"""
+"A library to read/write and convert OpenSpeleo files"
+"""
+
+__version__ = "0.0.12"
+
+# Initialize the logger
+from openspeleo_lib import logger  # noqa: F401 # pyright: ignore[reportUnusedImport]

openspeleo_lib/commands/convert.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import pathlib
+
+import orjson
+
+from openspeleo_lib.geojson import survey_to_geojson
+from openspeleo_lib.interfaces import ArianeInterface
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+def convert(args):
+    parser = argparse.ArgumentParser(
+        prog="convert", description="Convert a Survey File"
+    )
+    parser.add_argument(
+        "-i",
+        "--input_file",
+        type=pathlib.Path,
+        required=True,
+        help="Path to the TML file to be validated",
+    )
+
+    parser.add_argument(
+        "-o",
+        "--output_file",
+        type=pathlib.Path,
+        default=None,
+        required=True,
+        help="Path to save the converted file at.",
+    )
+
+    parser.add_argument(
+        "-w",
+        "--overwrite",
+        action="store_true",
+        help="Allow overwrite an already existing file.",
+        default=False,
+    )
+
+    parser.add_argument(
+        "-b",
+        "--beautify",
+        action="store_true",
+        help="Beautify the JSON output (indent=2 and sorted).",
+        default=False,
+    )
+
+    parser.add_argument(
+        "-f",
+        "--format",
+        type=str,
+        choices=["geojson", "json"],
+        required=True,
+        help="Conversion format used.",
+    )
+
+    parsed_args = parser.parse_args(args)
+
+    input_file: pathlib.Path = parsed_args.input_file
+    output_file: pathlib.Path = parsed_args.output_file
+
+    if not input_file.exists():
+        raise FileNotFoundError(f"File not found: `{input_file}`")
+
+    if output_file.exists() and not parsed_args.overwrite:
+        raise FileExistsError(
+            f"The file `{output_file}` already existing. "
+            "Please pass the flag `--overwrite` to ignore."
+        )
+
+    match input_file.suffix:
+        case ".tml":
+            survey = ArianeInterface.from_file(input_file)
+
+        case _:
+            raise ValueError(f"Unsupported file format: `{input_file.suffix}`")
+
+    match parsed_args.format:
+        case "geojson":
+            geojson_data = survey_to_geojson(survey)
+            with output_file.open(mode="wb") as f:
+                f.write(
+                    orjson.dumps(
+                        geojson_data,
+                        None,
+                        option=(
+                            (orjson.OPT_INDENT_2 | orjson.OPT_SORT_KEYS)
+                            if parsed_args.beautify
+                            else None
+                        ),
+                    )
+                )
+
+        case "json":
+            survey.to_json(filepath=output_file, beautify=parsed_args.beautify)
+
+        case _:
+            raise ValueError(f"Unsupported conversion format: `{parsed_args.format}`")

openspeleo_lib/commands/encrypt.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+from pathlib import Path
+
+from cryptography.fernet import Fernet
+from dotenv import load_dotenv
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+def encrypt(args: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="openspeleo encrypt")
+
+    parser.add_argument(
+        "-i",
+        "--input_file",
+        type=str,
+        default=None,
+        required=True,
+        help="Compass Survey Source File.",
+    )
+
+    parser.add_argument(
+        "-o",
+        "--output_file",
+        type=str,
+        default=None,
+        required=True,
+        help="Path to save the converted file at.",
+    )
+
+    parser.add_argument(
+        "-e",
+        "--env_file",
+        type=str,
+        default=None,
+        required=True,
+        help="Path of the environment file containing the Fernet key.",
+    )
+
+    parser.add_argument(
+        "-w",
+        "--overwrite",
+        action="store_true",
+        help="Allow overwrite an already existing file.",
+        default=False,
+    )
+
+    parsed_args = parser.parse_args(args)
+
+    if not (input_file := Path(parsed_args.input_file)).exists():
+        raise FileNotFoundError(f"Impossible to find: `{input_file}`.")
+
+    if (
+        output_file := Path(parsed_args.output_file)
+    ).exists() and not parsed_args.overwrite:
+        raise FileExistsError(
+            f"The file {output_file} already existing. "
+            "Please pass the flag `--overwrite` to ignore."
+        )
+
+    if not (envfile := Path(parsed_args.env_file)).exists():
+        raise FileNotFoundError(f"Impossible to find: `{envfile}`.")
+    load_dotenv(envfile, verbose=True, override=True)
+    logger.info("Loaded environment variables from: `%s`", envfile)
+
+    if (fernet_key := os.getenv("ARTIFACT_ENCRYPTION_KEY")) is None:
+        raise ValueError(
+            "No Fernet key found in the environment file. "
+            "Check if `ARTIFACT_ENCRYPTION_KEY` is set."
+        )
+    fernet_key = Fernet(fernet_key)
+
+    with input_file.open("rb") as f:
+        clear_data = f.read()
+
+    with output_file.open("wb") as f:
+        f.write(fernet_key.encrypt(clear_data))
+
+    # Round Trip Check:
+    with output_file.open("rb") as f:
+        roundtrip_data = fernet_key.decrypt(f.read())
+        assert clear_data == roundtrip_data
+
+    return 0

openspeleo_lib/commands/main.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import argparse
+from importlib.metadata import entry_points
+
+import openspeleo_lib
+
+
+def main():
+    registered_commands = entry_points(group="openspeleo_lib.actions")
+
+    parser = argparse.ArgumentParser(prog="openspeleo_lib")
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"%(prog)s version: {openspeleo_lib.__version__}",
+    )
+    parser.add_argument(
+        "command",
+        choices=registered_commands.names,
+    )
+    parser.add_argument(
+        "args",
+        help=argparse.SUPPRESS,
+        nargs=argparse.REMAINDER,
+    )
+
+    args = argparse.Namespace()
+    parser.parse_args(namespace=args)
+
+    main_fn = registered_commands[args.command].load()
+    return main_fn(args.args)

openspeleo_lib/commands/validate_tml.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import pathlib
+
+from openspeleo_lib.interfaces import ArianeInterface
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+def validate(args):
+    parser = argparse.ArgumentParser(
+        prog="validate_tml", description="Validate a TML file"
+    )
+    parser.add_argument(
+        "-i",
+        "--input_file",
+        type=pathlib.Path,
+        required=True,
+        help="Path to the TML file to be validated",
+    )
+
+    parsed_args = parser.parse_args(args)
+
+    input_file = parsed_args.input_file
+
+    if not input_file.exists():
+        raise FileNotFoundError(f"File not found: `{input_file}`")
+
+    _ = ArianeInterface.from_file(input_file)
+
+    logger.info("Filepath: `%(input_file)s` ... VALID", {"input_file": input_file})

openspeleo_lib/constants.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+# Length for the shot field `name` used by compass
+OSPL_SHOTNAME_MAX_LENGTH = 50
+OSPL_SHOTNAME_DEFAULT_LENGTH = 6
+
+# Length for the section field `name`
+OSPL_SECTIONNAME_MAX_LENGTH = 500
+
+# Maximum retry attempts for any while loop
+OSPL_MAX_RETRY_ATTEMPTS = 100
+
+# Filenames
+ARIANE_DATA_FILENAME = "Data.xml"
+
+# GEOJSON DIGIT PRECISION
+OSPL_GEOJSON_DIGIT_PRECISION = 7

openspeleo_lib/debug_utils.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import orjson
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def write_debugdata_to_disk(data: dict, filepath: Path) -> None:
+    with filepath.open(mode="w") as f:
+        f.write(
+            orjson.dumps(
+                data, None, option=(orjson.OPT_INDENT_2 | orjson.OPT_SORT_KEYS)
+            ).decode("utf-8")
+        )

openspeleo_lib/enums.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class CustomEnum(Enum):
+    @classmethod
+    def reverse(cls, name):
+        return cls._value2member_map_[name]
+
+
+class ArianeProfileType(CustomEnum):
+    VERTICAL = "VERTICAL"
+    HORIZONTAL = "HORIZONTAL"
+    PERPENDICULAR = "PERPENDICULAR"
+    BISECTION = "BISECTION"
+
+
+class ArianeShotType(CustomEnum):
+    REAL = "REAL"
+    START = "START"
+    VIRTUAL = "VIRTUAL"
+    CLOSURE = "CLOSURE"
+
+
+class LengthUnits(CustomEnum):
+    FEET = "FT"
+    METERS = "M"

openspeleo_lib/errors.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+class DuplicateValueError(ValueError):
+    pass
+
+
+class MaxRetriesError(RuntimeError):
+    pass

openspeleo_lib/generators.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import contextlib
+import random
+from collections import defaultdict
+from typing import Any
+from typing import NewType
+
+from openspeleo_lib.constants import OSPL_MAX_RETRY_ATTEMPTS
+from openspeleo_lib.constants import OSPL_SHOTNAME_DEFAULT_LENGTH
+from openspeleo_lib.constants import OSPL_SHOTNAME_MAX_LENGTH
+from openspeleo_lib.errors import DuplicateValueError
+from openspeleo_lib.errors import MaxRetriesError
+
+
+class UniqueValueGenerator:
+    _used_values = None
+    VOCAB = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+    def __init__(self):
+        raise NotImplementedError("This class should not be instantiated.")
+
+    @classmethod
+    @contextlib.contextmanager
+    def activate_uniqueness(cls):
+        try:
+            cls._used_values = defaultdict(set)
+            yield
+        finally:
+            cls._used_values = None
+
+    @classmethod
+    def register(cls, vartype: type, value: Any) -> None:
+        """Register the generated value."""
+        if cls._used_values is None:  # uniqueness is not activated
+            return
+
+        value = vartype(value)
+
+        if value in cls._used_values[vartype]:
+            raise DuplicateValueError(
+                f"Value `{value}` for type `{vartype}` has already been registered."
+            )
+
+        cls._used_values[vartype].add(value)
+
+    @classmethod
+    def get(cls, vartype: type, **kwargs) -> Any:
+        """Get unique value for an object primary key."""
+        iter_idx = 0
+        while True:
+            iter_idx += 1
+            if iter_idx > OSPL_MAX_RETRY_ATTEMPTS:
+                raise MaxRetriesError(
+                    "Impossible to find an available value to use. "
+                    "Max retry attempts reached: "
+                    f"{OSPL_MAX_RETRY_ATTEMPTS}"
+                )
+            try:
+                if vartype is str or (
+                    isinstance(vartype, NewType) and vartype.__supertype__ is str
+                ):
+                    value = cls._generate_str(**kwargs)
+
+                elif vartype is int or (
+                    isinstance(vartype, NewType) and vartype.__supertype__ is int
+                ):
+                    value = cls._generate_int(
+                        known_values=(
+                            cls._used_values[vartype] if cls._used_values else []
+                        )
+                    )
+                else:
+                    raise TypeError(f"Unsupported type: `{vartype}`")
+
+                cls.register(vartype=vartype, value=value)
+                break
+            except DuplicateValueError:
+                continue
+
+        return value
+
+    @classmethod
+    def _generate_str(cls, str_len: int = OSPL_SHOTNAME_DEFAULT_LENGTH) -> str:
+        if str_len > OSPL_SHOTNAME_MAX_LENGTH:
+            raise ValueError(
+                f"Maximum length allowed: {OSPL_SHOTNAME_MAX_LENGTH}, received: {str_len}"  # noqa: E501
+            )
+        return "".join(random.choices(cls.VOCAB, k=str_len))
+
+    @classmethod
+    def _generate_int(cls, known_values: list[int] | set[int]) -> str:
+        return max(known_values, default=0) + 1

openspeleo_lib/geo_utils.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import datetime
+
+import pyIGRF14 as pyIGRF
+from pydantic import BaseModel
+from pydantic_extra_types.coordinate import Latitude  # noqa: TC002
+from pydantic_extra_types.coordinate import Longitude  # noqa: TC002
+
+from openspeleo_lib.constants import OSPL_GEOJSON_DIGIT_PRECISION
+
+# ruff: noqa: T201
+
+
+class GeoLocation(BaseModel):
+    latitude: Latitude
+    longitude: Longitude
+
+    def as_tuple(self) -> tuple[float, float]:
+        """Return the latitude and longitude as a tuple.
+        # RFC 7946: (longitude, latitude)
+        """
+        return (
+            round(self.longitude, OSPL_GEOJSON_DIGIT_PRECISION),
+            round(self.latitude, OSPL_GEOJSON_DIGIT_PRECISION),
+        )
+
+
+def decimal_year(dt: datetime.datetime) -> float:
+    dt_start = datetime.datetime(
+        year=dt.year, month=1, day=1, hour=0, minute=0, second=0
+    )
+    dt_end = datetime.datetime(
+        year=dt.year + 1, month=1, day=1, hour=0, minute=0, second=0
+    )
+    return round(
+        dt.year + (dt - dt_start).total_seconds() / (dt_end - dt_start).total_seconds(),
+        ndigits=2,
+    )
+
+
+def get_declination(location: GeoLocation, dt: datetime.datetime) -> float:
+    declination, _, _, _, _, _, _ = pyIGRF.igrf_value(
+        location.latitude,
+        location.longitude,
+        alt=0.0,
+        year=decimal_year(dt),
+    )
+    return round(declination, 2)
+
+
+if __name__ == "__main__":
+    dt = datetime.datetime(2025, 7, 1)
+
+    d1 = get_declination(GeoLocation(latitude=20.6296, longitude=-87.0739), dt)
+
+    print(f"pyIGRF declination : {d1:.6f}°")