Make error handling part of the public interface

docs/source/conf.py

@@ -4,6 +4,6 @@
 release = "1.0.0"
 
 
-extensions = ["sphinx.ext.autodoc"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.doctest"]
 language = "python"
 html_theme = "sphinx_rtd_theme"

docs/source/error_handling.rst

@@ -0,0 +1,40 @@
+Error Handling
+==============
+
+Reading of ecl files will throw :py:class:`ecl_data_io.EclParsingError`
+when the given file does not contain valid ecl data:
+
+.. doctest::
+
+    >>> from ecl_data_io import read, write, EclParsingError, EclWriteError
+    >>> from io import StringIO
+    >>>
+    >>> file_contents = StringIO("Not valid ecl content")
+    >>> try:
+    ...   read(file_contents)
+    ... except EclParsingError as e:
+    ...   print(e)
+    Expected "'" before keyword, got N at 1
+
+Similarly, write will produce :py:class:`ecl_data_io.EclWriteError`
+when the given data is not suitable for writing.
+
+.. doctest::
+
+    >>> try:
+    ...   write("my_file.egrid", [("FILEHEAD", ["a"*100])])
+    ... except EclWriteError as e:
+    ...   print(e)
+    Could not convert numpy type <U100...
+
+
+For file and stream operations, the underlying exceptions from open(), read(), and
+write() are passed through:
+
+.. doctest::
+
+    >>> try:
+    ...   read("does_not_exist/my_file.egrid", [])
+    ... except OSError as e:
+    ...   print(e)
+    [Errno 2] No such file or directory...

docs/source/example_usage.rst

@@ -12,52 +12,61 @@ read
 The read function will open a given file and give you a list of tuples
 of the keywords and arrays.
 
+... testsetup::
+
+    >>> import ecl_data_io as eclio
+    >>>
+    >>> eclio.write(
+    ...     "my_grid.egrid",
+    ...     [
+    ...         ("FILEHEAD", []),
+    ...         ("GRIDHEAD", []),
+    ...         ("COORD", []),
+    ...         ("ZCORN", []),
+    ...         ("ACTNUM", []),
+    ...         ("MAPAXES", []),
+    ...     ],
+    ...     fileformat=eclio.Format.FORMATTED,
+    ... )
+
 >>> import ecl_data_io as eclio
 >>> for kw, arr in eclio.read("my_grid.egrid"):
-...     print(kw)
-"FILEHEAD"
-"GRIDHEAD"
-"COORD"
-"ZCORN"
-"ACTNUM"
-"MAPAXES"
+...     print(kw.strip())
+FILEHEAD
+GRIDHEAD
+COORD
+ZCORN
+ACTNUM
+MAPAXES
 
 write
 -----
 
 The :meth:`ecl_data_io.write` function will write such files
 from lists of keywords, array tuples:
 
->>> import ecl_data_io as eclio
->>> eclio.write("my_grid.egrid", ["FILEHEAD": [...], "GRIDHEAD": [10,10,10]])
+>>> eclio.write("my_grid.egrid", [("FILEHEAD", [1]), ("GRIDHEAD", [10,10,10])])
 
 The default format is is binary (unformatted), but it is possible to
 read and write ascii (formatted) aswell:
 
 
->>> import ecl_data_io as eclio
 >>> eclio.write(
->>>     "my_grid.egrid",
->>>     {"FILEHEAD": [...], "GRIDHEAD": [10,10,10]},
->>>     fileformat=eclio.Format.FORMATTED
->>> )
+...     "my_grid.fegrid",
+...     {"FILEHEAD": [1], "GRIDHEAD": [10,10,10]},
+...     fileformat=eclio.Format.FORMATTED
+... )
 
 lazy reading
 ------------
 
 It is possible to read through the file without loading all arrays into
 memory, ie. lazily:
 
-import ecl_data_io as eclio
-
->>> for item in eclio.lazy_read("my_grid.egrid"):
->>>     print(item.read_keyword())
-"FILEHEAD"
-"GRIDHEAD"
-"COORD"
-"ZCORN"
-"ACTNUM"
-"MAPAXES"
+>>> for item in eclio.lazy_read("my_grid.fegrid"):
+...     print(item.read_keyword())
+FILEHEAD
+GRIDHEAD
 
 
 Note that :meth:`ecl_data_io.lazy_read` in the above example is a generator of array
@@ -71,18 +80,15 @@ For better control, one can pass the opened file:
 ...     generator = eclio.lazy_read(f)
 ...     item = next(generator)
 ...     print(item.read_keyword())
-
-"FILEHEAD"
+FILEHEAD
 
 Writing MESS
 ------------
 
 The special MESS types keyword can be written as follows:
 
 
->>> from ecl_data_io.types import MESS
->>> from ecl_data_io import write, MESS
->>> write("output.EGRID", [("MESSHEAD", MESS)])
+>>> eclio.write("output.EGRID", [("MESSHEAD", eclio.MESS)])
 
 array types
 -----------
@@ -110,12 +116,10 @@ Say you want to update the first keyword name `"OLD_NAME"`, change the array
 to `new_array` and the name to `NEW_NAME`, then that can be done
 with the following:
 
->>> import ecl_data_io as eclio
->>>
->>> new_array = ...
+>>> new_array = [2]
 >>>
 >>> with open("my_grid.egrid", "br+") as f: # Open with read and write
 ...     for entry in eclio.lazy_read(f):
-...         if entry.read_keyword() == "OLD_NAME":
-...             entry.update(keyword="NEW_NAME", array=new_array)
+...         if entry.read_keyword() == "FILEHEAD":
+...             entry.update(keyword="FILEHEAD", array=new_array)
 ...             break

docs/source/index.rst

@@ -9,6 +9,7 @@ ecl-data-io: Low level IO for ecl files
 
    example_usage
    the_file_format
+   error_handling
    developer_guide
    api_doc
 
@@ -25,15 +26,32 @@ Quick Start Guide
 Using the library
 -----------------
 
+... testsetup::
+
+    >>> import ecl_data_io as eclio
+    >>>
+    >>> eclio.write(
+    ...     "my_grid.egrid",
+    ...     [
+    ...         ("FILEHEAD", []),
+    ...         ("GRIDHEAD", []),
+    ...         ("COORD", []),
+    ...         ("ZCORN", []),
+    ...         ("ACTNUM", []),
+    ...         ("MAPAXES", []),
+    ...     ],
+    ...     fileformat=eclio.Format.FORMATTED,
+    ... )
+
 >>> import ecl_data_io as eclio
 >>> for kw, arr in eclio.read("my_grid.egrid"):
-...     print(kw)
-"FILEHEAD"
-"GRIDHEAD"
-"COORD"
-"ZCORN"
-"ACTNUM"
-"MAPAXES"
+...     print(kw.strip())
+FILEHEAD
+GRIDHEAD
+COORD
+ZCORN
+ACTNUM
+MAPAXES
 
 
 For more see :ref:`example-usage`.

src/ecl_data_io/__init__.py

@@ -1,5 +1,6 @@
 import ecl_data_io.version
 
+from .errors import EclParsingError, EclWriteError
 from .format import Format
 from .read import lazy_read, read
 from .types import MESS
@@ -10,4 +11,12 @@
 
 __version__ = ecl_data_io.version.version
 
-__all__ = ["read", "lazy_read", "write", "Format", "MESS"]
+__all__ = [
+    "read",
+    "lazy_read",
+    "write",
+    "Format",
+    "MESS",
+    "EclParsingError",
+    "EclWriteError",
+]

src/ecl_data_io/_unformatted/write.py

@@ -68,9 +68,9 @@ def write_str_list(stream, str_list, ecl_type):
         return
     max_len = max(len(s) for s in str_list)
     if max_len > 99:
-        raise ValueError("Ecl files does not support strings of length > 99")
+        raise EclWriteError("Ecl files does not support strings of length > 99")
     if max_len > str_size:
-        raise ValueError(
+        raise EclWriteError(
             f"Inconsistent type size, have {str_size} type but longest string is {max_len}"
         )
     str_list = [s.ljust(str_size) for s in str_list]
@@ -79,7 +79,7 @@ def write_str_list(stream, str_list, ecl_type):
             s.encode("ascii") if isinstance(s, str) else s for s in str_list
         ]
     except UnicodeEncodeError as e:
-        raise ValueError(
+        raise EclWriteError(
             "Cannot write non-ascii strings to unformatted ecl files"
         ) from e
 
@@ -100,7 +100,10 @@ def write_str_list(stream, str_list, ecl_type):
 
 def write_array_like(stream, keyword, array_like):
     array = np.asarray(array_like)
-    ecl_type = ecl_types.from_np_dtype(array)
+    try:
+        ecl_type = ecl_types.from_np_dtype(array)
+    except ValueError as e:
+        raise EclWriteError(f"{e}") from e
     if ecl_type == b"MESS":
         write_array_header(stream, keyword, ecl_type, 0)
         array = np.array([])

src/ecl_data_io/errors.py

@@ -1,12 +1,12 @@
-class EclParsingError(Exception):
+class EclParsingError(ValueError):
     """
     Indicates an error occurred during reading of an ecl file.
     """
 
     pass
 
 
-class EclWriteError(Exception):
+class EclWriteError(ValueError):
     """
     Indicates an error occurred during writing of an ecl file.
     """

src/ecl_data_io/read.py

@@ -38,6 +38,17 @@ def lazy_read(filelike, fileformat=None):
     :param fileformat: Either ecl_data_io.Format.FORMATTED for ascii
         format, ecl_data_io.Format.UNFORMATTED for binary formatted files
         or None for guess.
+
+    :raises ecl_data_io.EclParsingError: If the file is not a valid
+        ecl file.
+
+    .. note::
+        If given a file to be open (as opposed to a stream), the errors
+        (various `IOError` s) associated with the default behavior of the
+        built-in `open()` function may be raised.
+
+        When given a stream, the exceptions associated with the stream will
+        pass through.
     """
     if fileformat is None:
         fileformat = guess_format(filelike)

src/ecl_data_io/write.py

@@ -19,6 +19,17 @@ def write(filelike, contents, fileformat=Format.UNFORMATTED):
         will be converted according to ecl_data_io.types.to_np_type
     :param fileformat: Either ecl_data_io.Format.FORMATTED for ascii
         format or ecl_data_io.Format.UNFORMATTED for binary format.
+
+    :raises ecl_data_io.EclWriteError: If the given contents cannot be
+        written to an ecl file.
+
+    .. note::
+        If given a file to be open (as opposed to a stream), the errors
+        (various `IOError` s) associated with the default behavior of the
+        built-in `open()` function may be raised.
+
+        When given a stream, the exceptions associated with the stream will
+        pass through.
     """
     stream, didopen = get_stream(filelike, fileformat, mode="w")
 

tox.ini

@@ -7,7 +7,7 @@ envlist =
 [testenv]
 deps =
     -rdev-requirements.txt
-commands = python -m pytest tests
+commands = python -m pytest
 
 [testenv:style]
 deps = pre-commit
@@ -23,6 +23,8 @@ commands =
 addopts =
     -ra
     --durations=5
+    --doctest-glob="*.rst"
+    --doctest-modules
 
 [gh-actions]
 python =