Context Manager: with flushing(MainEngine()) as eng: (#449)

* Context Manager: with flushing(MainEngine()) as eng:

Simplify the creation, use, and flushing of any Engine using a Python context manager.

When exiting the `with` block, the engine is _automatically_ flushed.

Modeled after https://docs.python.org/3/library/contextlib.html#contextlib.closing
```python
from projectq import MainEngine, flushing  # import the main compiler engine
from projectq.ops import (
    H,
    Measure,
)  # import the operations we want to perform (Hadamard and measurement)

with flushing(MainEngine()) as eng:  # create a default compiler (the back-end is a simulator)
    qubit = eng.allocate_qubit()  # allocate a quantum register with 1 qubit

    H | qubit  # apply a Hadamard gate
    Measure | qubit  # measure the qubit

    # This line is no longer required... eng.flush()

print(f"Measured {int(qubit)}")  # converting a qubit to int or bool gives access to the measurement result

* Add tests

* Run linters/formatters on code

* Fix isort comment pragmas

* Really fix isort issues in cengines/__init__.py

Co-authored-by: Damien Nguyen <ngn.damien@gmail.com>

Author: cclauss

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+-   Python context manager `with flusing(MainEngine()) as eng:`
+
 ## [v0.8.0] - 2022-10-18
 
 ### Added

projectq/cengines/__init__.py

@@ -14,10 +14,14 @@
 
 """ProjectQ module containing all compiler engines."""
 
+from contextlib import contextmanager
+
 from ._basics import BasicEngine, ForwarderEngine, LastEngineException  # isort:skip
 from ._cmdmodifier import CommandModifier  # isort:skip
 from ._basicmapper import BasicMapperEngine  # isort:skip
 
+# isort: split
+
 from ._ibm5qubitmapper import IBM5QubitMapper
 from ._linearmapper import LinearMapper, return_swap_depth
 from ._main import MainEngine, NotYetMeasuredError, UnsupportedEngineError
@@ -33,3 +37,22 @@
 from ._tagremover import TagRemover
 from ._testengine import CompareEngine, DummyEngine
 from ._twodmapper import GridMapper
+
+
+@contextmanager
+def flushing(engine):
+    """
+    Context manager to flush the given engine at the end of the 'with' context block.
+
+    Example:
+        with flushing(MainEngine()) as eng:
+            qubit = eng.allocate_qubit()
+            ...
+
+    Calling 'eng.flush()' is no longer needed because the engine will be flushed at the
+    end of the 'with' block even if an exception has been raised within that block.
+    """
+    try:
+        yield engine
+    finally:
+        engine.flush()

projectq/cengines/_withflushing_test.py

@@ -0,0 +1,38 @@
+#   Copyright 2017 ProjectQ-Framework (www.projectq.ch)
+#
+#   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.
+"""Tests for projectq.cengines.__init__.py."""
+
+from unittest.mock import MagicMock
+
+from projectq.cengines import DummyEngine, flushing
+
+
+def test_with_flushing():
+    """Test with flushing() as eng:"""
+    with flushing(DummyEngine()) as engine:
+        engine.flush = MagicMock()
+        assert engine.flush.call_count == 0
+    assert engine.flush.call_count == 1
+
+
+def test_with_flushing_with_exception():
+    """Test with flushing() as eng: with an exception raised in the 'with' block."""
+    try:
+        with flushing(DummyEngine()) as engine:
+            engine.flush = MagicMock()
+            assert engine.flush.call_count == 0
+            raise ValueError("An exception is raised in the 'with' block")
+    except ValueError:
+        pass
+    assert engine.flush.call_count == 1