Fix merge conflicts

Author: Anthchirp

HISTORY.rst

@@ -2,90 +2,88 @@
 History
 =======
 
-2.2.0 (????-??-??)
+2.3.0 (????-??-??)
 ------------------
-
 * Python 3.6+ only, support for Python 3.5 has been dropped
 
+2.2.0 (2020-09-07)
+------------------
+* Calling the run() function with unnamed arguments (other than the command
+  list as the first argument) is now deprecated. As a number of arguments
+  will be removed in a future version the use of unnamed arguments will
+  cause future confusion. `Use explicit keyword arguments instead (#62). <https://github.com/DiamondLightSource/python-procrunner/pull/62>`_
+* `The run() function debug argument has been deprecated (#63). <https://github.com/DiamondLightSource/python-procrunner/pull/63>`_
+  This is only used to debug the NonBlockingStream* classes. Those are due
+  to be replaced in a future release, so the argument will no longer serve
+  a purpose. Debugging information remains available via standard logging
+  mechanisms.
+* Final version supporting Python 3.5
+
 2.1.0 (2020-09-05)
 ------------------
-
 * `Deprecated array access on the return object (#60). <https://github.com/DiamondLightSource/python-procrunner/pull/60>`_
   The return object will become a subprocess.CompletedProcess in a future
   release, which no longer allows array-based access. For a translation table
   of array elements to attributes please see the pull request linked above.
-* Add a `new parameter 'raise_timeout_exceptions' (#61). <https://github.com/DiamondLightSource/python-procrunner/pull/61>`_
+* Add a `new parameter 'raise_timeout_exception' (#61). <https://github.com/DiamondLightSource/python-procrunner/pull/61>`_
   When set to 'True' a subprocess.TimeoutExpired exception is raised when the
   process runtime exceeds the timeout threshold. This defaults to 'False' and
   will be set to 'True' in a future release.
-* Final version supporting Python 3.5
 
 2.0.0 (2020-06-24)
 ------------------
-
 * Python 3.5+ only, support for Python 2.7 has been dropped
 * Deprecated function alias run_process() has been removed
 * Fixed a stability issue on Windows
 
 1.1.0 (2019-11-04)
 ------------------
-
 * Add Python 3.8 support, drop Python 3.4 support
 
 1.0.2 (2019-05-20)
 ------------------
-
 * Stop environment override variables leaking into the process environment
 
 1.0.1 (2019-04-16)
 ------------------
-
 * Minor fixes on the return object (implement equality,
   mark as unhashable)
 
 1.0.0 (2019-03-25)
 ------------------
-
 * Support file system path objects (PEP-519) in arguments
 * Change the return object to make it similar to
   subprocess.CompletedProcess, introduced with Python 3.5+
 
 0.9.1 (2019-02-22)
 ------------------
-
 * Have deprecation warnings point to correct code locations
 
 0.9.0 (2018-12-07)
 ------------------
-
 * Trap UnicodeEncodeError when printing output. Offending characters
   are replaced and a warning is logged once. Hints at incorrectly set
   PYTHONIOENCODING.
 
 0.8.1 (2018-12-04)
 ------------------
-
 * Fix a few deprecation warnings
 
 0.8.0 (2018-10-09)
 ------------------
-
 * Add parameter working_directory to set the working directory
   of the subprocess
 
 0.7.2 (2018-10-05)
 ------------------
-
 * Officially support Python 3.7
 
 0.7.1 (2018-09-03)
 ------------------
-
 * Accept environment variable overriding with numeric values.
 
 0.7.0 (2018-05-13)
 ------------------
-
 * Unicode fixes. Fix crash on invalid UTF-8 input.
 * Clarify that stdout/stderr values are returned as bytestrings.
 * Callbacks receive the data decoded as UTF-8 unicode strings
@@ -95,23 +93,19 @@ History
 
 0.6.1 (2018-05-02)
 ------------------
-
 * Maintenance release to add some tests for executable resolution.
 
 0.6.0 (2018-05-02)
 ------------------
-
 * Fix Win32 API executable resolution for commands containing a dot ('.') in
   addition to a file extension (say '.bat').
 
 0.5.1 (2018-04-27)
 ------------------
-
 * Fix Win32API dependency installation on Windows.
 
 0.5.0 (2018-04-26)
 ------------------
-
 * New keyword 'win32resolve' which only takes effect on Windows and is enabled
   by default. This causes procrunner to call the Win32 API FindExecutable()
   function to try and lookup non-.exe files with the corresponding name. This
@@ -120,21 +114,17 @@ History
 
 0.4.0 (2018-04-23)
 ------------------
-
 * Python 2.7 support on Windows. Python3 not yet supported on Windows.
 
 0.3.0 (2018-04-17)
 ------------------
-
 * run_process() renamed to run()
 * Python3 compatibility fixes
 
 0.2.0 (2018-03-12)
 ------------------
-
 * Procrunner is now Python3 3.3-3.6 compatible.
 
 0.1.0 (2018-03-12)
 ------------------
-
 * First release on PyPI.

docs/conf.py

@@ -48,8 +48,8 @@
 
 # General information about the project.
 project = "ProcRunner"
-copyright = "2020, Markus Gerstel"
-author = "Markus Gerstel"
+copyright = "2020, Diamond Light Source"
+author = "Diamond Light Source - Scientific Software"
 
 # The version info for the project you're documenting, acts as replacement
 # for |version| and |release|, also used in various other places throughout
@@ -128,8 +128,8 @@
     (
         master_doc,
         "procrunner.tex",
-        "ProcRunner Documentation",
-        "Markus Gerstel",
+        "procrunner Documentation",
+        "Diamond Light Source - Scientific Software",
         "manual",
     )
 ]
@@ -139,7 +139,7 @@
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "procrunner", "ProcRunner Documentation", [author], 1)]
+man_pages = [(master_doc, "procrunner", "procrunner Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output ----------------------------------------
@@ -151,10 +151,10 @@
     (
         master_doc,
         "procrunner",
-        "ProcRunner Documentation",
+        "procrunner Documentation",
         author,
         "procrunner",
-        "One line description of project.",
+        "Versatile utility function to run external processes",
         "Miscellaneous",
     )
 ]

procrunner/__init__.py

@@ -1,4 +1,5 @@
 import codecs
+import functools
 import io
 import logging
 import os
@@ -52,7 +53,7 @@
 
 __author__ = """Markus Gerstel"""
 __email__ = "[email protected]"
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 
 logger = logging.getLogger("procrunner")
 logger.addHandler(logging.NullHandler())
@@ -209,7 +210,6 @@ def __init__(self, stream, data, debug=False, notify=None):
         self._buffer = data
         self._buffer_len = len(data)
         self._buffer_pos = 0
-        self._debug = debug
         self._max_block_len = 4096
         self._stream = stream
         self._terminated = False
@@ -413,10 +413,26 @@ def update(self, dictionary):
         self._extras.update(dictionary)
 
 
+def _deprecate_argument_calling(f):
+    @functools.wraps(f)
+    def wrapper(*args, **kwargs):
+        if len(args) > 1:
+            warnings.warn(
+                "Calling procrunner.run() with unnamed arguments (apart from "
+                "the command) is deprecated. Use keyword arguments instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return f(*args, **kwargs)
+
+    return wrapper
+
+
+@_deprecate_argument_calling
 def run(
     command,
     timeout=None,
-    debug=False,
+    debug=None,
     stdin=None,
     print_stdout=True,
     print_stderr=True,
@@ -436,7 +452,7 @@ def run(
 
     :param array command: Command line to be run, specified as array.
     :param timeout: Terminate program execution after this many seconds.
-    :param boolean debug: Enable further debug messages.
+    :param boolean debug: Enable further debug messages. (deprecated)
     :param stdin: Optional bytestring that is passed to command stdin.
     :param boolean print_stdout: Pass stdout through to sys.stdout.
     :param boolean print_stderr: Pass stderr through to sys.stderr.
@@ -470,6 +486,10 @@ def run(
     else:
         assert sys.platform != "win32", "stdin argument not supported on Windows"
         stdin_pipe = subprocess.PIPE
+    if debug is not None:
+        warnings.warn(
+            "Use of the debug parameter is deprecated", DeprecationWarning, stacklevel=3
+        )
 
     start_time = timeit.default_timer()
     if timeout is not None:
@@ -478,7 +498,7 @@ def run(
             warnings.warn(
                 "Using procrunner with timeout and without raise_timeout_exception set is deprecated",
                 DeprecationWarning,
-                stacklevel=2,
+                stacklevel=3,
             )
 
     if environment is not None:

requirements_dev.txt

@@ -1,10 +1,10 @@
 bump2version==1.0.0
-coverage==5.2.1
+coverage==5.3
 flake8==3.8.3
 mock==3.0.5
-pip==20.2.2
-pytest==6.0.1
+pip==20.2.3
+pytest==6.1.0
 Sphinx==3.2.1
-tox==3.19.0
+tox==3.20.0
 twine==1.15.0
 wheel==0.35.1

setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 2.1.0
+current_version = 2.2.0
 commit = True
 tag = True
 

setup.py

@@ -44,6 +44,6 @@
     test_suite="tests",
     tests_require=test_requirements,
     url="https://github.com/DiamondLightSource/python-procrunner",
-    version="2.1.0",
+    version="2.2.0",
     zip_safe=False,
 )