invoke 2.2.1__tar.gz → 3.0.0__tar.gz

{invoke-2.2.1 → invoke-3.0.0}/MANIFEST.in

@@ -1,10 +1,10 @@
 include LICENSE
 include README.rst
 include tasks.py
+include pyproject.toml
 recursive-include invoke/completion *
 recursive-include sites *
 recursive-exclude sites/*/_build *
-include dev-requirements.txt
 recursive-include * py.typed
 recursive-include tests *
 recursive-exclude * *.pyc *.pyo

{invoke-2.2.1/invoke.egg-info → invoke-3.0.0}/PKG-INFO

@@ -1,21 +1,18 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: invoke
-Version: 2.2.1
+Version: 3.0.0
 Summary: Pythonic task execution
-Home-page: https://pyinvoke.org
-Author: Jeff Forcier
-Author-email: jeff@bitprophet.org
-License: BSD
+Author-email: Jeff Forcier <jeff@bitprophet.org>
+License-Expression: BSD-2-Clause
 Project-URL: Docs, https://docs.pyinvoke.org
 Project-URL: Source, https://github.com/pyinvoke/invoke
-Project-URL: Issues, https://github.com/pyinvoke/invoke/issues
 Project-URL: Changelog, https://www.pyinvoke.org/changelog.html
 Project-URL: CI, https://app.circleci.com/pipelines/github/pyinvoke/invoke
+Project-URL: Issues, https://github.com/pyinvoke/invoke/issues
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
-Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: POSIX
 Classifier: Operating System :: Unix
 Classifier: Operating System :: MacOS :: MacOS X
@@ -23,21 +20,22 @@ Classifier: Operating System :: Microsoft :: Windows
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Build Tools
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Software Distribution
 Classifier: Topic :: System :: Systems Administration
-Requires-Python: >=3.6
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
 License-File: LICENSE
-
+Dynamic: license-file
 
 |version| |python| |license| |ci| |coverage|
 
@@ -60,18 +58,17 @@ License-File: LICENSE
 Welcome to Invoke!
 ==================
 
-Invoke is a Python (2.7 and 3.4+) library for managing shell-oriented
-subprocesses and organizing executable Python code into CLI-invokable tasks. It
-draws inspiration from various sources (``make``/``rake``, Fabric 1.x, etc) to
-arrive at a powerful & clean feature set.
+Invoke is a Python library for managing shell-oriented subprocesses and
+organizing executable Python code into CLI-invokable tasks. It draws
+inspiration from various sources (``make``/``rake``, Fabric 1.x, etc) to arrive
+at a powerful & clean feature set.
 
 To find out what's new in this version of Invoke, please see `the changelog
 <https://pyinvoke.org/changelog.html#{}>`_.
 
-The project maintainer keeps a `roadmap
-<https://bitprophet.org/projects#roadmap>`_ on his website.
-
-
 For a high level introduction, including example code, please see `our main
 project website <https://pyinvoke.org>`_; or for detailed API docs, see `the
 versioned API website <https://docs.pyinvoke.org>`_.
+
+The project maintainer keeps a `roadmap
+<https://bitprophet.org/projects#roadmap>`_ on his website.

{invoke-2.2.1 → invoke-3.0.0}/README.rst

@@ -19,13 +19,17 @@
 Welcome to Invoke!
 ==================
 
-Invoke is a Python (2.7 and 3.4+) library for managing shell-oriented
-subprocesses and organizing executable Python code into CLI-invokable tasks. It
-draws inspiration from various sources (``make``/``rake``, Fabric 1.x, etc) to
-arrive at a powerful & clean feature set.
+Invoke is a Python library for managing shell-oriented subprocesses and
+organizing executable Python code into CLI-invokable tasks. It draws
+inspiration from various sources (``make``/``rake``, Fabric 1.x, etc) to arrive
+at a powerful & clean feature set.
 
 To find out what's new in this version of Invoke, please see `the changelog
 <https://pyinvoke.org/changelog.html#{}>`_.
 
+For a high level introduction, including example code, please see `our main
+project website <https://pyinvoke.org>`_; or for detailed API docs, see `the
+versioned API website <https://docs.pyinvoke.org>`_.
+
 The project maintainer keeps a `roadmap
 <https://bitprophet.org/projects#roadmap>`_ on his website.

{invoke-2.2.1 → invoke-3.0.0}/invoke/__init__.py

@@ -1,6 +1,6 @@
-from typing import Any, Optional
+from importlib import metadata
+from typing import Any
 
-from ._version import __version_info__, __version__  # noqa
 from .collection import Collection  # noqa
 from .config import Config  # noqa
 from .context import Context, MockContext  # noqa
@@ -8,6 +8,7 @@ from .exceptions import (  # noqa
     AmbiguousEnvVar,
     AuthFailure,
     CollectionNotFound,
+    CommandTimedOut,
     Exit,
     ParseError,
     PlatformError,
@@ -19,19 +20,20 @@ from .exceptions import (  # noqa
     UnknownFileType,
     UnpicklableConfigMember,
     WatcherError,
-    CommandTimedOut,
 )
 from .executor import Executor  # noqa
 from .loader import FilesystemLoader  # noqa
 from .parser import Argument, Parser, ParserContext, ParseResult  # noqa
 from .program import Program  # noqa
-from .runners import Runner, Local, Failure, Result, Promise  # noqa
-from .tasks import task, call, Call, Task  # noqa
+from .runners import Failure, Local, Promise, Result, Runner  # noqa
+from .tasks import Call, Task, call, task  # noqa
 from .terminals import pty_size  # noqa
 from .watchers import FailingResponder, Responder, StreamWatcher  # noqa
 
+__version__ = metadata.version("invoke")
+
 
-def run(command: str, **kwargs: Any) -> Optional[Result]:
+def run(command: str, **kwargs: Any) -> Result:
     """
     Run ``command`` in a subprocess and return a `.Result` object.
 
@@ -50,7 +52,7 @@ def run(command: str, **kwargs: Any) -> Optional[Result]:
     return Context().run(command, **kwargs)
 
 
-def sudo(command: str, **kwargs: Any) -> Optional[Result]:
+def sudo(command: str, **kwargs: Any) -> Result:
     """
     Run ``command`` in a ``sudo`` subprocess and return a `.Result` object.
 

{invoke-2.2.1 → invoke-3.0.0}/invoke/config.py

@@ -449,7 +449,7 @@ class Config(DataProxy):
         # TODO: consider an automatic fallback to /bin/sh for systems lacking
         # /bin/bash; however users may configure run.shell quite easily, so...
         else:
-            shell = "/bin/bash"
+            shell = "bash"
 
         return {
             # TODO: we document 'debug' but it's not truly implemented outside

{invoke-2.2.1 → invoke-3.0.0}/invoke/context.py

@@ -4,7 +4,6 @@ from contextlib import contextmanager
 from itertools import cycle
 from os import PathLike
 from typing import (
-    TYPE_CHECKING,
     Any,
     Generator,
     Iterator,
@@ -15,13 +14,10 @@ from typing import (
 from unittest.mock import Mock
 
 from .config import Config, DataProxy
-from .exceptions import Failure, AuthFailure, ResponseNotAccepted
-from .runners import Result
+from .exceptions import AuthFailure, Failure, ResponseNotAccepted
+from .runners import Result, Runner
 from .watchers import FailingResponder
 
-if TYPE_CHECKING:
-    from invoke.runners import Runner
-
 
 class Context(DataProxy):
     """
@@ -43,37 +39,59 @@ class Context(DataProxy):
     .. versionadded:: 1.0
     """
 
-    def __init__(self, config: Optional[Config] = None) -> None:
+    # NOTE: sometime after Sphinx 1.7, autodoc stopped being able to see
+    # doc-comments inside __init__ (or something equivalent, anyway). Moving
+    # the type definitions up here seems to work better and /shouldn't/ mess up
+    # the DataProxy magic going on...
+
+    #: A list of commands to run (via "&&") before the main argument to any
+    #: `run` or `sudo` calls. Note that the primary API for manipulating
+    #: this list is `prefix`; see its docs for details.
+    command_prefixes: List[str]
+    #: A list of directories to 'cd' into before running commands with
+    #: `run` or `sudo`; intended for management via `cd`, please see its
+    #: docs for details.
+    command_cwds: List[str]
+    #: The CLI parser's 'remainder' value (text given after a standalone
+    #: ``--`` in the command line), or the empty string if not given.
+    remainder: str
+
+    def __init__(
+        self,
+        config: Optional[Config] = None,
+        remainder: str = "",
+    ) -> None:
         """
         :param config:
             `.Config` object to use as the base configuration.
 
             Defaults to an anonymous/default `.Config` instance.
+
+        :param remainder:
+            The invoking program's :ref:`parser remainder <remainder>` value,
+            if any was obtained.
         """
-        #: The fully merged `.Config` object appropriate for this context.
-        #:
-        #: `.Config` settings (see their documentation for details) may be
-        #: accessed like dictionary keys (``c.config['foo']``) or object
-        #: attributes (``c.config.foo``).
-        #:
-        #: As a convenience shorthand, the `.Context` object proxies to its
-        #: ``config`` attribute in the same way - e.g. ``c['foo']`` or
-        #: ``c.foo`` returns the same value as ``c.config['foo']``.
         config = config if config is not None else Config()
-        self._set(_config=config)
-        #: A list of commands to run (via "&&") before the main argument to any
-        #: `run` or `sudo` calls. Note that the primary API for manipulating
-        #: this list is `prefix`; see its docs for details.
-        command_prefixes: List[str] = list()
-        self._set(command_prefixes=command_prefixes)
-        #: A list of directories to 'cd' into before running commands with
-        #: `run` or `sudo`; intended for management via `cd`, please see its
-        #: docs for details.
-        command_cwds: List[str] = list()
-        self._set(command_cwds=command_cwds)
+        self._set(
+            _config=config,
+            command_prefixes=[],
+            command_cwds=[],
+            remainder=remainder,
+        )
 
     @property
     def config(self) -> Config:
+        """
+        The fully merged `.Config` object appropriate for this context.
+
+        `.Config` settings (see their documentation for details) may be
+        accessed like dictionary keys (``c.config['foo']``) or object
+        attributes (``c.config.foo``).
+
+        As a convenience shorthand, the `.Context` object proxies to its
+        ``config`` attribute in the same way - e.g. ``c['foo']`` or
+        ``c.foo`` returns the same value as ``c.config['foo']``.
+        """
         # Allows Context to expose a .config attribute even though DataProxy
         # otherwise considers it a config key.
         return self._config
@@ -87,7 +105,7 @@ class Context(DataProxy):
         # runtime.
         self._set(_config=value)
 
-    def run(self, command: str, **kwargs: Any) -> Optional[Result]:
+    def run(self, command: str, **kwargs: Any) -> Result:
         """
         Execute a local shell command, honoring config options.
 
@@ -106,13 +124,11 @@ class Context(DataProxy):
     # NOTE: broken out of run() to allow for runner class injection in
     # Fabric/etc, which needs to juggle multiple runner class types (local and
     # remote).
-    def _run(
-        self, runner: "Runner", command: str, **kwargs: Any
-    ) -> Optional[Result]:
+    def _run(self, runner: "Runner", command: str, **kwargs: Any) -> Result:
         command = self._prefix_commands(command)
         return runner.run(command, **kwargs)
 
-    def sudo(self, command: str, **kwargs: Any) -> Optional[Result]:
+    def sudo(self, command: str, **kwargs: Any) -> Result:
         """
         Execute a shell command via ``sudo`` with password auto-response.
 
@@ -185,9 +201,7 @@ class Context(DataProxy):
         return self._sudo(runner, command, **kwargs)
 
     # NOTE: this is for runner injection; see NOTE above _run().
-    def _sudo(
-        self, runner: "Runner", command: str, **kwargs: Any
-    ) -> Optional[Result]:
+    def _sudo(self, runner: "Runner", command: str, **kwargs: Any) -> Result:
         prompt = self.config.sudo.prompt
         password = kwargs.pop("password", self.config.sudo.password)
         user = kwargs.pop("user", self.config.sudo.user)

{invoke-2.2.1 → invoke-3.0.0}/invoke/executor.py

@@ -1,14 +1,13 @@
 from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
 
 from .config import Config
-from .parser import ParserContext
-from .util import debug
+from .parser import ParserContext, ParseResult
 from .tasks import Call, Task
+from .util import debug
 
 if TYPE_CHECKING:
     from .collection import Collection
     from .runners import Result
-    from .parser import ParseResult
 
 
 class Executor:
@@ -41,10 +40,14 @@ class Executor:
         :param core:
             An optional `.ParseResult` holding parsed core program arguments.
             Defaults to ``None``.
+
+        .. versionchanged:: 3.0
+            The ``core`` attribute now defaults to an 'empty' `.ParseResult` if
+            ``None`` was given.
         """
         self.collection = collection
         self.config = config if config is not None else Config()
-        self.core = core
+        self.core = core if core is not None else ParseResult()
 
     def execute(
         self, *tasks: Union[str, Tuple[str, Dict[str, Any]], ParserContext]
@@ -135,7 +138,7 @@ class Executor:
             # Get final context from the Call (which will know how to generate
             # an appropriate one; e.g. subclasses might use extra data from
             # being parameterized), handing in this config for use there.
-            context = call.make_context(config)
+            context = call.make_context(config, core_parse_result=self.core)
             args = (context, *call.args)
             result = call.task(*args, **call.kwargs)
             if autoprint:

{invoke-2.2.1 → invoke-3.0.0}/invoke/loader.py

@@ -37,7 +37,7 @@ class Loader:
 
         Must return a ModuleSpec valid for use by `importlib`, which is
         typically a name string followed by the contents of the 3-tuple
-        returned by `importlib.module_from_spec` (``name``, ``loader``,
+        returned by `importlib.util.module_from_spec` (``name``, ``loader``,
         ``origin``.)
 
         For a sample implementation, see `.FilesystemLoader`.

{invoke-2.2.1 → invoke-3.0.0}/invoke/program.py

@@ -18,8 +18,8 @@ from typing import (
 
 from . import Collection, Config, Executor, FilesystemLoader
 from .completion.complete import complete, print_completion_script
-from .parser import Parser, ParserContext, Argument
-from .exceptions import UnexpectedExit, CollectionNotFound, ParseError, Exit
+from .exceptions import CollectionNotFound, Exit, ParseError, UnexpectedExit
+from .parser import Argument, Parser, ParserContext
 from .terminals import pty_size
 from .util import debug, enable_logging, helpline
 

{invoke-2.2.1 → invoke-3.0.0}/invoke/runners.py

@@ -1,20 +1,20 @@
 import errno
 import locale
 import os
+import signal
 import struct
 import sys
 import threading
 import time
-import signal
-from subprocess import Popen, PIPE
+from subprocess import PIPE, Popen
 from types import TracebackType
 from typing import (
+    IO,
     TYPE_CHECKING,
     Any,
     Callable,
     Dict,
     Generator,
-    IO,
     List,
     Optional,
     Tuple,
@@ -37,21 +37,21 @@ except ImportError:
     termios = None  # type: ignore[assignment]
 
 from .exceptions import (
-    UnexpectedExit,
+    CommandTimedOut,
     Failure,
+    SubprocessPipeError,
     ThreadException,
+    UnexpectedExit,
     WatcherError,
-    SubprocessPipeError,
-    CommandTimedOut,
 )
 from .terminals import (
     WINDOWS,
-    pty_size,
+    bytes_to_read,
     character_buffered,
+    pty_size,
     ready_for_reading,
-    bytes_to_read,
 )
-from .util import has_fileno, isatty, ExceptionHandlingThread
+from .util import ExceptionHandlingThread, has_fileno, isatty
 
 if TYPE_CHECKING:
     from .context import Context
@@ -90,7 +90,7 @@ class Runner:
                 minimum, this means values for each of the default
                 `.Runner.run` keyword arguments such as ``echo`` and ``warn``.
 
-        :raises exceptions.ValueError:
+        :raises ValueError:
             if not all expected default values are found in ``context``.
         """
         #: The `.Context` given to the same-named argument of `__init__`.
@@ -122,7 +122,7 @@ class Runner:
         self._asynchronous = False
         self._disowned = False
 
-    def run(self, command: str, **kwargs: Any) -> Optional["Result"]:
+    def run(self, command: str, **kwargs: Any) -> "Result":
         """
         Execute ``command``, returning an instance of `Result` once complete.
 
@@ -188,19 +188,26 @@ class Runner:
 
             Specifically, ``disown=True`` has the following behaviors:
 
-            - The return value is ``None`` instead of a `Result` or subclass.
+            - The return value is still a `Result`, but it is severely limited
+              in functionality & data, per below.
             - No I/O worker threads are spun up, so you will have no access to
-              the subprocess' stdout/stderr, your stdin will not be forwarded,
+              the subprocess' stdout/stderr (those attributes on the result
+              will be empty strings), your stdin will not be forwarded,
               ``(out|err|in)_stream`` will be ignored, and features like
               ``watchers`` will not function.
             - No exit code is checked for, so you will not receive any errors
-              if the subprocess fails to exit cleanly.
+              if the subprocess fails to exit cleanly, the result's ``exited``
+              will be ``None``, and convenience properties like `ok` and
+              `failed` will not be reliable.
             - ``pty=True`` may not function correctly (subprocesses may not run
               at all; this seems to be a potential bug in Python's
               ``pty.fork``) unless your command line includes tools such as
               ``nohup`` or (the shell builtin) ``disown``.
 
             .. versionadded:: 1.4
+            .. versionchanged:: 3.0
+                The return value when ``disown=True`` changed from `None` to
+                `Result`.
 
         :param bool dry:
             Whether to dry-run instead of truly invoking the given command. See
@@ -428,7 +435,7 @@ class Runner:
             encoding=self.encoding,
         )
 
-    def _run_body(self, command: str, **kwargs: Any) -> Optional["Result"]:
+    def _run_body(self, command: str, **kwargs: Any) -> "Result":
         # Prepare all the bits n bobs.
         self._setup(command, kwargs)
         # If dry-run, stop here.
@@ -438,10 +445,20 @@ class Runner:
             )
         # Start executing the actual command (runs in background)
         self.start(command, self.opts["shell"], self.env)
+        # Update result data with anything only obtainable post-start.
+        self.result_kwargs["pid"] = self.get_pid()
         # If disowned, we just stop here - no threads, no timer, no error
         # checking, nada.
         if self._disowned:
-            return None
+            return self.generate_result(
+                **dict(
+                    self.result_kwargs,
+                    stdout="",
+                    stderr="",
+                    exited=None,
+                    disowned=True,
+                )
+            )
         # Stand up & kick off IO, timer threads
         self.start_timer(self.opts["timeout"])
         self.threads, self.stdout, self.stderr = self.create_io_threads()
@@ -1051,7 +1068,7 @@ class Runner:
         execution on a remote system.
 
         In most cases, this method will also set subclass-specific member
-        variables used in other methods such as `wait` and/or `returncode`.
+        variables used in other methods such as `.wait` and/or `returncode`.
 
         :param str command:
             Command string to execute.
@@ -1169,9 +1186,9 @@ class Runner:
         """
         Perform final cleanup, if necessary.
 
-        This method is called within a ``finally`` clause inside the main `run`
-        method. Depending on the subclass, it may be a no-op, or it may do
-        things such as close network connections or open files.
+        This method is called within a ``finally`` clause inside the main
+        `~.Runner.run` method. Depending on the subclass, it may be a no-op, or
+        it may do things such as close network connections or open files.
 
         :returns: ``None``
 
@@ -1203,6 +1220,15 @@ class Runner:
         # killed the subprocess, allowing us to even get to this point.)
         return bool(self._timer and not self._timer.is_alive())
 
+    def get_pid(self) -> Optional[int]:
+        """
+        When possible, obtain the subprocess PID.
+
+        The default implementation returns None; subclasses may return useful
+        integers.
+        """
+        return None
+
 
 class Local(Runner):
     """
@@ -1327,12 +1353,11 @@ class Local(Runner):
                 # TODO: make subroutine?
                 winsize = struct.pack("HHHH", rows, cols, 0, 0)
                 fcntl.ioctl(sys.stdout.fileno(), termios.TIOCSWINSZ, winsize)
-                # Use execve for bare-minimum "exec w/ variable # args + env"
-                # behavior. No need for the 'p' (use PATH to find executable)
-                # for now.
+                # Use execvpe for bare-minimum "exec w/ variable # args + env"
+                # behavior.
                 # NOTE: stdlib subprocess (actually its posix flavor, which is
                 # written in C) uses either execve or execv, depending.
-                os.execve(shell, [shell, "-c", command], env)
+                os.execvpe(shell, [shell, "-c", command], env)
         else:
             self.process = Popen(
                 command,
@@ -1344,10 +1369,12 @@ class Local(Runner):
                 stdin=PIPE,
             )
 
+    def get_pid(self) -> int:
+        return self.pid if self.using_pty else self.process.pid
+
     def kill(self) -> None:
-        pid = self.pid if self.using_pty else self.process.pid
         try:
-            os.kill(pid, signal.SIGKILL)
+            os.kill(self.get_pid(), signal.SIGKILL)
         except ProcessLookupError:
             # In odd situations where our subprocess is already dead, don't
             # throw this upwards.
@@ -1453,6 +1480,21 @@ class Result:
         results in ``result.hide == ('stdout', 'stderr')``; and ``hide=False``
         (the default) generates ``result.hide == ()`` (the empty tuple.)
 
+    :param int pid:
+        The process ID of the subprocess that was executed (normally) or is
+        executing (when asynchronous or disowned).
+
+        .. versionadded:: 3.0
+
+    :param bool disowned:
+        Whether the subprocess was 'disowned' or detached from ourselves; in
+        this mode may other attributes or methods of this `Result` will be
+        unreliable, see `Runner.run` docs for details. You may want to use your
+        own methods to interrogate your operating system about this object's
+        ``pid``, however, which will usually be valid.
+
+        .. versionadded:: 3.0
+
     .. note::
         `Result` objects' truth evaluation is equivalent to their `.ok`
         attribute's value. Therefore, quick-and-dirty expressions like the
@@ -1481,6 +1523,8 @@ class Result:
         exited: int = 0,
         pty: bool = False,
         hide: Tuple[str, ...] = tuple(),
+        pid: Optional[int] = None,
+        disowned: bool = False,
     ):
         self.stdout = stdout
         self.stderr = stderr
@@ -1493,6 +1537,8 @@ class Result:
         self.exited = exited
         self.pty = pty
         self.hide = hide
+        self.pid = pid
+        self.disowned = disowned
 
     @property
     def return_code(self) -> int:
@@ -1515,11 +1561,9 @@ class Result:
         for x in ("stdout", "stderr"):
             val = getattr(self, x)
             ret.append(
-                """=== {} ===
-{}
-""".format(
-                    x, val.rstrip()
-                )
+                f"""=== {x} ===
+{val.rstrip()}
+"""
                 if val
                 else "(no {})".format(x)
             )