compass-lib 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

compass_lib/__init__.py

@@ -1,5 +1,7 @@
-#!/usr/bin/env python
+# -*- coding: utf-8 -*-
 
-import importlib.metadata
+"""
+"A library to read Compass Survey files"
+"""
 
-__version__ = importlib.metadata.version("compass_lib")
+__version__ = "0.0.2"

compass_lib/commands/__init__.py

@@ -1 +0,0 @@
-#!/usr/bin/env python

compass_lib/commands/convert.py

@@ -1,4 +1,4 @@
-# #!/usr/bin/env python3
+from __future__ import annotations
 
 import argparse
 from pathlib import Path
@@ -10,22 +10,25 @@ def convert(args: list[str]) -> int:
     parser = argparse.ArgumentParser(prog="compass convert")
 
     parser.add_argument(
+        "-i",
         "--input_file",
         type=str,
         default=None,
         required=True,
-        help="Compass Survey Source File."
+        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."
+        help="Path to save the converted file at.",
     )
 
     parser.add_argument(
+        "-w",
         "--overwrite",
         action="store_true",
         help="Allow overwrite an already existing file.",
@@ -33,11 +36,12 @@ def convert(args: list[str]) -> int:
     )
 
     parser.add_argument(
+        "-f",
         "--format",
         type=str,
         choices=["json"],
         required=True,
-        help="Conversion format used."
+        help="Conversion format used.",
     )
 
     parsed_args = parser.parse_args(args)
@@ -48,9 +52,11 @@ def convert(args: list[str]) -> int:
 
     output_file = Path(parsed_args.output_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.")
+        raise FileExistsError(
+            f"The file {output_file} already existing. "
+            "Please pass the flag `--overwrite` to ignore."
+        )
 
-    parser = CompassParser(dmp_file)
-    parser.to_json(filepath=output_file)
+    survey = CompassParser.load_dat_file(dmp_file)
+    survey.to_json(filepath=output_file)
     return 0

compass_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="compass 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

compass_lib/commands/main.py

@@ -1,15 +1,17 @@
-# #!/usr/bin/env python3
+from __future__ import annotations
 
 import argparse
 from importlib.metadata import entry_points
 
 import compass_lib
 
+
 def main():
-    registered_commands = entry_points(group='compass.actions')
+    registered_commands = entry_points(group="compass.actions")
 
     parser = argparse.ArgumentParser(prog="compass_lib")
     parser.add_argument(
+        "-v",
         "--version",
         action="version",
         version=f"%(prog)s version: {compass_lib.__version__}",

compass_lib/constants.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import re
+
+from compass_lib.enums import ShotFlag
+
+# ============================== SPECIAL CHARS ============================== #
+
+COMPASS_SECTION_SEPARATOR = "\f"  # Form_feed: https://www.ascii-code.com/12
+COMPASS_END_OF_FILE = "\x1a"  # Substitute: https://www.ascii-code.com/26
+
+# ================================== REGEX ================================== #
+# Priorized regex:
+# 1. Section Split with `\r\n`
+# 2. Section Split with `\n`
+# 3. Section Split with `\f` alone
+COMPASS_SECTION_SPLIT_RE = re.compile(
+    rf"{COMPASS_SECTION_SEPARATOR}\r\n|{COMPASS_SECTION_SEPARATOR}\n|{COMPASS_SECTION_SEPARATOR}"
+)
+
+# String format:
+# - `SURVEY NAME: toc+187?`
+COMPASS_SECTION_NAME_RE = re.compile(r"SURVEY NAME:\s*(?P<section_name>\S*)")
+
+# String format:
+# - `SURVEY DATE: 1 26 86`
+# - `SURVEY DATE: 4 22 2001`
+# - `SURVEY DATE: 8 28 1988  COMMENT:Surface to shelter`
+COMPASS_DATE_COMMENT_RE = re.compile(
+    r"^SURVEY DATE:\s*(?P<date>\d{1,2}\s+\d{1,2}\s+\d{2,4}|None)(?:\s+COMMENT:\s*(?P<comment>.*))?$"  # noqa: E501
+)
+
+COMPASS_SHOT_FLAGS_RE = re.compile(
+    rf"({ShotFlag.__start_token__}"
+    rf"([{''.join(ShotFlag._value2member_map_.keys())}]*){ShotFlag.__end_token__})*(.*)"
+)

compass_lib/encoding.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import datetime
+import json
+import uuid
+from dataclasses import asdict
+from dataclasses import is_dataclass
+
+
+class EnhancedJSONEncoder(json.JSONEncoder):
+    def default(self, obj):
+        from compass_lib.parser import ShotFlag  # noqa: PLC0415
+
+        match obj:
+            case datetime.date():
+                return obj.isoformat()
+
+            case ShotFlag():
+                return obj.value
+
+            case uuid.UUID():
+                return str(obj)
+
+        if is_dataclass(obj):
+            return asdict(obj)
+
+        return super().default(obj)

compass_lib/enums.py

@@ -1,10 +1,40 @@
+from __future__ import annotations
+
 from enum import Enum
+from enum import IntEnum
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
 
 class CustomEnum(Enum):
     @classmethod
     def reverse(cls, name):
         return cls._value2member_map_[name]
 
+
+class CompassFileType(IntEnum):
+    DAT = 0
+    MAK = 1
+    PLT = 2
+
+    @classmethod
+    def from_str(cls, value: str) -> Self:
+        try:
+            return cls[value.upper()]
+        except KeyError as e:
+            raise ValueError(f"Unknown value: {value.upper()}") from e
+
+    @classmethod
+    def from_path(cls, filepath: str | Path):
+        if not isinstance(filepath, Path):
+            filepath = Path(filepath)
+
+        return cls.from_str(filepath.suffix.upper()[1:])  # Remove the leading `.`
+
+
 # ============================== Azimuth ============================== #
 
 # export const azimuthUnits: { [string]: DisplayAzimuthUnit } = {
@@ -13,11 +43,13 @@ class CustomEnum(Enum):
 #   G: 'gradians',
 # }
 
+
 class AzimuthUnits(CustomEnum):
     DEGREES = "D"
     QUADS = "Q"
     GRADIANS = "G"
 
+
 # ============================== Inclination Unit ============================== #
 
 # export const inclinationUnits: { [string]: DisplayInclinationUnit } = {
@@ -28,6 +60,7 @@ class AzimuthUnits(CustomEnum):
 #   W: 'depthGauge',
 # }
 
+
 class InclinationUnits(CustomEnum):
     DEGREES = "D"
     PERCENT_GRADE = "G"
@@ -35,6 +68,7 @@ class InclinationUnits(CustomEnum):
     GRADIANS = "R"
     DEPTH_GAUGE = "W"
 
+
 # ============================== Length Unit ============================== #
 
 
@@ -44,11 +78,13 @@ class InclinationUnits(CustomEnum):
 #   M: 'meters',
 # }
 
+
 class LengthUnits(CustomEnum):
     DECIMAL_FEET = "D"
     FEET_AND_INCHES = "I"
     METERS = "M"
 
+
 # ============================== LRUD ============================== #
 
 # export const lrudItems: { [string]: LrudItem } = {
@@ -58,12 +94,14 @@ class LengthUnits(CustomEnum):
 #   D: 'down',
 # }
 
+
 class LRUD(CustomEnum):
     LEFT = "L"
     RIGHT = "R"
     UP = "U"
     DOWN = "D"
 
+
 # ============================== ShotItem ============================== #
 
 # export const shotMeasurementItems: { [string]: ShotMeasurementItem } = {
@@ -74,6 +112,7 @@ class LRUD(CustomEnum):
 #   d: 'backsightInclination',
 # }
 
+
 class ShotItem(CustomEnum):
     LENGTH = "L"
     FRONTSIGHT_AZIMUTH = "A"
@@ -81,6 +120,7 @@ class ShotItem(CustomEnum):
     BACKSIGHT_AZIMUTH = "a"
     BACKSIGHT_INCLINATION = "d"
 
+
 # ============================== StationSide ============================== #
 
 # export const stationSides: { [string]: StationSide } = {
@@ -88,6 +128,7 @@ class ShotItem(CustomEnum):
 #   T: 'to',
 # }
 
+
 class StationSide(CustomEnum):
     FROM = "F"
     TO = "T"
@@ -95,6 +136,7 @@ class StationSide(CustomEnum):
 
 # ============================== ShotFlag ============================== #
 
+
 class ShotFlag(CustomEnum):
     EXCLUDE_PLOTING = "P"
     EXCLUDE_CLOSURE = "C"
@@ -102,11 +144,5 @@ class ShotFlag(CustomEnum):
     TOTAL_EXCLUSION = "X"
     SPLAY = "S"
 
-    __start_token__ = r"#\|"
-    __end_token__ = r"#"
-
-
-
-if __name__ == "__main__":
-    print(StationSide.FROM.value)
-    print(StationSide.reverse("F"))
+    __start_token__ = r"#\|"  # noqa: S105
+    __end_token__ = r"#"  # noqa: S105

compass_lib/models.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import datetime  # noqa: TC003
+import json
+from pathlib import Path
+from typing import Annotated
+from typing import Any
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+from pydantic import field_validator
+
+from compass_lib.encoding import EnhancedJSONEncoder
+
+# from compass_lib.errors import DuplicateValueError
+
+
+class SurveyShot(BaseModel):
+    from_id: str
+    to_id: str
+
+    azimuth: Annotated[float, Field(ge=0, lt=360)]
+
+    inclination: Annotated[float, Field(ge=-90, le=90)]
+    length: Annotated[float, Field(ge=0)]
+
+    # Optional Values
+    comment: str | None = None
+    flags: Any | None = None
+
+    azimuth2: Annotated[float, Field(ge=0, lt=360)] | None = None
+    inclination2: Annotated[float, Field(ge=-90, le=90)] | None = None
+
+    # LRUD
+    left: Annotated[float, Field(ge=0)] = 0.0
+    right: Annotated[float, Field(ge=0)] = 0.0
+    up: Annotated[float, Field(ge=0)] = 0.0
+    down: Annotated[float, Field(ge=0)] = 0.0
+
+    model_config = ConfigDict(extra="forbid")
+
+    @field_validator("left", "right", "up", "down", mode="before")
+    @classmethod
+    def validate_lrud(cls, value: float) -> float:
+        return value if value > 0 else 0.0
+
+    @field_validator("azimuth", "azimuth2", mode="before")
+    @classmethod
+    def validate_azimuth(cls, value: float) -> float:
+        return value if value > 0 else 0.0
+
+    @field_validator("inclination2", mode="before")
+    @classmethod
+    def validate_inclination2(cls, value: float) -> float:
+        return value if -90 <= value <= 90 else 0.0
+
+    # ======================== VALIDATOR UTILS ======================== #
+
+    # @classmethod
+    # def validate_unique(cls, field: str, values: list) -> list:
+    #     vals2check = [getattr(val, field) for val in values]
+    #     dupl_vals = list(duplicates(vals2check))
+    #     if dupl_vals:
+    #         raise DuplicateValueError(
+    #             f"[{cls.__name__}] Duplicate value found for `{field}`: "
+    #             f"{dupl_vals}"
+    #         )
+    #     return values
+
+    # @field_validator("to_id", mode="before")
+    # @classmethod
+    # def validate_unique_to_id(cls, value: str | None) -> str:
+    #     """Note: Validators are only ran with custom fed values.
+    #     Not autogenerated ones. Hence we need to register the name."""
+
+    #     if value is None or value == "":
+    #         return cls.to_id.default_factory()
+
+    #     # 1. Verify the name is only composed of valid chars.
+    #     for char in value:
+    #         if char.upper() not in [
+    #             *UniqueNameGenerator.VOCAB,
+    #             *list("_-~:!?.'()[]{}@*&#%|$")
+    #         ]:
+    #             raise ValueError(f"The character `{char}` is not allowed as `name`.")
+
+    #     if len(value) > COMPASS_MAX_NAME_LENGTH:
+    #         raise ValueError(f"Name {value} is too long, maximum allowed: "
+    #                          f"{COMPASS_MAX_NAME_LENGTH}")
+
+    #     UniqueNameGenerator.register(value=value)
+    #     return value
+
+
+class SurveySection(BaseModel):
+    name: str
+    comment: str
+    correction: list[float]
+    correction2: list[float]
+    survey_date: datetime.date | None = None
+    discovery_date: datetime.date | None = None
+    declination: float
+    format: str = "DDDDUDLRLADN"
+    shots: list[SurveyShot]
+    surveyors: str | None = None
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class Survey(BaseModel):
+    cave_name: str
+    description: str = ""
+
+    sections: list[SurveySection] = []
+
+    model_config = ConfigDict(extra="forbid")
+
+    def to_json(self, filepath: str | Path | None = None) -> str:
+        filepath = Path(filepath) if filepath else None
+        data = self.model_dump()
+
+        json_str = json.dumps(data, indent=4, sort_keys=True, cls=EnhancedJSONEncoder)
+
+        if filepath is not None:
+            with filepath.open(mode="w") as file:
+                file.write(json_str)
+
+        return json_str