Fix REXPaint error handling and deprecate an old function.

Author: HexDecimal

CHANGELOG.rst

@@ -8,6 +8,12 @@ v2.0.0
 
 Unreleased
 ------------------
+Deprecated
+ - `tcod.console_load_xp` has been deprecated, `tcod.console_from_xp` can load
+   these files without modifying an existing console.
+
+Fixed
+ - `tcod.console_from_xp` now has better error handling (instead of crashing.)
 
 11.18.2 - 2020-12-03
 --------------------

tcod/_internal.py

@@ -63,12 +63,19 @@ def _raise_tcod_error() -> NoReturn:
 
 
 def _check(error: int) -> int:
-    """Detect and convert a libtcod error code it into an exception."""
+    """Detect and convert a libtcod error code into an exception."""
     if error < 0:
         _raise_tcod_error()
     return error
 
 
+def _check_p(pointer: Any) -> Any:
+    """Treats NULL pointers as errors and raises a libtcod exception."""
+    if not pointer:
+        _raise_tcod_error()
+    return pointer
+
+
 def _check_warn(error: int, stacklevel: int = 2) -> int:
     """Like _check, but raises a warning on positive error codes."""
     if _check(error) > 0:

tcod/libtcodpy.py

@@ -33,6 +33,7 @@
     _bytes,
     _CDataWrapper,
     _check,
+    _check_p,
     _check_warn,
     _console,
     _fmt,
@@ -1853,8 +1854,12 @@ def console_from_file(filename: str) -> tcod.console.Console:
 
     Returns: A new :any`Console` instance.
     """
+    if not os.path.exists(filename):
+        raise RuntimeError(
+            "File not found:\n\t%s" % (os.path.realpath(filename),)
+        )
     return tcod.console.Console._from_cdata(
-        lib.TCOD_console_from_file(filename.encode("utf-8"))
+        _check_p(lib.TCOD_console_from_file(filename.encode("utf-8")))
     )
 
 
@@ -2068,8 +2073,14 @@ def console_save_apf(con: tcod.console.Console, filename: str) -> bool:
     )
 
 
+@deprecate("Use tcod.console_from_xp to load this file.")
 def console_load_xp(con: tcod.console.Console, filename: str) -> bool:
-    """Update a console from a REXPaint `.xp` file."""
+    """Update a console from a REXPaint `.xp` file.
+
+    .. deprecated:: 11.18
+        Functions modifying console objects in-place are deprecated.
+        Use :any:`tcod.console_from_xp` to load a Console from a file.
+    """
     return bool(
         lib.TCOD_console_load_xp(_console(con), filename.encode("utf-8"))
     )
@@ -2088,15 +2099,23 @@ def console_save_xp(
 
 def console_from_xp(filename: str) -> tcod.console.Console:
     """Return a single console from a REXPaint `.xp` file."""
+    if not os.path.exists(filename):
+        raise RuntimeError(
+            "File not found:\n\t%s" % (os.path.realpath(filename),)
+        )
     return tcod.console.Console._from_cdata(
-        lib.TCOD_console_from_xp(filename.encode("utf-8"))
+        _check_p(lib.TCOD_console_from_xp(filename.encode("utf-8")))
     )
 
 
 def console_list_load_xp(
     filename: str,
 ) -> Optional[List[tcod.console.Console]]:
     """Return a list of consoles from a REXPaint `.xp` file."""
+    if not os.path.exists(filename):
+        raise RuntimeError(
+            "File not found:\n\t%s" % (os.path.realpath(filename),)
+        )
     tcod_list = lib.TCOD_console_list_from_xp(filename.encode("utf-8"))
     if tcod_list == ffi.NULL:
         return None