canvod-filemap 1.0.0__py3-none-any.whl

canvod/filemap/__init__.py

@@ -0,0 +1,38 @@
+"""canvod-filemap: naming recipes for non-canonical GNSS filenames."""
+
+from importlib.metadata import version
+
+__version__ = version("canvod-filemap")
+
+from .mapping import VirtualFile
+from .recipe import NamingRecipe, recipe_sha256
+from .recipe_files import (
+    RecipeNotFoundError,
+    create_recipe,
+    find_recipe,
+    recipe_path,
+)
+from .remote import (
+    RecipeFetchError,
+    RecipeURLError,
+    RemoteRecipeError,
+    check_recipe_url,
+    fetch_recipe,
+    is_recipe_url,
+)
+
+__all__ = [
+    "NamingRecipe",
+    "RecipeFetchError",
+    "RecipeNotFoundError",
+    "RecipeURLError",
+    "RemoteRecipeError",
+    "VirtualFile",
+    "check_recipe_url",
+    "create_recipe",
+    "fetch_recipe",
+    "find_recipe",
+    "is_recipe_url",
+    "recipe_path",
+    "recipe_sha256",
+]

canvod/filemap/mapping.py

@@ -0,0 +1,28 @@
+"""``VirtualFile``: a physical file paired with its canVOD conventional name.
+
+``NamingRecipe.to_virtual_file`` returns it; the file on disk keeps its name.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from canvod.preflight.convention import CanVODFilename
+
+
+@dataclass(frozen=True)
+class VirtualFile:
+    """Physical file mapped to its canVOD conventional name."""
+
+    physical_path: Path
+    conventional_name: CanVODFilename
+
+    @property
+    def canonical_str(self) -> str:
+        """The conventional filename as a string."""
+        return self.conventional_name.name
+
+    def open(self, mode: str = "rb"):
+        """Open the physical file."""
+        return self.physical_path.open(mode)

canvod/filemap/patterns.py

@@ -0,0 +1,28 @@
+"""Helpers for the date and time fields of non-canonical filenames."""
+
+from __future__ import annotations
+
+# RINEX v2 hour letter: a-x = 0-23
+_HOUR_LETTER_MAP: dict[str, int] = {chr(ord("a") + h): h for h in range(24)}
+_HOUR_LETTER_MAP["0"] = 0  # '0' also means hour 0
+
+
+def hour_letter_to_int(letter: str) -> int:
+    """Convert a RINEX hour letter (a-x or '0') to an integer 0-23.
+
+    Raises
+    ------
+    ValueError
+        If the letter is not a valid RINEX hour code.
+    """
+    try:
+        return _HOUR_LETTER_MAP[letter.lower()]
+    except KeyError:
+        raise ValueError(f"Invalid hour letter: {letter!r}") from None
+
+
+def resolve_year_from_yy(yy: int) -> int:
+    """Expand a 2-digit year to 4 digits (80-99 → 1980-1999, 00-79 → 2000-2079)."""
+    if yy >= 80:
+        return 1900 + yy
+    return 2000 + yy

canvod/filemap/recipe.py

@@ -0,0 +1,387 @@
+"""Naming recipe: user-defined mapping from arbitrary filenames to canVOD names.
+
+A recipe is a small YAML file that describes:
+1. The canonical identity of a receiver (site, agency, sampling, etc.)
+2. How to extract date/time fields from the user's physical filenames.
+
+The field extraction is a sequential left-to-right walk over the filename.
+Each entry in the ``fields`` list consumes characters and either extracts
+a named value or skips literal characters.
+
+Recognized field names
+----------------------
+- ``year``         4-digit year (e.g. 2025)
+- ``yy``           2-digit year (80-99 → 19xx, 00-79 → 20xx)
+- ``doy``          day of year (1-366)
+- ``month``        month (01-12)
+- ``day``          day of month (01-31)
+- ``hour``         hour (00-23)
+- ``minute``       minute (00-59)
+- ``hour_letter``  RINEX 2 session letter (a-x = hours 0-23; 0 = daily file)
+- ``skip``         ignore these characters
+
+Example recipe (YAML)
+---------------------
+::
+
+    name: fangorn_reference
+    description: Orthanc, reference receiver
+
+    site: FAN
+    agency: INK
+    receiver_number: 1
+    receiver_type: reference
+    sampling: "05S"
+    period: "15M"
+    content: "AA"
+    file_type: rnx
+
+    glob: "*.??o"
+
+    # Example: rref001a15.25o
+    fields:
+      - skip: 4
+      - doy: 3
+      - hour_letter: 1
+      - minute: 2
+      - skip: 1
+      - yy: 2
+      - skip: 1
+
+Example recipe for exotic filenames
+------------------------------------
+::
+
+    # Example: STATION_2025_042_00_15.rinex
+    fields:
+      - skip: 8
+      - year: 4
+      - skip: 1
+      - doy: 3
+      - skip: 1
+      - hour: 2
+      - skip: 1
+      - minute: 2
+      - skip: 6
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from canvod.preflight.convention import (
+    AgencyId,
+    CanVODFilename,
+    ContentCode,
+    Duration,
+    FileType,
+    ReceiverType,
+    SiteId,
+)
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from .mapping import VirtualFile
+from .patterns import hour_letter_to_int, resolve_year_from_yy
+
+# Field names the parser understands
+KNOWN_FIELDS = frozenset(
+    {
+        "year",
+        "yy",
+        "doy",
+        "month",
+        "day",
+        "hour",
+        "minute",
+        "hour_letter",
+        "skip",
+    }
+)
+
+
+class NamingRecipe(BaseModel):
+    """A user-defined mapping from arbitrary filenames to canVOD names.
+
+    Serialize to YAML for sharing, to JSON for API transport. Fields it
+    does not know are ignored; :meth:`unrecognized_fields` names them.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    name: str = Field(description="Recipe identifier (e.g. 'fangorn_reference')")
+    description: str = ""
+
+    # Canonical identity
+    site: SiteId
+    agency: AgencyId
+    receiver_number: int = Field(ge=1, le=99)
+    receiver_type: Literal["reference", "canopy"] = "canopy"
+    sampling: Duration = "05S"
+    period: Duration = "15M"
+    content: ContentCode = "AA"
+    file_type: Literal["rnx", "sbf", "ubx", "nmea"] = "rnx"
+
+    # File discovery
+    glob: str = Field(description="Glob pattern to find files (e.g. '*.??o', '*.rinex')")
+
+    # Field extraction: sequential left-to-right
+    # Each entry is a single-key dict: {field_name: width}
+    fields: list[dict[str, int]] = Field(
+        description="Sequential field extraction. Each entry: {field_name: width}"
+    )
+
+    @model_validator(mode="after")
+    def _validate_fields(self) -> NamingRecipe:
+        for i, entry in enumerate(self.fields):
+            if len(entry) != 1:
+                msg = f"fields[{i}]: each entry must be a single key-value pair, got {entry}"
+                raise ValueError(msg)
+            field_name = next(iter(entry))
+            width = entry[field_name]
+            if field_name not in KNOWN_FIELDS:
+                msg = f"fields[{i}]: unknown field '{field_name}'. Known: {sorted(KNOWN_FIELDS)}"
+                raise ValueError(msg)
+            if not isinstance(width, int) or width < 1:
+                msg = f"fields[{i}]: width must be a positive integer, got {width}"
+                raise ValueError(msg)
+        return self
+
+    # -- Parsing ---------------------------------------------------------------
+
+    def parse_filename(self, filename: str) -> dict[str, str | int]:
+        """Extract fields from a physical filename.
+
+        Parameters
+        ----------
+        filename
+            Bare filename (no directory components).
+
+        Returns
+        -------
+        dict
+            Extracted field values. Integer fields (year, doy, etc.) are
+            returned as ``int``.  ``hour_letter`` is returned as ``str``.
+            ``skip`` fields are not included.
+
+        Raises
+        ------
+        ValueError
+            If the filename is too short for the field spec.
+        """
+        pos = 0
+        result: dict[str, str | int] = {}
+
+        for entry in self.fields:
+            field_name = next(iter(entry))
+            width = entry[field_name]
+
+            if pos + width > len(filename):
+                msg = (
+                    f"Filename {filename!r} too short: need {width} chars "
+                    f"at position {pos} for '{field_name}', "
+                    f"but only {len(filename) - pos} remain"
+                )
+                raise ValueError(msg)
+
+            raw = filename[pos : pos + width]
+            pos += width
+
+            if field_name == "skip":
+                continue
+            elif field_name == "hour_letter":
+                result["hour_letter"] = raw
+            else:
+                try:
+                    result[field_name] = int(raw)
+                except ValueError:
+                    msg = f"Cannot parse '{field_name}' as integer from {raw!r} in {filename!r}"
+                    raise ValueError(msg) from None
+
+        return result
+
+    def to_virtual_file(self, file_path: Path) -> VirtualFile:
+        """Map a physical file to a VirtualFile using this recipe.
+
+        Parameters
+        ----------
+        file_path
+            Path to the physical file.
+
+        Returns
+        -------
+        VirtualFile
+            The mapped virtual file.
+
+        Raises
+        ------
+        ValueError
+            If the filename cannot be parsed.
+        """
+        parsed = self.parse_filename(file_path.name)
+
+        def _require_int(parsed_key: str) -> int:
+            value = parsed[parsed_key]
+            if isinstance(value, int):
+                return value
+            msg = (
+                f"Recipe '{self.name}': expected integer field '{parsed_key}' "
+                f"for {file_path.name!r}, got {value!r}"
+            )
+            raise ValueError(msg)
+
+        def _require_str(parsed_key: str) -> str:
+            value = parsed[parsed_key]
+            if isinstance(value, str):
+                return value
+            msg = (
+                f"Recipe '{self.name}': expected string field '{parsed_key}' "
+                f"for {file_path.name!r}, got {value!r}"
+            )
+            raise ValueError(msg)
+
+        # Resolve year
+        if "year" in parsed:
+            year = _require_int("year")
+        elif "yy" in parsed:
+            year = resolve_year_from_yy(_require_int("yy"))
+        else:
+            raise ValueError(
+                f"Recipe '{self.name}': no 'year' or 'yy' field "
+                f"in parsed result for {file_path.name!r}"
+            )
+
+        # Resolve DOY (from doy directly, or from month+day)
+        if "doy" in parsed:
+            doy = _require_int("doy")
+        elif "month" in parsed and "day" in parsed:
+            from datetime import date
+
+            doy = date(year, _require_int("month"), _require_int("day")).timetuple().tm_yday
+        else:
+            raise ValueError(
+                f"Recipe '{self.name}': no 'doy' or 'month'+'day' fields "
+                f"in parsed result for {file_path.name!r}"
+            )
+
+        # Resolve hour
+        if "hour" in parsed:
+            hour = _require_int("hour")
+        elif "hour_letter" in parsed:
+            hour = hour_letter_to_int(_require_str("hour_letter"))
+        else:
+            hour = 0
+
+        # Resolve minute
+        minute = _require_int("minute") if "minute" in parsed else 0
+
+        # Daily file: no hour in the name, or the RINEX 2 daily session "0"
+        # (hourly sessions are "a"-"x", so one recipe matches both)
+        period = self.period
+        has_hour = any("hour" in e or "hour_letter" in e for e in self.fields)
+        if parsed.get("hour_letter") == "0" or (hour == 0 and minute == 0 and not has_hour):
+            period = "01D"
+
+        rx_type = (
+            ReceiverType.REFERENCE if self.receiver_type == "reference" else ReceiverType.ACTIVE
+        )
+
+        conventional = CanVODFilename(
+            site=self.site,
+            receiver_type=rx_type,
+            receiver_number=self.receiver_number,
+            agency=self.agency,
+            year=year,
+            doy=doy,
+            hour=hour,
+            minute=minute,
+            period=period,
+            sampling=self.sampling,
+            content=self.content,
+            file_type=FileType(self.file_type),
+        )
+
+        return VirtualFile(physical_path=file_path, conventional_name=conventional)
+
+    @property
+    def expected_length(self) -> int:
+        """Total number of characters consumed by the field spec."""
+        return sum(next(iter(e.values())) for e in self.fields)
+
+    def matches(self, filename: str) -> bool:
+        """Check if a filename can be parsed by this recipe."""
+        if len(filename) != self.expected_length:
+            return False
+        try:
+            self.parse_filename(filename)
+            return True
+        except ValueError:
+            return False
+
+    # -- Serialization ---------------------------------------------------------
+
+    def to_yaml(self) -> str:
+        """Serialize to YAML string."""
+        return yaml.dump(
+            self.model_dump(mode="json"),
+            default_flow_style=False,
+            sort_keys=False,
+            allow_unicode=True,
+        )
+
+    def save(self, path: Path) -> None:
+        """Write recipe to a YAML file."""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(self.to_yaml(), encoding="utf-8")
+
+    @classmethod
+    def from_yaml(cls, text: str) -> NamingRecipe:
+        """Load from a YAML string."""
+        data = yaml.safe_load(text)
+        return cls.model_validate(data)
+
+    @classmethod
+    def load(cls, path: Path) -> NamingRecipe:
+        """Load from a YAML file."""
+        text = path.read_text(encoding="utf-8")
+        return cls.from_yaml(text)
+
+    @classmethod
+    def unrecognized_fields(cls, path: Path) -> list[str]:
+        """Top-level fields of a recipe file that the recipe does not know.
+
+        They are ignored when the recipe is loaded, for example a misspelled
+        field or one a later version of canvod-filemap reads.
+
+        Parameters
+        ----------
+        path : Path
+            A recipe file.
+
+        Returns
+        -------
+        list[str]
+            The unknown field names, in file order; empty if there are none.
+        """
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            return []
+        return [str(key) for key in data if key not in cls.model_fields]
+
+
+def recipe_sha256(path: Path) -> str:
+    """The sha256 of a recipe file, as recorded in a store's metadata.
+
+    Parameters
+    ----------
+    path : Path
+        A recipe file, local or fetched by this run.
+
+    Returns
+    -------
+    str
+        The hexadecimal sha256 of the file's bytes.
+    """
+    return hashlib.sha256(Path(path).read_bytes()).hexdigest()

canvod/filemap/recipe_files.py

@@ -0,0 +1,125 @@
+"""Where naming recipe files live, and creating them from the template.
+
+Recipes are kept per site in the configuration directory::
+
+    <config dir>/recipes/<site>/<name>.yaml
+
+``<site>`` is the site name in the settings file and ``<name>`` the
+receiver's ``recipe:`` setting. Recipe files are user data: they are not part
+of any repository and are only read from this location.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .remote import fetch_recipe, is_recipe_url
+
+#: The recipe template shipped with this package.
+TEMPLATE_PATH = Path(__file__).parent / "templates" / "recipe.yaml"
+
+
+class RecipeNotFoundError(FileNotFoundError):
+    """No recipe file exists for a site and recipe name."""
+
+
+def recipe_path(config_dir: Path, site: str, name: str) -> Path:
+    """Path of the recipe ``name`` of ``site``, whether it exists or not.
+
+    Parameters
+    ----------
+    config_dir : Path
+        The configuration directory (the one holding the settings file).
+    site : str
+        Site name in the settings file.
+    name : str
+        Recipe name, the receiver's ``recipe:`` setting.
+
+    Returns
+    -------
+    Path
+        ``<config_dir>/recipes/<site>/<name>.yaml``.
+    """
+    return Path(config_dir) / "recipes" / site / f"{name}.yaml"
+
+
+def find_recipe(config_dir: Path, site: str, name: str) -> Path:
+    """Path of the existing recipe file ``name`` of ``site``.
+
+    Parameters
+    ----------
+    config_dir : Path
+        The configuration directory (the one holding the settings file).
+    site : str
+        Site name in the settings file.
+    name : str
+        Recipe name, the receiver's ``recipe:`` setting.
+
+    Returns
+    -------
+    Path
+        ``<config_dir>/recipes/<site>/<name>.yaml``, or, if ``name`` is a
+        URL, the file of the recipe this run fetched
+        (:func:`canvod.filemap.remote.fetch_recipe`).
+
+    Raises
+    ------
+    RecipeNotFoundError
+        If that file does not exist. If the recipe is found directly in
+        ``<config_dir>/recipes/``, the message says where to move it.
+    RemoteRecipeError
+        If ``name`` is a URL that is not a raw file link, or the recipe
+        cannot be fetched or is not valid.
+    """
+    if is_recipe_url(name):
+        return fetch_recipe(name)
+    path = recipe_path(config_dir, site, name)
+    if path.is_file():
+        return path
+    flat = Path(config_dir) / "recipes" / f"{name}.yaml"
+    if flat.is_file():
+        msg = (
+            f"Recipe '{name}' of site '{site}' must be in a folder named after "
+            f"the site. Move {flat} to {path}"
+        )
+        raise RecipeNotFoundError(msg)
+    msg = f"Recipe file not found for '{name}' of site '{site}': {path}"
+    raise RecipeNotFoundError(msg)
+
+
+def create_recipe(config_dir: Path, site: str, name: str, *, overwrite: bool = False) -> Path:
+    """Create the recipe ``name`` of ``site`` from the template.
+
+    The new file has ``name`` filled in. The receiver identity and the
+    ``fields`` list must be edited before the recipe can be loaded.
+
+    Parameters
+    ----------
+    config_dir : Path
+        The configuration directory (the one holding the settings file).
+    site : str
+        Site name in the settings file.
+    name : str
+        Recipe name, the receiver's ``recipe:`` setting.
+    overwrite : bool
+        Replace an existing recipe file.
+
+    Returns
+    -------
+    Path
+        The created file, ``<config_dir>/recipes/<site>/<name>.yaml``.
+
+    Raises
+    ------
+    FileExistsError
+        If the recipe file exists and ``overwrite`` is false.
+    """
+    path = recipe_path(config_dir, site, name)
+    if path.exists() and not overwrite:
+        msg = f"Recipe file already exists: {path}"
+        raise FileExistsError(msg)
+    text = TEMPLATE_PATH.read_text(encoding="utf-8")
+    text = text.replace("name: CHANGEME", f"name: {name}", 1)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+    return path

canvod/filemap/remote.py

@@ -0,0 +1,160 @@
+"""Naming recipes read from a URL.
+
+A receiver's ``recipe:`` setting can be a raw file link to a recipe in a
+GitHub repository, at a commit, a tag or a branch::
+
+    https://raw.githubusercontent.com/<account>/<repo>/<commit>/<path>/<name>.yaml
+    https://raw.githubusercontent.com/<account>/<repo>/refs/tags/<tag>/<path>/<name>.yaml
+    https://raw.githubusercontent.com/<account>/<repo>/refs/heads/<branch>/<path>/<name>.yaml
+
+The user is responsible for what the link points to. Every run fetches
+the recipe again; there is no cache, so a run needs network access. The
+sha256 of the fetched file, recorded in the store's metadata with the
+file name of the URL (never the URL), says which recipe a run used.
+
+A recipe in a private repository needs a GitHub token in the environment
+variable ``GH_TOKEN`` or ``GITHUB_TOKEN``. canvodpy stores no secrets
+(ADR "Credentials come from the environment" in the canvodpy repository).
+The token is only sent to ``raw.githubusercontent.com``, never to the
+target of a redirect, and never appears in messages or logs.
+
+The URL check, token and download are canvodpy's
+:mod:`canvod.utils.remote_file`, which also reads settings files from a
+URL; this module adds the recipe check and keeps the recipe names and
+errors.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+from urllib.parse import urlsplit
+
+import yaml
+from canvod.utils import remote_file
+from canvod.utils.remote_file import RemoteFetchError, RemoteURLError
+from pydantic import ValidationError
+
+from .recipe import NamingRecipe
+
+#: The only host recipes are read from.
+RECIPE_HOST = remote_file.REMOTE_HOST
+
+#: Environment variables a GitHub token is read from, in this order.
+TOKEN_VARIABLES = remote_file.TOKEN_VARIABLES
+
+#: Largest recipe file accepted, in bytes.
+MAX_RECIPE_BYTES = 1_000_000
+
+
+class RemoteRecipeError(Exception):
+    """A recipe URL that cannot be used."""
+
+
+class RecipeURLError(RemoteRecipeError, ValueError):
+    """A recipe URL that is not a raw file link."""
+
+
+class RecipeFetchError(RemoteRecipeError):
+    """A recipe that could not be fetched, or whose file is not a valid recipe."""
+
+
+def is_recipe_url(value: str) -> bool:
+    """Whether a ``recipe:`` setting is a URL rather than a recipe name.
+
+    Parameters
+    ----------
+    value : str
+        The receiver's ``recipe:`` setting.
+
+    Returns
+    -------
+    bool
+        True for ``https://`` and ``http://`` values.
+    """
+    return remote_file.is_url(value)
+
+
+def check_recipe_url(url: str) -> None:
+    """Check that ``url`` is a raw file link in a GitHub repository.
+
+    Parameters
+    ----------
+    url : str
+        The recipe URL.
+
+    Raises
+    ------
+    RecipeURLError
+        If the URL is not ``https``, holds a user name, password, query or
+        fragment, points to a host other than ``raw.githubusercontent.com``
+        (a ``github.com/.../blob/...`` link gets the matching raw link),
+        has no ``<account>/<repo>/<commit, tag or branch>/<file>`` path, or
+        does not end in a ``.yaml`` or ``.yml`` file.
+    """
+    try:
+        remote_file.parse_remote_url(url, what="recipe")
+    except RemoteURLError as exc:
+        raise RecipeURLError(str(exc)) from None
+
+
+def fetch_recipe(url: str, *, timeout: float = 30.0) -> Path:
+    """The local file of the recipe at ``url``, fetched by this run.
+
+    The URL is checked with :func:`check_recipe_url`. The file is fetched,
+    read like a local recipe file, and its ``name`` must match the file
+    name at the end of the URL. A run fetches a URL once, into a folder
+    of the run that is removed when the process that made it ends
+    (:func:`canvod.utils.remote_file.fetch_remote`).
+
+    Parameters
+    ----------
+    url : str
+        The recipe URL.
+    timeout : float
+        Seconds to wait for the server.
+
+    Returns
+    -------
+    Path
+        The fetched recipe file.
+
+    Raises
+    ------
+    RecipeURLError
+        If the URL is not a raw file link.
+    RecipeFetchError
+        If the file cannot be fetched (not found, no access, a token that
+        is not a token, no network, timeout), is not a valid recipe, or its
+        name does not match the URL.
+    """
+    try:
+        return remote_file.fetch_remote(
+            url,
+            what="recipe",
+            check=lambda data: _check_content(url, data),
+            max_bytes=MAX_RECIPE_BYTES,
+            timeout=timeout,
+        )
+    except RemoteURLError as exc:
+        raise RecipeURLError(str(exc)) from None
+    except RemoteFetchError as exc:
+        raise RecipeFetchError(str(exc)) from None
+
+
+def _check_content(url: str, data: bytes) -> None:
+    """Read ``data`` like a local recipe file and check its name against ``url``."""
+    try:
+        recipe = NamingRecipe.from_yaml(data.decode("utf-8"))
+    except (UnicodeDecodeError, yaml.YAMLError) as exc:
+        msg = f"Recipe {url} is not a YAML file: {exc}"
+        raise RecipeFetchError(msg) from None
+    except ValidationError as exc:
+        msg = f"Recipe {url} is not a valid recipe:\n{exc}"
+        raise RecipeFetchError(msg) from None
+    stem = PurePosixPath(urlsplit(url).path).stem
+    if recipe.name != stem:
+        msg = (
+            f"Recipe {url} is named '{recipe.name}', but its file is '{stem}'. "
+            "The recipe's name must match its file name."
+        )
+        raise RecipeFetchError(msg)

canvod/filemap/templates/recipe.yaml

@@ -0,0 +1,77 @@
+# =============================================================================
+# canVODpy naming recipe
+# =============================================================================
+# A recipe maps the file names of one receiver to the canonical canVOD name
+# {SIT}{T}{NN}{AGC}_R_{YYYY}{DOY}{HHMM}_{PERIOD}_{SAMPLING}_{CONTENT}.{TYPE}
+# without renaming anything on disk. It is only needed if the receiver writes
+# non-canonical file names.
+#
+# Recipes live in <config dir>/recipes/<site>/<name>.yaml, where <site> is the
+# site name in canvod-settings.yaml and <name> is the receiver's `recipe:`
+# setting. Fill in the receiver identity below, then describe the file names
+# in the `fields:` list.
+
+name: CHANGEME               # same as the file name, without .yaml
+description: ""
+
+# -----------------------------------------------------------------------
+# Receiver identity: the first 9 characters of the canonical name
+# -----------------------------------------------------------------------
+site: CHANGEME                 # 3-character site code, e.g. FAN
+agency: CHANGEME               # 3-character agency code, e.g. INK
+receiver_number: 1             # 1-99, unique per receiver role at the site
+receiver_type: reference       # reference or canopy
+
+# -----------------------------------------------------------------------
+# File properties written into the canonical name
+# -----------------------------------------------------------------------
+sampling: "05S"                # sampling interval, e.g. 01S, 05S, 15S, 30S
+period: "15M"                  # time span of one file, e.g. 15M, 01H, 01D
+content: AA                    # content code (AA = all observables)
+file_type: rnx                 # rnx, sbf, ubx or nmea
+
+# -----------------------------------------------------------------------
+# Which files belong to this receiver
+# -----------------------------------------------------------------------
+glob: "*.??o"                  # pattern the file names must match
+
+# -----------------------------------------------------------------------
+# Field extraction: a left-to-right walk over the file name
+# -----------------------------------------------------------------------
+# Each entry consumes N characters and either reads a value or skips them.
+# Field names:
+#   year         4-digit year (e.g. 2025)
+#   yy           2-digit year (80-99 -> 19xx, 00-79 -> 20xx)
+#   doy          day of year (1-366)
+#   month, day   calendar month and day (together, instead of doy)
+#   hour         hour (00-23)
+#   minute       minute (00-59)
+#   hour_letter  RINEX 2 session letter, instead of hour: a-x = hours 0-23,
+#                0 = daily file (period 01D)
+#   skip         ignore these characters
+#
+# Example 1, RINEX short name rref001a15.25o
+#   station "rref", doy "001", hour letter "a", minute "15", extension "25o"
+# fields:
+#   - skip: 4
+#   - doy: 3
+#   - hour_letter: 1
+#   - minute: 2
+#   - skip: 1
+#   - yy: 2
+#   - skip: 1
+#
+# Example 2, STATION_2025_042_00_15.rinex
+# fields:
+#   - skip: 8
+#   - year: 4
+#   - skip: 1
+#   - doy: 3
+#   - skip: 1
+#   - hour: 2
+#   - skip: 1
+#   - minute: 2
+#   - skip: 6
+
+fields:
+  - skip: 0   # CHANGEME: replace with the fields of your file names

canvod_filemap-1.0.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: canvod-filemap
+Version: 1.0.0
+Summary: Naming recipes that map non-canonical GNSS-T filenames to canVOD names
+Keywords: GNSS,GNSS-T,file names,naming recipes,RINEX,SBF,remote sensing
+Author: Nicolas François Bader
+Author-email: Nicolas François Bader <support@canvodpy.eu>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: canvod-preflight>=1.0.0
+Requires-Dist: canvod-utils>=1.0.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: natsort>=8.4.0
+Maintainer: Climate and Environmental Remote Sensing (CLIMERS)
+Maintainer-email: Climate and Environmental Remote Sensing (CLIMERS) <support@canvodpy.eu>
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/TUW-GEO/canvodpy-extensions
+Project-URL: Documentation, https://extensions.canvodpy.eu/packages/filemap/overview/
+Project-URL: Repository, https://github.com/TUW-GEO/canvodpy-extensions
+Project-URL: Issues, https://github.com/TUW-GEO/canvodpy-extensions/issues
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/TUW-GEO/canvodpy/main/docs/assets/logo/canvodpy_logo_dark_mode.svg">
+    <img alt="canVODpy" src="https://raw.githubusercontent.com/TUW-GEO/canvodpy/main/docs/assets/logo/canvodpy_logo_bright_mode.svg" width="260">
+  </picture>
+</p>
+
+# canvod-filemap
+
+[![PyPI](https://img.shields.io/pypi/v/canvod-filemap.svg)](https://pypi.org/project/canvod-filemap/)
+[![Python](https://img.shields.io/badge/python-3.14-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/TUW-GEO/canvodpy-extensions/blob/main/LICENSE)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21359005-blue)](https://doi.org/10.5281/zenodo.21359005)
+
+**Naming recipes for receiver files that don't follow the canVOD file name convention.** `canvod-filemap` is one of the
+[canVODpy extensions](https://extensions.canvodpy.eu/), optional packages
+for [canVODpy](https://canvodpy.eu/), an open Python ecosystem for
+GNSS-Transmissometry (GNSS-T) canopy VOD retrievals.
+
+## What it does
+
+`canvodpy run` processes files whose names follow the canVOD convention, in
+any folder layout. For a receiver whose files are named differently, a
+naming recipe translates each file name to its canonical name, without
+renaming any file on disk.
+
+```
+{SIT}{T}{NN}{AGC}_R_{YYYY}{DOY}{HHMM}_{PERIOD}_{SAMPLING}_{CONTENT}.{TYPE}
+```
+
+Example: `FANA01INK_R_20250010000_15M_05S_AA.rnx`
+
+| Component | Purpose |
+|---|---|
+| `NamingRecipe` | Translates a receiver's own file names to canonical names |
+| `find_recipe`, `create_recipe` | Recipe files at `<config dir>/recipes/<site>/<name>.yaml`; new ones from the template |
+| `fetch_recipe`, `check_recipe_url` | Recipes from a raw GitHub link (commit, tag or branch), fetched by every run |
+
+`canvodpy config validate --site <site>` checks before a run which files the
+run would process.
+
+## Install
+
+```bash
+uv add canvod-filemap
+```
+
+canVODpy requires Python 3.14.
+
+## Example
+
+```python
+from pathlib import Path
+
+from canvod.filemap import NamingRecipe
+
+recipe = NamingRecipe.load(Path("config/recipes/fangorn/fangorn_reference.yaml"))
+vf = recipe.to_virtual_file(Path("rref001a15.25o"))
+print(vf.conventional_name)  # canonical canVOD name; the file keeps its name
+```
+
+## Documentation
+
+[filemap documentation](https://extensions.canvodpy.eu/packages/filemap/overview/)
+and the [canVODpy documentation](https://canvodpy.eu/).
+
+## Citation
+
+Please cite the canVODpy extensions with their Zenodo DOI,
+[10.5281/zenodo.21359005](https://doi.org/10.5281/zenodo.21359005), and
+canVODpy with
+[10.5281/zenodo.18496233](https://doi.org/10.5281/zenodo.18496233).
+
+## License
+
+Apache License 2.0. See
+[LICENSE](https://github.com/TUW-GEO/canvodpy-extensions/blob/main/LICENSE)
+and [NOTICE](https://github.com/TUW-GEO/canvodpy-extensions/blob/main/NOTICE).

canvod_filemap-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+canvod/filemap/__init__.py,sha256=wS8ZMYkTd1HOtJCg1IiR0uEkIieXDaPSUrwV3_ZeRDk,787
+canvod/filemap/mapping.py,sha256=bejmrSMdcjX4HzrahbOqt6Z0xcgKlyr4jlNhlhb9D_w,754
+canvod/filemap/patterns.py,sha256=b24dVGxP5Xtm-h_3QsDUOITS_Z0UguXyNMykLD8xY4Y,829
+canvod/filemap/recipe.py,sha256=nIY5wnJcx3vNXLGUQYUUvkSljc29YQ9DK2MQzkt4xrg,11765
+canvod/filemap/recipe_files.py,sha256=spIQt3vcDIto3p7RZ7Eq1FrLED5k6WtLXpV2pOLuEoU,3974
+canvod/filemap/remote.py,sha256=WCp1W9t2sCiNCdIXp0VyqFO8egMGwd0yjgIoalmcqpU,5379
+canvod/filemap/templates/recipe.yaml,sha256=riuGl2rKUvlrOsewkipVfKBykMU3peu7f51yPvEG2G0,3218
+canvod_filemap-1.0.0.dist-info/licenses/LICENSE,sha256=U-RON1EiebzhqnitQJxzTyVzpX4thnEpslKJNf0ymbA,11474
+canvod_filemap-1.0.0.dist-info/licenses/NOTICE,sha256=0_Cqs8FdJJO_wa9jhFwu4yx5hvA-BQC_SQlBOSkIOc4,566
+canvod_filemap-1.0.0.dist-info/WHEEL,sha256=si2p8vW03RnhyBnhWl4tj-ObJa78SpE-c9HsEtblGR0,80
+canvod_filemap-1.0.0.dist-info/METADATA,sha256=1SV9YZ1ZfF2xYOeBxbk0JEwzav2VQtRcCASCaXl0S4w,4358
+canvod_filemap-1.0.0.dist-info/RECORD,,

canvod_filemap-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.5
+Root-Is-Purelib: true
+Tag: py3-none-any

canvod_filemap-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,203 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Nicolas François Bader
+   Climate and Environmental Remote Sensing Research Unit (CLIMERS)
+   Department of Geodesy and Geoinformation, TU Wien
+
+   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
+
+       http://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.

canvod_filemap-1.0.0.dist-info/licenses/NOTICE

@@ -0,0 +1,14 @@
+canvodpy-extensions
+Copyright 2026 Nicolas François Bader, TU Wien
+
+This product includes software developed at the
+Climate and Environmental Remote Sensing Research Unit (CLIMERS),
+Department of Geodesy and Geoinformation, TU Wien.
+
+This product includes contributions from the canVODpy community.
+Individual contributors are listed in the CONTRIBUTORS.md file and
+recorded in the Git revision history of the repository:
+https://github.com/TUW-GEO/canvodpy-extensions
+
+canvodpy-extensions is an optional extension monorepo for
+https://github.com/TUW-GEO/canvodpy.