imas-python 0.1.dev1618__py3-none-any.whl

imas/dd_helpers.py

@@ -0,0 +1,300 @@
+# This file is part of imas-python.
+# You should have received the imas-python LICENSE file with this project.
+"""Helper functions to build IDSDef.xml"""
+
+import logging
+import os
+import re
+import shutil
+import subprocess
+from io import BytesIO
+from pathlib import Path
+from typing import Sequence, Tuple, Union
+from urllib.request import urlopen
+from zipfile import ZIP_DEFLATED, ZipFile
+
+from packaging.version import Version as V
+
+logger = logging.getLogger(__name__)
+
+_idsdef_zip_relpath = Path("imas/assets/IDSDef.zip")
+_build_dir = Path("build")
+_saxon_local_default_name = "saxon9he.jar"  # For pre-3.30.0 builds
+_saxon_regex = "saxon((.(?!test|xqj))*).jar"  # Can be used in re.match
+
+
+def prepare_data_dictionaries():
+    """Build IMAS IDSDef.xml files for each tagged version in the DD repository
+    1. Search for saxon or download it
+    2. Clone the DD repository (ask for user/pass unless ssh key access is available)
+    3. Generate IDSDef.xml and rename to IDSDef_${version}.xml
+    4. Zip all these IDSDefs together and include in wheel
+    """
+    from git import Repo
+
+    saxon_jar_path = get_saxon()
+    repo: Repo = get_data_dictionary_repo()
+    if repo:
+        newest_version_and_tag = (V("0"), None)
+        for tag in repo.tags:
+            version_and_tag = (V(str(tag)), tag)
+            if V(str(tag)) > V("3.21.1"):
+                newest_version_and_tag = max(newest_version_and_tag, version_and_tag)
+                logger.debug("Building data dictionary version %s", tag)
+                build_data_dictionary(repo, tag, saxon_jar_path)
+
+        logger.info("Creating zip file of DD versions")
+
+        if _idsdef_zip_relpath.is_file():
+            logger.warning("Overwriting '%s'", _idsdef_zip_relpath)
+
+        with ZipFile(
+            _idsdef_zip_relpath,
+            mode="w",  # this needs w, since zip can have multiple same entries
+            compression=ZIP_DEFLATED,
+        ) as dd_zip:
+            for filename in _build_dir.glob("[0-9]*.xml"):
+                arcname = Path("data-dictionary").joinpath(*filename.parts[1:])
+                dd_zip.write(filename, arcname=arcname)
+            # Include identifiers from latest tag in zip file
+            repo.git.checkout(newest_version_and_tag[1], force=True)
+            # DD layout <= 4.0.0
+            for filename in Path("data-dictionary").glob("*/*identifier.xml"):
+                arcname = Path("identifiers").joinpath(*filename.parts[1:])
+                dd_zip.write(filename, arcname=arcname)
+            # DD layout > 4.0.0
+            for filename in Path("data-dictionary").glob("schemas/*/*identifier.xml"):
+                arcname = Path("identifiers").joinpath(*filename.parts[2:])
+                dd_zip.write(filename, arcname=arcname)
+
+
+# pre 3.30.0 versions of the DD have the `saxon9he.jar` file path hardcoded
+# in their makefiles. To be sure we can build everything, we link whatever
+# saxon we can find to a local file called saxon9he.jar
+def get_saxon() -> Path:
+    """Search for saxon*.jar and return the path or download it.
+    The DD build works by having Saxon in the CLASSPATH, called saxon9he.jar
+    until DD version 3.30.0. After 3.30.0 Saxon is found by the SAXONJARFILE env
+    variable. We will 'cheat' a little bit later by symlinking saxon9he.jar to
+    any version of saxon we found.
+
+    Check:
+    1. CLASSPATH
+    2. `which saxon`
+    3. /usr/share/java/*
+    4. or download it
+    """
+
+    local_saxon_path = Path.cwd() / _saxon_local_default_name
+    if local_saxon_path.exists():
+        logger.debug("Something already at '%s' not creating anew", local_saxon_path)
+        return local_saxon_path
+
+    saxon_jar_origin = Path(
+        find_saxon_classpath()
+        or find_saxon_bin()
+        or find_saxon_jar()
+        or download_saxon()
+    )
+    logger.info("Found Saxon JAR '%s'", saxon_jar_origin)
+    if saxon_jar_origin.name != _saxon_local_default_name:
+        try:
+            os.symlink(saxon_jar_origin, local_saxon_path)
+        except FileExistsError:
+            # Another process could have created the symlink while we were searching
+            logger.debug(
+                "Link '%s' exists, parallel process might've created it",
+                local_saxon_path,
+            )
+        return local_saxon_path
+    return saxon_jar_origin
+
+
+def find_saxon_jar():
+    # This finds multiple versions on my system, but they are symlinked together.
+    # take the shortest one.
+    jars = [
+        path
+        for path in Path("/usr/share/java").rglob("*")
+        if re.match(_saxon_regex, path.name, flags=re.IGNORECASE)
+    ]
+
+    if jars:
+        saxon_jar_path = min(jars, key=lambda x: len(x.parts))
+        return saxon_jar_path
+
+
+def find_saxon_classpath():
+    """Search JAVAs CLASSPATH for a Saxon .jar"""
+    classpath = os.environ.get("CLASSPATH", "")
+    for part in re.split(";|:", classpath):
+        if (
+            part.endswith(".jar")
+            and part.split("/")[-1].startswith("saxon")
+            and "test" not in part
+            and "xqj" not in part
+        ):
+            return part
+
+
+def find_saxon_bin():
+    """Search for a saxon executable"""
+    saxon_bin = shutil.which("saxon")
+    if saxon_bin:
+        with open(saxon_bin, "r") as file:
+            for line in file:
+                saxon_jar_path = re.search("[^ ]*saxon[^ ]*jar", line)
+                if saxon_jar_path:
+                    return saxon_jar_path.group(0)
+
+
+def download_saxon():
+    """Downloads a zipfile containing Saxon and extract it to the current dir.
+    Return the full path to Saxon. This can be any Saxon version. Scripts that
+    wrap this should probably manipulate either the name of this file, and/or
+    the CLASSPATH"""
+
+    SAXON_PATH = "https://github.com/Saxonica/Saxon-HE/releases/download/SaxonHE10-9/SaxonHE10-9J.zip"  # noqa: E501
+
+    resp = urlopen(SAXON_PATH, timeout=120.0)
+    zipfile = ZipFile(BytesIO(resp.read()))
+    # Zipfile has a list of the ZipInfos. Look inside for a Saxon jar
+    for file in zipfile.filelist:
+        if re.match(_saxon_regex, file.filename, flags=re.IGNORECASE):
+            path = zipfile.extract(file)
+            del zipfile
+            return path
+    raise FileNotFoundError(f"No Saxon jar found in given zipfile '{SAXON_PATH}'")
+
+
+def get_data_dictionary_repo() -> Tuple[bool, bool]:
+    try:
+        import git  # Import git here, the user might not have it!
+    except ModuleNotFoundError:
+        raise RuntimeError(
+            "Could not find 'git' module, try 'pip install gitpython'. \
+            Will not build Data Dictionaries!"
+        )
+
+        # We need the actual source code (for now) so grab it from ITER
+    dd_repo_path = "data-dictionary"
+
+    if "DD_DIRECTORY" in os.environ:
+        logger.info("Found DD_DIRECTORY, copying")
+        try:
+            shutil.copytree(os.environ["DD_DIRECTORY"], dd_repo_path)
+        except FileExistsError:
+            pass
+    else:
+        logger.info("Trying to pull data dictionary git repo from ITER")
+
+    # Set up a bare repo and fetch the data-dictionary repository in it
+    os.makedirs(dd_repo_path, exist_ok=True)
+    try:
+        repo = git.Repo(dd_repo_path)
+    except git.exc.InvalidGitRepositoryError:
+        repo = git.Repo.init(dd_repo_path)
+    logger.info("Set up local git repository {!s}".format(repo))
+
+    try:
+        origin = repo.remote()
+    except ValueError:
+        dd_repo_url = "https://github.com/iterorganization/imas-data-dictionary.git"
+        origin = repo.create_remote("origin", url=dd_repo_url)
+    logger.info("Set up remote '{!s}' linking to '{!s}'".format(origin, origin.url))
+
+    try:
+        origin.fetch(tags=True)
+    except git.exc.GitCommandError as ee:
+        logger.warning(
+            "Could not fetch tags from %s. Git reports:\n %s." "\nTrying to continue",
+            list(origin.urls),
+            ee,
+        )
+    else:
+        logger.info("Remote tags fetched")
+    return repo
+
+
+def _run_data_dictionary(
+    args: Union[Sequence, str], tag: str, saxon_jar_path: str
+) -> int:
+    """Run in a Data Dictionary environment. Used e.g. to run the DD Makefile
+
+    Args:
+        args: The "args" argument directly passed to :func:`subprocess.run`,
+            e.g. ``["make", "clean"]``
+        tag: The DD version tag that will be printed on error
+        saxon_jar_path: The path to the saxon jar; Added to CLASSPATH and used
+            to generate the DD
+    """
+    env = os.environ.copy()
+    env["CLASSPATH"] = f"{saxon_jar_path}:{env.get('CLASSPATH', '')}"
+    result = subprocess.run(
+        args,
+        bufsize=0,
+        capture_output=True,
+        cwd=os.getcwd() + "/data-dictionary",
+        env=env,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        logger.warning("Error making DD version %s, make reported:", tag)
+        logger.warning("CLASSPATH ='%s'", saxon_jar_path)
+        logger.warning("PATH = '%s'", os.environ.get("PATH", ""))
+        logger.warning("stdout = '%s'", result.stdout.strip())
+        logger.warning("stderr = '%s'", result.stderr.strip())
+        logger.warning("continuing without DD version %s", tag)
+    else:
+        logger.debug(
+            "Successful make for DD %s.\n-- Make stdout --\n%s\n-- Make stderr --\n%s",
+            tag,
+            result.stdout,
+            result.stderr,
+        )
+    return result.returncode
+
+
+def build_data_dictionary(repo, tag: str, saxon_jar_path: str, rebuild=False) -> None:
+    """Build a single version of the data dictionary given by the tag argument
+    if the IDS does not already exist.
+
+    In the data-dictionary repository sometimes IDSDef.xml is stored
+    directly, in which case we do not call make.
+
+    Args:
+        repo: Repository object containing the DD source code
+        tag: The DD version tag that will be build
+        saxon_jar_path: The path to the saxon jar; Added to CLASSPATH and used
+            to generate the DD
+        rebuild: If true, overwrites existing pre-build tagged DD version
+    """
+    _build_dir.mkdir(exist_ok=True)
+    result_xml = _build_dir / f"{tag}.xml"
+
+    if result_xml.exists() and not rebuild:
+        logger.debug(f"XML for tag '{tag}' already exists, skipping")
+        return
+
+    repo.git.checkout(tag, force=True)
+    if _run_data_dictionary(["make", "clean"], tag, saxon_jar_path) != 0:
+        return
+    if _run_data_dictionary(["make", "IDSDef.xml"], tag, saxon_jar_path) != 0:
+        return
+
+    # copy and delete original instead of move (to follow symlink)
+    IDSDef = Path("data-dictionary/IDSDef.xml")
+    try:
+        shutil.copy(
+            IDSDef,  # Hardcoded in access-layer makefile
+            result_xml,
+            follow_symlinks=True,
+        )
+    except shutil.SameFileError:
+        pass
+    IDSDef.unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    prepare_data_dictionaries()

imas/dd_zip.py

@@ -0,0 +1,297 @@
+# This file is part of imas-python.
+# You should have received the imas-python LICENSE file with this project.
+""" Extract DD versions from a zip file.
+
+The zip file contains files as
+* `data-dictionary/3.30.0.xml`
+* `data-dictionary/3.29.0.xml`
+
+multiple paths are checked. See `ZIPFILE_LOCATIONS`.
+First the environment variable IMASPY_DDZIP is checked.
+If that exists and points to a file we will attempt to open it.
+Then, IDSDef.zip is searched in site-packages, the current folder,
+in .config/imas/ (`$$XDG_CONFIG_HOME`) and in
+the assets/ folder within the imas-python package.
+
+1. `$$IMASPY_DDZIP`
+2. The virtual environment
+3. USER_BASE`imas/IDSDef.zip`
+4. All `site-packages/imas/IDSDef.zip`
+5. `./IDSDef.zip`
+6. `~/.config/imas/IDSDef.zip`
+7. `__file__/../../imas/assets/IDSDef.zip`
+
+All files are checked, i.e. if your .config/imas/IDSDef.zip is outdated
+the imas-python-packaged version will be used.
+
+The `assets/IDSDef.zip` provided with the package can be updated
+with the `python setup.py build_DD` command, which is also performed on install
+if you have access to the ITER data-dictionary git repo.
+Reinstalling imas thus also will give you access to the latest DD versions.
+"""
+import logging
+import os
+import re
+import xml.etree.ElementTree as ET
+from contextlib import contextmanager, nullcontext
+from functools import lru_cache
+from pathlib import Path
+from typing import Dict, Iterator, List, Tuple, Union
+from zipfile import ZipFile
+
+try:
+    from importlib.resources import as_file, files
+
+    try:
+        from importlib.resources.abc import Traversable
+    except ModuleNotFoundError:  # Python 3.9/3.10 support
+        from importlib.abc import Traversable
+
+except ImportError:  # Python 3.8 support
+    from importlib_resources import as_file, files
+    from importlib_resources.abc import Traversable
+
+from packaging.version import InvalidVersion, Version
+
+import imas
+from imas.exception import UnknownDDVersion
+
+logger = logging.getLogger(__name__)
+
+
+def _get_xdg_config_dir():
+    """
+    Return the XDG config directory, according to the XDG base directory spec:
+
+    https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
+    """
+    return os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+
+
+def _generate_zipfile_locations() -> Iterator[Union[Path, Traversable]]:
+    """Build a list of potential data dictionary locations.
+    We start with the path (if any) of the IMASPY_DDZIP env var.
+    Then we look for IDSDef.zip in the current folder, in the
+    default XDG config dir (~/.config/imas/IDSDef.zip) and
+    finally in the assets distributed with this package.
+    """
+    zip_name = "IDSDef.zip"
+
+    environ = os.environ.get("IMASPY_DDZIP")
+    if environ:
+        yield Path(environ).resolve()
+
+    yield Path(zip_name).resolve()
+    yield Path(_get_xdg_config_dir()).resolve() / "imas" / zip_name
+    yield files(imas) / "assets" / zip_name
+
+
+def parse_dd_version(version: str) -> Version:
+    try:
+        return Version(version)
+    except InvalidVersion:
+        # This is probably a dev build of the DD, of which the version is obtained with
+        # `git describe` in the format X.Y.Z-<ncommits>-g<hash> with X.Y.Z the previous
+        # released version: try again after converting the first dash to a + and treat
+        # it like a `local` version specifier, which is recognized as newer.
+        # https://packaging.python.org/en/latest/specifications/version-specifiers/
+        return Version(version.replace("-", "+", 1))
+
+
+# Expected use case is one, maximum two DD versions
+# Cache is bigger than that: in pytest we currently use the following DD versions:
+#   - 3.22.0
+#   - 3.25.0
+#   - 3.28.0
+#   - 3.39.0
+#   - 4.0.0 (if available)
+#   - Environment default
+#   - IDS_fake_toplevel.xml
+#   - IDS_minimal.xml
+#   - IDS_minimal_2.xml
+#   - IDS_minimal_struct_array.xml
+#   - IDS_minimal_types.xml
+_DD_CACHE_SIZE = 8
+ZIPFILE_LOCATIONS = list(_generate_zipfile_locations())
+
+
+def dd_etree(version=None, xml_path=None):
+    """Return the DD element tree corresponding to the provided dd_version or xml_file.
+
+    By default (``dd_version`` and ``dd_xml`` are not supplied), this will attempt
+    to get the version from the environment (``IMAS_VERSION``) and use the latest
+    available version as fallback.
+
+    You can also specify a specific DD version to use (e.g. "3.38.1") or point to a
+    specific data-dictionary XML file. These options are exclusive.
+
+    Args:
+        version: DD version string, e.g. "3.38.1".
+        xml_path: XML file containing data dictionary definition.
+    """
+    if version and xml_path:
+        raise ValueError("version and xml_path cannot be provided both.")
+    if not version and not xml_path:
+        # Figure out which DD version to use
+        if "IMAS_VERSION" in os.environ:
+            imas_version = os.environ["IMAS_VERSION"]
+            if imas_version in dd_xml_versions():
+                # Use bundled DD version when available
+                version = imas_version
+            elif "IMAS_PREFIX" in os.environ:
+                # Try finding the IDSDef.xml in this installation
+                imas_prefix = Path(os.environ["IMAS_PREFIX"]).resolve()
+                xml_file = imas_prefix / "include" / "IDSDef.xml"
+                if xml_file.exists():
+                    xml_path = str(xml_file)
+            if not version and not xml_path:
+                logger.warning(
+                    "Unable to load IMAS version %s, falling back to latest version.",
+                    imas_version,
+                )
+    if not version and not xml_path:
+        # Use latest available from
+        version = latest_dd_version()
+    # Do the actual loading in a cached method:
+    return _load_etree(version, xml_path)
+
+
+@lru_cache(_DD_CACHE_SIZE)
+def _load_etree(version, xml_path):
+    if xml_path:
+        logger.info("Parsing data dictionary from file: %s", xml_path)
+        tree = ET.parse(xml_path)
+    else:
+        xml = get_dd_xml(version)
+        logger.info("Parsing data dictionary version %s", version)
+        tree = ET.ElementTree(ET.fromstring(xml))
+    return tree
+
+
+@contextmanager
+def _open_zipfile(path: Union[Path, Traversable]) -> Iterator[ZipFile]:
+    """Open a zipfile, given a Path or Traversable."""
+    if isinstance(path, Path):
+        ctx = nullcontext(path)
+    else:
+        ctx = as_file(path)
+    with ctx as file:
+        with ZipFile(file) as zipfile:
+            yield zipfile
+
+
+@lru_cache
+def _read_dd_versions() -> Dict[str, Tuple[Union[Path, Traversable], str]]:
+    """Traverse all possible DD zip files and return a map of known versions.
+
+    Returns:
+        version_map: version -> (zipfile path, filename)
+    """
+    versions = {}
+    xml_re = re.compile(r"^data-dictionary/([0-9.]+)\.xml$")
+    for path in ZIPFILE_LOCATIONS:
+        if not path.is_file():
+            continue
+        with _open_zipfile(path) as zipfile:
+            for fname in zipfile.namelist():
+                match = xml_re.match(fname)
+                if match:
+                    version = match.group(1)
+                    if version not in versions:
+                        versions[version] = (path, fname)
+    if not versions:
+        raise RuntimeError(
+            "Could not find any data dictionary definitions. "
+            f"Looked in: {', '.join(map(repr, ZIPFILE_LOCATIONS))}."
+        )
+    return versions
+
+
+@lru_cache
+def _read_identifiers() -> Dict[str, Tuple[Union[Path, Traversable], str]]:
+    """Traverse all possible DD zip files and return a map of known identifiers.
+
+    Returns:
+        identifier_map: identifier -> (zipfile path, filename)
+    """
+    identifiers = {}
+    xml_re = re.compile(r"^identifiers/\w+/(\w+_identifier).xml$")
+    for path in ZIPFILE_LOCATIONS:
+        if not path.is_file():
+            continue
+        with _open_zipfile(path) as zipfile:
+            for fname in zipfile.namelist():
+                match = xml_re.match(fname)
+                if match:
+                    identifier_name = match.group(1)
+                    if identifier_name not in identifiers:
+                        identifiers[identifier_name] = (path, fname)
+    return identifiers
+
+
+@lru_cache
+def dd_xml_versions() -> List[str]:
+    """Parse IDSDef.zip to find version numbers available"""
+
+    def sort_key(version):
+        try:
+            return parse_dd_version(version)
+        except InvalidVersion:
+            # Don't fail when a malformatted version is present in the DD zip
+            logger.error(
+                f"Could not convert DD XML version {version} to a Version.", exc_info=1
+            )
+            return Version(0)
+
+    return sorted(_read_dd_versions(), key=sort_key)
+
+
+@lru_cache
+def dd_identifiers() -> List[str]:
+    """Parse IDSDef.zip to find available identifiers"""
+
+    return sorted(_read_identifiers())
+
+
+def get_dd_xml(version):
+    """Read XML file for the given data dictionary version."""
+    dd_versions = dd_xml_versions()
+    if version not in dd_versions:
+        raise UnknownDDVersion(version, dd_versions)
+    path, fname = _read_dd_versions()[version]
+    with _open_zipfile(path) as zipfile:
+        return zipfile.read(fname)
+
+
+def get_dd_xml_crc(version):
+    """Given a version string, return its CRC checksum"""
+    # Note, by this time get_dd_xml is already called, so we don't need to check if the
+    # version is known
+    path, fname = _read_dd_versions()[version]
+    with _open_zipfile(path) as zipfile:
+        return zipfile.getinfo(fname).CRC
+
+
+def get_identifier_xml(identifier_name):
+    """Get identifier XML for the given identifier name"""
+    path, fname = _read_identifiers()[identifier_name]
+    with _open_zipfile(path) as zipfile:
+        return zipfile.read(fname)
+
+
+def print_supported_version_warning(version):
+    try:
+        if parse_dd_version(version) < imas.OLDEST_SUPPORTED_VERSION:
+            logger.warning(
+                "Version %s is below lowest supported version of %s.\
+                Proceed at your own risk.",
+                version,
+                imas.OLDEST_SUPPORTED_VERSION,
+            )
+    except InvalidVersion:
+        logging.warning("Ignoring version parsing error.", exc_info=1)
+
+
+def latest_dd_version():
+    """Find the latest version in data-dictionary/IDSDef.zip"""
+    return dd_xml_versions()[-1]

imas/exception.py

@@ -0,0 +1,107 @@
+# This file is part of imas-python.
+# You should have received the imas-python LICENSE file with this project.
+"""Exception classes used in imas-python.
+"""
+
+import difflib
+import logging
+from typing import TYPE_CHECKING, List
+
+from imas.backends.imas_core import imas_interface as _imas_interface
+
+if TYPE_CHECKING:
+    from imas.ids_factory import IDSFactory
+
+
+logger = logging.getLogger(__name__)
+
+
+# Expose ALException, which may be thrown by the lowlevel
+if _imas_interface.has_imas:
+    ALException = _imas_interface.lowlevel.ALException
+else:
+    ALException = None
+
+
+class UnknownDDVersion(ValueError):
+    """Error raised when an unknown DD version is specified."""
+
+    def __init__(self, version: str, available: List[str], note: str = "") -> None:
+        close_matches = difflib.get_close_matches(version, available, n=1)
+        if close_matches:
+            suggestions = f"Did you mean {close_matches[0]!r}?"
+        else:
+            suggestions = f"Available versions are {', '.join(reversed(available))}"
+        super().__init__(
+            f"Data dictionary version {version!r} cannot be found. {suggestions}{note}"
+        )
+
+
+class IDSNameError(ValueError):
+    """Error raised by DBEntry.get(_slice) when providing an invalid IDS name."""
+
+    def __init__(self, ids_name: str, factory: "IDSFactory") -> None:
+        suggestions = ""
+        close_matches = difflib.get_close_matches(ids_name, factory.ids_names(), n=1)
+        if close_matches:
+            suggestions = f" Did you mean {close_matches[0]!r}?"
+        super().__init__(f"IDS {ids_name!r} does not exist.{suggestions}")
+
+
+class DataEntryException(RuntimeError):
+    """Error raised by DBEntry for unexpected data in the backend."""
+
+
+class MDSPlusModelError(RuntimeError):
+    """Error raised when building MDS+ models."""
+
+    def __init__(self, msg: str) -> None:
+        super().__init__(f"Error building MDSplus data model: {msg}")
+
+
+class LowlevelError(RuntimeError):
+    """Error raised when lowlevel returns nonzero status"""
+
+    def __init__(self, function: str, status: int):
+        super().__init__(
+            f"An Access Layer lowlevel operation ({function}) was unsuccessful "
+            f"({status=}). "
+            "More debug information should be available earlier in the program output."
+        )
+
+
+class CoordinateLookupError(Exception):
+    """Error raised by IDSCoordinate.__getitem__ when a coordinate cannot be found."""
+
+
+class ValidationError(Exception):
+    """Error raised by IDSToplevel.validate() to indicate the IDS is not valid."""
+
+
+class CoordinateError(ValidationError):
+    """Error raised by ids.validate() to indicate a coordinate check has failed."""
+
+    def __init__(self, node, dimension, expected_size, coor_path):
+        """Create a new CoordinateError
+
+        Args:
+            node: IDSBase object that this coordinate error is raised for
+            dimension: (0-based) dimension with incorrect size
+            expected_size: size of the coordinate for the specified dimension
+            coor_path: path of the coordinate, may be None when a coordinate is of fixed
+                size (e.g. ``1...3``)
+        """
+        if coor_path is not None:  # Error message when coordinate size doesnt match
+            details = (
+                f"its coordinate in dimension {dimension + 1} (`{coor_path}`) has "
+                f"size {expected_size}."
+            )
+        else:
+            details = f"dimension {dimension + 1} must have size {expected_size}."
+        super().__init__(
+            f"Element `{node._path}` has incorrect shape {node.shape}: {details}"
+        )
+
+
+class InvalidNetCDFEntry(Exception):
+    """Error raised when loading an IDS from a NetCDF file that fails validation."""