{
    "info": {
        "author": "Andy Robb",
        "author_email": "andy@andyrobb.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "Environment :: Console",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: MIT License",
            "Operating System :: POSIX",
            "Programming Language :: Python :: 2",
            "Programming Language :: Python :: 2.7",
            "Topic :: Utilities"
        ],
        "description": "Python ProcessRunner\n====================\nDesigned to make reading from external processes easier. Does not permit interactive communication with the process, but rather provides (usually) simplified consumption of process output, especially targeted at logging use cases.\n\nOutput can be sent to multiple locations. E.g. the stdout and stderr of an external process can be written to one or multiple files, AND also to the pipes of the local process.\n\nSeveral convenience functions simplify common use cases. All the classes and functions take the command to execute in the subprocess.Popen/.call format, a list of strings starting with the command name, followed by any arguments for that command.\n\n\nProvided classes\n================\nProcessRunner\n  The ProcessRunner class uses subprocess.Popen. It does not use the ``shell=True`` flag. All processes started by the class are saved in ``PROCESSRUNNER_PROCESSES``. A list of currently active processes started by the class can be retrieved by calling ``getActiveProcesses()``, which IS NOT a class member.\n\n  *Parameters*\n    - **command** REQUIRED ``[string,]`` The command to execute along with all parameters.\n    - **cwd** OPTIONAL ``string`` Directory to switch into before execution. CWD does not apply to the location of the process executable itself, which must be on PATH or called with an absolute path.\n\n  *Properties*\n    - Non-blocking: Returns immediately; the external process is managed in a new thread\n\nProcessRunner class methods\n---------------------------\ncollectLines\n  Obtains all output from stdout, stderr, or both in a list.\n\n  *Parameters*\n    - **procPipeName** OPTIONAL ``string`` One of stdout or stderr. If neither is provided, the output of both pipes will be collected.\n\n  *Properties*\n    - Blocking: Returns once the external command exits.\n\ngetCommand\n  Returns the ``[string,]`` originally provided as the ``command`` parameter to ``ProcessRunner``.\n\n  *Parameters*\n    - None\n\n  *Properties*\n    - None\n\ngetLineFromPipe\n  Obtain one line from a pipe client.\n\n  *Parameters*\n    - **clientId** REQUIRED ``string`` Pipe manager client queue ID.\n    - **procPipeName** REQUIRED ``string`` One of stdout or stderr.\n\n  *Properties*\n    - Blocking\n\ngetPopen\n  Obtain the underlying ``subprocess.Popen`` instance.\n\n  *Parameters*\n    - None\n\n  *Properties*\n    - None\n\nisAlive\n  Returns ``True`` if the external process is still running, else retuns ``False``.\n\n  *Parameters*\n    - None\n\n  *Properties*\n    - None\n\nisQueueEmpty\n  Returns ``True`` if there are no lines in the queue for a given pipe client, otherwise returns ``False``.\n\n  *Parameters*\n    - **clientId** REQUIRED ``string`` Pipe manager client queue ID.\n    - **procPipeName** REQUIRED ``string`` One of stdout or stderr.\n\n  *Properties*\n\nkillCommand\n  Send SIGKILL to the main process (the command).\n\n  *Parameters*\n    - None\n\n  *Properties*\n    - None\n\nmapLines\n  Run a function against each line presented by one pipe manager.\n  Returns a reference to a ``dict`` that can be used to monitor the status of\n  the function. When the process is dead, the queues are empty, and all lines\n  are processed, the dict will be updated (the value will be changed from ``False`` to ``True``). This can be used as a blocking\n  mechanism by functions invoking mapLines.\n  Status dict format: ``{\"complete\":bool}``\n\n  *Parameters*\n    - **func** REQUIRED ``function`` A function that takes one parameter, the line from the pipe and returns the line with any desired changes.\n    - **procPipeName** REQUIRED ``string`` One of \"stdout\" or \"stderr\".\n\n  *Properties*\n    - Non-blocking: Returns immediately.\n    - Returns a dict reference that is used to determine completion.\n\npoll\n  A proxy to the underlying ``subprocess.Popen.poll`` method. Returns ``NoneType`` if the external process is alive, otherwise the exit code as an ``int``.\n\n  *Parameters*\n    - None\n\n  *Properties*\n    - None\n\nregisterForClientQueue\n  Register to get a client queue on a pipe manager. The ID for the queue is\n  returned from the method as a string.\n\n  *Parameters*\n    - **procPipeName** REQUIRED ``string`` One of \"stdout\" or \"stderr\".\n\n  *Properties*\n    - None\n\nshutdown\n  Shutdown the process managers. Run after verifying terminate/kill has destroyed any child processes. Should be run following the successful completion of the ``terminate`` or ``killCommand`` methods to clear any lingering process entries.\n\n  *Parameters*\n    - None\n\n  *Properties*\n    - Blocking: Returns when the internal process managers stop.\n\nterminate\n  Terminate both the main process and reader queues.\n\n  *Parameters*\n    - **timeoutMs** OPTIONAL ``int`` Milliseconds ``terminate`` should wait for main process to exit before raising an error.\n\n  *Properties*\n    - Blocking: Returns when the main process exits; if the timeout occurs, terminate raises a basic ``Exception``.\n\nunRegisterClientQueue\n  Unregister a client queue from a pipe manager. Prevents clients from waiting on other clients that will never perform additional reads.\n\n  *Parameters*\n    - **procPipeName** REQUIRED ``string`` One of \"stdout\" or \"stderr\".\n    - **clientId** REQUIRED ``string`` ID of the client queue on this pipe manager.\n\n  *Properties*\n    - None\n\nwait\n  Block until the external process exits and pipe managers have finished reading from the external pipes.\n\n  *Parameters*\n    - None\n\n  *Properties*\n    - Chainable\n\nwhich\n  Verify a given command exists. Returns absolute path to exec as a string, or None if not found.\n\n  *Parameters*\n    - **program** REQUIRED ``string`` The name or full path to desired executable.\n\n  *Properties*\n    - Static\n\n\nProvided convenience functions\n==============================\nrunCommand\n  The runCommand function returns the process exit code, and stdout and stderr are connected to local stdout and stderr.\n\n  *Parameters*\n    - **command** REQUIRED ``[string,]`` The command to execute along with all parameters.\n    - **outputPrefix** OPTIONAL ``string`` String to prepend to all output lines. Defaults to 'ProcessRunner> '.\n\n  *Properties*\n    - Blocking: Returns once the external command exits.\n\nssh\n  The ssh function runs a command on a remote host, and returns the SSH exit code. stdout and stderr are connected to local stdout and stderr.\n\n  *Parameters*\n    - **remoteAddress** REQUIRED ``string`` IP or hostname for target system.\n    - **remotecommand** REQUIRED ``string`` The command to run on the target system.\n    - **outputPrefix** OPTIONAL ``string`` String to prepend to all output lines. Defaults to 'ssh> '.\n\n  *Properties*\n    - Blocking: Returns once the external command exits.\n\nWriteOut\n  The WriteOut function is used to prepend lines from the external process with a given string. Given a pipe and a string, it returns a function that accepts a line of text, then writes that line to the provided pipe, prepended with a user provided string. Useful when handling output from processes directly. See example use below.\n\n  *Parameters*\n    - **pipe** REQUIRED ``pipe`` A system pipe to write the output to.\n    - **outputPrefix** REQUIRED ``string`` A string to prepend to each line.\n      - This can also be any object that can be cast to a string.\n\n  *Properties*\n    - Return type is a function.\n\ngetActiveProcesses\n  The getActiveProcesses function returns a list of ``ProcessRunner`` instances that are currently alive.\n\n  *Takes no parameters*\n\n\nCustom Exceptions\n=================\nCommandNotFound\n  Exception thrown when the command to execute isn't available.\n\n\nExamples\n==============\n\nSimple\n------\nUse SCP to copy a local file to a remote host, using SSH key-based authentication.\n\n::\n\n  # Run a command, wait for it to complete, and gather its return code\n  command = [\"scp\", \"-o\", \"BatchMode=yes\", \"-o\", \"StrictHostKeyChecking=no\", \"/path/to/local/file\", clientAddress+\":/tmp/\"]\n  result = ProcessRunner(command).wait().poll()\n\nComplex\n-------\nExecute a command and while it runs write lines from the external process stdout and stderr to both the corresponding local pipes, as well as corresponding files. Further, prefix the local pipe output with dedicated notes, and prefix the file output with timestamps.\n\n::\n\n  # Logging files\n  stdoutFile = open(workingDir+'/stdout.txt', 'a')\n  stderrFile = open(workingDir+'/stderr.txt', 'a')\n\n  # Date/time notation for output lines in files\n  class DateNote:\n      def init(self):\n          pass\n      def __repr__(self):\n          return datetime.now().isoformat() + \" \"\n\n  # Start the process\n  proc = ProcessRunner(command)\n\n  # Attach output mechanisms to the process's output pipes. These are handled asynchronously, so you can see the output while it is happening\n  # Write to the console's stdout and stderr, with custom prefixes for each\n  proc.mapLines(WriteOut(pipe=sys.stdout, outputPrefix=\"validation-stdout> \"), procPipeName=\"stdout\")\n  proc.mapLines(WriteOut(pipe=sys.stderr, outputPrefix=\"validation-stderr> \"), procPipeName=\"stderr\")\n\n  # Write to the log files, prepending each line with a date/time stamp\n  proc.mapLines(WriteOut(pipe=stdoutFile, outputPrefix=DateNote()), procPipeName=\"stdout\")\n  proc.mapLines(WriteOut(pipe=stderrFile, outputPrefix=DateNote()), procPipeName=\"stderr\")\n\n  # Block regular execution until the process finishes\n  result = proc.wait().poll()\n\n  # Wait until the queues are emptied to close the files\n  while not proc.areAllQueuesEmpty():\n      time.sleep(0.01)\n\n  stdoutFile.close()\n  stderrFile.close()",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/arobb/python-processrunner",
        "keywords": "external process execution",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "processrunner",
        "package_url": "https://pypi.org/project/processrunner/",
        "platform": "",
        "project_url": "https://pypi.org/project/processrunner/",
        "project_urls": {
            "Homepage": "https://github.com/arobb/python-processrunner"
        },
        "release_url": "https://pypi.org/project/processrunner/2.1.1/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Easily trigger and manage output from external processes.",
        "version": "2.1.1"
    },
    "last_serial": 3708812,
    "releases": {
        "1.0.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8b738786e0bd77ca54633dd14a9eda75",
                    "sha256": "29543856f05958cd44267f479134b44295bfdc00293bf73121cbc4bca437594d"
                },
                "downloads": -1,
                "filename": "processrunner-1.0.3.tar.gz",
                "has_sig": true,
                "md5_digest": "8b738786e0bd77ca54633dd14a9eda75",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10170,
                "upload_time": "2017-05-12T19:06:49",
                "url": "https://files.pythonhosted.org/packages/78/2c/0c62be311744ec439dbaabfad5a092a697f534e9936c4022de8f20a3a84c/processrunner-1.0.3.tar.gz"
            }
        ],
        "2.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "cc6b646256d2de0e81a6c62002f87dff",
                    "sha256": "811c429a3d342f48ef38700ff0ecc9bc6be0606eddad9ceda8afe229d5323bb3"
                },
                "downloads": -1,
                "filename": "processrunner-2.0.0.tar.gz",
                "has_sig": true,
                "md5_digest": "cc6b646256d2de0e81a6c62002f87dff",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 14570,
                "upload_time": "2017-10-02T03:39:03",
                "url": "https://files.pythonhosted.org/packages/e2/07/92fd10ef883af797333663cb20673be6ec50fe2e919a9ae007c27b65fce3/processrunner-2.0.0.tar.gz"
            }
        ],
        "2.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "cf62f864ff7ec5e6c83b465d5c978f02",
                    "sha256": "aaa2be212eb930eae90c49c7b4ff13fae2ee3dd550df3027a575ccb9c78bc017"
                },
                "downloads": -1,
                "filename": "processrunner-2.1.1.tar.gz",
                "has_sig": true,
                "md5_digest": "cf62f864ff7ec5e6c83b465d5c978f02",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 16344,
                "upload_time": "2018-03-27T03:14:32",
                "url": "https://files.pythonhosted.org/packages/08/55/e239121bbba33404923d06f227b514bbceab7c473c235498f56bad24b029/processrunner-2.1.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "cf62f864ff7ec5e6c83b465d5c978f02",
                "sha256": "aaa2be212eb930eae90c49c7b4ff13fae2ee3dd550df3027a575ccb9c78bc017"
            },
            "downloads": -1,
            "filename": "processrunner-2.1.1.tar.gz",
            "has_sig": true,
            "md5_digest": "cf62f864ff7ec5e6c83b465d5c978f02",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 16344,
            "upload_time": "2018-03-27T03:14:32",
            "url": "https://files.pythonhosted.org/packages/08/55/e239121bbba33404923d06f227b514bbceab7c473c235498f56bad24b029/processrunner-2.1.1.tar.gz"
        }
    ]
}