Add experimental support for verbose output and writing stderr to file

Author: Dekker1

CHANGELOG.rst

@@ -13,6 +13,10 @@ Added
 ^^^^^
 - Support for Python 3.9. (MiniZinc Python will aim to support all versions of
   Python that are not deprecated)
+- Experimental support for capturing the error output of the MiniZinc process
+  in ``CLIInstance``.
+- Experimental support for verbose compiler and solver output (using the ``-v``
+  flag) in ``CLIInstance``.
 
 Changed
 ^^^^^^^

docs/advanced_usage.rst

@@ -344,3 +344,53 @@ The generated file will contain all remote calls to the MiniZinc executable:
     DEBUG:minizinc:CLIInstance:analyse -> output fields: [('q', typing.List[int]), ('_checker', <class 'str'>)]
     DEBUG:asyncio:Using selector: KqueueSelector
     DEBUG:minizinc:CLIDriver:create_process -> program: /Applications/MiniZincIDE.app/Contents/Resources/minizinc args: "--solver [email protected] --allow-multiple-assignments --output-mode json --output-time --output-objective --output-output-item -s nqueens.mzn /var/folders/gj/cmhh026j5ddb28sw1z95pygdy5kk20/T/mzn_datamnhikzwo.json"
+
+
+If MiniZinc Python instances are instantiated directly from Python, then the
+CLI driver will generate temporary files to use with the created MiniZinc
+process. When something seems wrong with MiniZinc Python it is often a good
+idea to retrieve these objects to both check if the files are generated
+correctly and to recreate the exact MiniZinc command that is ran. For a
+``CLIInstance`` object, you can use the ``files()`` method to generate the
+files. You can then inspect or copy these files:
+
+..  code-block:: python
+
+    import minizinc
+    from pathlib import Path
+
+    model = minizinc.Model(["nqueens.mzn"])
+    solver = minizinc.Solver.lookup("gecode")
+    instance = minizinc.Instance(solver, model)
+    instance["n"] = 9
+
+    with instance.files() as files:
+        store = Path("./tmp")
+        store.mkdir()
+        for f in files:
+            f.link_to(store / f.name)
+
+
+Finally, if you are looking for bugs related to the behaviour of MiniZinc,
+solvers, or solver libraries, then it could be helpful to have a look at the
+direct MiniZinc output on ``stderr``.  The ``CLIInstance`` class now has
+experimental support for to write the output from ``stderr`` to a file and to
+enable verbose compilation and solving (using the command line ``-v`` flag).
+The former is enable by providing a ``pathlib.Path`` object as the
+``debug_output`` parameter to any solving method. Similarly, the verbose flag
+is triggered by setting the ``verbose`` parameter to ``True``. The following
+fragment shows capture the verbose output of a model that contains trace
+statements (which are also captured on ``stderr``):
+
+..  code-block:: python
+
+    import minizinc
+    from pathlib import Path
+
+    gecode = minizinc.Solver.lookup("gecode")
+    instance = minizinc.Instance(gecode)
+    instance.add_string("""
+        constraint trace("--- TRACE: This is a trace statement\\n");
+    """)
+
+    instance.solve(verbose=True, debug_output=Path("./debug_output.txt"))

src/minizinc/CLI/instance.py

@@ -10,6 +10,7 @@
 import sys
 import tempfile
 import warnings
+from asyncio import StreamReader
 from dataclasses import field, make_dataclass
 from datetime import datetime, timedelta
 from enum import EnumMeta
@@ -253,7 +254,8 @@ async def solutions(
         intermediate_solutions=False,
         free_search: bool = False,
         optimisation_level: Optional[int] = None,
-        ignore_errors=False,
+        verbose: bool = False,
+        debug_output: Optional[Path] = None,
         **kwargs,
     ):
         # Set standard command line arguments
@@ -319,6 +321,9 @@ async def solutions(
         if timeout is not None:
             cmd.extend(["--time-limit", str(int(timeout.total_seconds() * 1000))])
 
+        if verbose:
+            cmd.append("-v")
+
         for flag, value in kwargs.items():
             if not flag.startswith("-"):
                 flag = "--" + flag
@@ -334,35 +339,23 @@ async def solutions(
             cmd.extend(files)
             # Run the MiniZinc process
             proc = await self._driver.create_process(cmd, solver=solver)
-            assert proc.stderr is not None
-            assert proc.stdout is not None
+            assert isinstance(proc.stderr, StreamReader)
+            assert isinstance(proc.stdout, StreamReader)
+
+            # Python 3.7+: replace with asyncio.create_task
+            read_stderr = asyncio.ensure_future(_read_all(proc.stderr))
 
             status = Status.UNKNOWN
             code = 0
-            deadline = None
-            if timeout is not None:
-                deadline = datetime.now() + timeout + timedelta(seconds=5)
 
             remainder: Optional[bytes] = None
             try:
-                raw_sol: bytes = b""
-                while not proc.stdout.at_eof():
-                    try:
-                        if deadline is None:
-                            raw_sol += await proc.stdout.readuntil(SEPARATOR)
-                        else:
-                            t = deadline - datetime.now()
-                            raw_sol += await asyncio.wait_for(
-                                proc.stdout.readuntil(SEPARATOR), t.total_seconds()
-                            )
-                        status = Status.SATISFIED
-                        solution, statistics = parse_solution(
-                            raw_sol, self.output_type, self._enum_map
-                        )
-                        yield Result(Status.SATISFIED, solution, statistics)
-                        raw_sol = b""
-                    except asyncio.LimitOverrunError as err:
-                        raw_sol += await proc.stdout.readexactly(err.consumed)
+                async for raw_sol in _seperate_solutions(proc.stdout, timeout):
+                    status = Status.SATISFIED
+                    solution, statistics = parse_solution(
+                        raw_sol, self.output_type, self._enum_map
+                    )
+                    yield Result(Status.SATISFIED, solution, statistics)
 
                 code = await proc.wait()
             except asyncio.IncompleteReadError as err:
@@ -391,9 +384,14 @@ async def solutions(
                     )
                     yield Result(status, solution, statistics)
                 # Raise error if required
+                stderr = None
                 if code != 0 or status == Status.ERROR:
-                    stderr = await proc.stderr.read()
+                    stderr = await read_stderr
                     raise parse_error(stderr)
+                if debug_output is not None:
+                    if stderr is None:
+                        stderr = await read_stderr
+                    debug_output.write_bytes(stderr)
 
     async def solve_async(
         self,
@@ -514,3 +512,34 @@ def add_file(self, file: ParPath, parse_data: bool = True) -> None:
     def add_string(self, code: str) -> None:
         self._reset_analysis()
         return super().add_string(code)
+
+
+async def _seperate_solutions(stream: StreamReader, timeout: Optional[timedelta]):
+    deadline = None
+    if timeout is not None:
+        deadline = datetime.now() + timeout + timedelta(seconds=1)
+    solution: bytes = b""
+    while not stream.at_eof():
+        try:
+            if deadline is None:
+                solution += await stream.readuntil(SEPARATOR)
+            else:
+                t = deadline - datetime.now()
+                solution += await asyncio.wait_for(
+                    stream.readuntil(SEPARATOR), t.total_seconds()
+                )
+            yield solution
+            solution = b""
+        except asyncio.LimitOverrunError as err:
+            solution += await stream.readexactly(err.consumed)
+
+
+async def _read_all(stream: StreamReader):
+    output: bytes = b""
+    while not stream.at_eof():
+        try:
+            output += await stream.read()
+            return output
+        except asyncio.LimitOverrunError as err:
+            output += await stream.readexactly(err.consumed)
+    return output

src/minizinc/instance.py

@@ -170,7 +170,6 @@ async def solutions(
         intermediate_solutions=False,
         free_search: bool = False,
         optimisation_level: Optional[int] = None,
-        ignore_errors=False,
         **kwargs,
     ):
         """An asynchronous generator for solutions of the MiniZinc instance.