Merge branch 'master' into 197-int

Author: bitprophet

.coveragerc

@@ -0,0 +1,4 @@
+[run]
+branch = True
+include = invoke/*
+omit = invoke/vendor/*

.gitignore

@@ -6,3 +6,6 @@ dist/
 *.egg-info
 *.py[cod]
 src/
+htmlcov
+coverage.xml
+.cache

.travis.yml

@@ -1,40 +1,79 @@
 language: python
+sudo: required
+dist: xenial
+cache:
+  directories:
+    - $HOME/.cache/pip
 python:
-  - "2.6"
   - "2.7"
-  - "3.2"
-  - "3.3"
   - "3.4"
+  - "3.5"
+  - "3.6"
+  - "3.7"
+  - "3.8-dev"
   - "pypy"
+  - "pypy3"
 matrix:
-  # pypy is frequentlyish unstable on Travis, don't let it mark entire status
-  # as 'bad' =/ (Still worth running it though.)
   allow_failures:
-    - python: pypy
+    - python: "3.8-dev"
+# WHY does this have to be in before_install and not install? o_O
+before_install:
+  # Used by 'inv regression' (more performant/safe/likely to expose real issues
+  # than in-Python threads...)
+  - sudo apt-get -y install parallel
 install:
+  # For some reason Travis' build envs have wildly different pip/setuptools
+  # versions between minor Python versions, and this can cause many hilarious
+  # corner packaging cases. So...
+  - pip install -U pip
+  # Setuptools 34+ seems to get less stable
+  - pip install 'setuptools>33,<34'
   # Pre-requirements sanity test (again, resembles pure, non-dev install
   # environment.) Avoids e.g. spec's 'six' from gumming up our attempts to
   # import our vendorized 'six'.
   - pip install -r tasks-requirements.txt
   - inv --list
   # Install remaining dev requirements (test runner, etc)
   - pip install -r dev-requirements.txt
+  - pip list --format=columns
+  # Also create a workable alt-interpreter venv for testing dual package builds
+  # Python 3 is nicely namespaced, globally. Python 2 is masked by Travis'
+  # default venv, so we gotta hardcode it.
+  - "virtualenv alt_env --python=$([[ $TRAVIS_PYTHON_VERSION == 2* ]] && echo python3 || echo /usr/bin/python)"
+  - alt_env/bin/pip install wheel
+before_script:
+  # Create 'sudouser' w/ sudo password & perms on Travis' homedir
+  - inv travis.make-sudouser
+  # Blacken and flake8 before running any tests, it's a faster fail
+  - inv travis.blacken
+  - flake8
 script:
-  # Main test suite
-  - inv test
-  # Slow, annoying-to-run-every-time integration suite
-  - inv integration
-  # Websites build OK? (NOTE: sphinx/jinja are fucked on Python 3.2 now?)
-  - "[[ $TRAVIS_PYTHON_VERSION == 3.2 ]] || inv sites"
+  # Execute full test suite + coverage, as the new sudo-capable user
+  - inv travis.sudo-coverage
+  # Perform extra "not feasible inside pytest for no obvious reason" tests
+  - inv regression
+  # Websites build OK? (Not on PyPy3, Sphinx is all "who the hell are you?" =/
+  - "if [[ $TRAVIS_PYTHON_VERSION != 'pypy3' ]]; then inv sites; fi"
+  # Doctests in websites OK? (Same caveat as above...)
+  - "if [[ $TRAVIS_PYTHON_VERSION != 'pypy3' ]]; then inv www.doctest; fi"
   # Did we break setup.py?
-  - pip uninstall -y invoke # To undo the implicit -e install from above
-  - pip install . # NO -e!
-  - inv -l # Sanity check
+  # NOTE: sometime in 2019 travis grew a bizarre EnvironmentError problem
+  # around inability to overwrite/remote __pycache__ dirs...this attempts to
+  # workaround
+  - "find . -type d -name __pycache__ | sudo xargs rm -rf"
+  - inv travis.test-installation --package=invoke --sanity="inv --list"
+  # Test distribution builds, including some package_data based stuff
+  # (completion script printing)
+  - "inv travis.test-packaging --package=invoke --sanity='inv --list && inv --print-completion-script zsh' --alt-python=alt_env/bin/python"
+after_success:
+  # Upload coverage data to codecov
+  - codecov
 notifications:
   irc:
     channels: "irc.freenode.org#invoke"
     template:
-      - "%{repository}@%{branch}: %{message} (%{build_url})"
+      - "%{repository_name}@%{branch}: %{message} (%{build_url})"
     on_success: change
     on_failure: change
+    on_error: change
   email: false

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Jeff Forcier.
+Copyright (c) 2020 Jeff Forcier.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

MANIFEST.in

@@ -1,7 +1,11 @@
 include LICENSE
 include README.rst
-recursive-include docs *
-recursive-exclude docs/_build *
+include tasks.py
+recursive-include invoke/completion *
+recursive-include sites *
+recursive-exclude sites/*/_build *
 include dev-requirements.txt
+include tasks-requirements.txt
 recursive-include tests *
-recursive-exclude tests *.pyc *.pyo
+recursive-exclude * *.pyc *.pyo
+recursive-exclude **/__pycache__ *

README.rst

@@ -1,49 +1,11 @@
-Invoke is a Python (2.6+ and 3.2+) task execution tool & library, drawing inspiration from various sources to arrive at a powerful & clean feature set.
+Welcome to Invoke!
+==================
 
-* Like Ruby's Rake tool and Invoke's own predecessor Fabric 1.x, it provides a
-  clean, high level API for running shell commands and defining/organizing
-  task functions from a ``tasks.py`` file::
+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.
 
-    from invoke import run, task
-
-    @task
-    def clean(docs=False, bytecode=False, extra=''):
-        patterns = ['build']
-        if docs:
-            patterns.append('docs/_build')
-        if bytecode:
-            patterns.append('**/*.pyc')
-        if extra:
-            patterns.append(extra)
-        for pattern in patterns:
-            run("rm -rf %s" % pattern)
-
-    @task
-    def build(docs=False):
-        run("python setup.py build")
-        if docs:
-            run("sphinx-build docs docs/_build")
-
-* From GNU Make, it inherits an emphasis on minimal boilerplate for common
-  patterns and the ability to run multiple tasks in a single invocation::
-
-    $ invoke clean build
-
-* Following the lead of most Unix CLI applications, it offers a traditional
-  flag-based style of command-line parsing, deriving flag names and value types
-  from task signatures (optionally, of course!)::
-
-    $ invoke clean --docs --bytecode build --docs --extra='**/*.pyo'
-    $ invoke clean -d -b build --docs -e '**/*.pyo'
-    $ invoke clean -db build -de '**/*.pyo'
-
-* Like many of its predecessors, it offers advanced features as well --
-  namespacing, task aliasing, before/after hooks, parallel execution and more.
-
-For documentation, including detailed installation information, please see
-http://docs.pyinvoke.org. Post-install usage information may be found in ``invoke
---help``.
-
-You can install the `development version
-<https://github.com/pyinvoke/invoke/tarball/master#egg=invoke-dev>`_ via ``pip
-install invoke==dev``.
+For a high level introduction, including example code, please see `our main
+project website <http://pyinvoke.org>`_; or for detailed API docs, see `the
+versioned API website <http://docs.pyinvoke.org>`_.

THOUGHTS.rst

@@ -0,0 +1,202 @@
+==============================================
+Random thoughts unsuitable for public docs yet
+==============================================
+
+CLI type mapping
+================
+
+Some loose thoughts on bridging the "shell is strings, Python wants
+lists/dicts/integers/bools/etc" problem.
+
+Methodologies
+-------------
+
+* Explicit mapping, as with ``argparse``: this particular flag turns into a
+  list/boolean/int/whatever. Because we're specifically mapping to function
+  keyword arguments, a little of that complexity can be removed, but generally
+  it'll look very similar. E.g.::
+
+    @args(foo=int)
+    def mytask(foo):
+        ...
+
+  would turn this::
+
+    $ invoke mytask --foo 7
+
+  into ``7``, not ``"7"``.
+* Introspection-based mapping, i.e. introspecting the default values of a
+  function signature and automatically transforming the CLI input. E.g.::
+
+    def mytask(foo=5):
+        ...
+
+  invoked as::
+
+    $ invoke mytask --foo 7
+
+  results in the Python value ``7`` instead of ``"7"``, just as with the
+  explicit example above.
+* Formatting-based mapping, i.e. having (optional) conventions in the string
+  format of an incoming flag argument that cause transformations to occur.
+  E.g. we could say that commas in an argument automatically trigger
+  transformation into a list of strings; thus the invocation::
+
+    $ invoke mytask --items a,b,c
+
+  would on the Python end turn into a call like this::
+
+    mytask(items=['a', 'b', 'c'])
+
+What to do?
+~~~~~~~~~~~
+
+We haven't decided exactly how many of these to use -- we may end up using all
+three of them as appropriate, with some useful/sensible default and the option
+to enable/disable things for power users. The trick is to balance
+power/features with becoming overly complicated to understand or utilize.
+
+Other types
+-----------
+
+Those examples cover integers/numbers, and lists/iterables. Strings are
+obviously easy/the default. What else is there?
+
+* Booleans: these are relatively simple too, either a flag exists (``True``) or
+  is omitted (``False``).
+  
+    * Could also work in a ``--foo`` vs ``--no-foo`` convention to help with
+      the inverse, i.e. values which should default to ``True`` and then need
+      to be turned "off" on the command line. E.g.::
+
+        def mytask(option=True):
+            ...
+
+      could result in having a flag called ``--no-option`` instead of
+      ``--option``. (Or possibly both.)
+
+* Dicts: these are tougher, but we could potentially use something like::
+
+    $ invoke mytask --dictopt key1=val1,key2=val2
+
+  resulting in::
+
+    mytask(dictopt={'key1': 'val1', 'key2': 'val2'})
+
+
+Parameterizing tasks
+====================
+
+Old "previous example" (at time the below was split out of live docs, the
+actual previous example had been changed a lot and no longer applied)::
+
+    $ invoke test --module=foo test --module=bar
+    Cleaning
+    Testing foo
+    Cleaning
+    Testing bar
+
+The previous example had a bit of duplication in how it was invoked; an
+intermediate use case is to bundle up that sort of parameterization into a
+"meta" task that itself invokes other tasks in a parameterized fashion.
+
+TK: API for this? at CLI level would have to be unorthodox invocation, e.g.::
+
+    @task
+    def foo(bar):
+        print(bar)
+
+    $ invoke --parameterize foo --param bar --values 1 2 3 4
+    1
+    2
+    3
+    4
+
+Note how there's no "real" invocation of ``foo`` in the normal sense. How to
+handle partial application (e.g. runtime selection of other non-parameterized
+arguments)? E.g.::
+
+    @task
+    def foo(bar, biz):
+        print("%s %s" % (bar, biz))
+
+    $ invoke --parameterize foo --param bar --values 1 2 3 4 --biz "And a"
+    And a 1
+    And a 2
+    And a 3
+    And a 4
+
+That's pretty clunky and foregoes any multi-task invocation. But how could we
+handle multiple tasks here? If we gave each individual task flags for this,
+like so::
+
+    $ invoke foo --biz "And a" --param foo --values 1 2 3 4
+
+We could do multiple tasks, but then we're stomping on tasks' argument
+namespaces (we've taken over ``param`` and ``values``). Really hate that.
+
+**IDEALLY** we'd still limit parameterization to library use since it's an
+advanced-ish feature and frequently the parameterization vector is dynamic (aka
+not the sort of thing you'd give at CLI anyway)
+
+Probably best to leave that in the intermediate docs and keep it lib level;
+it's mostly there for Fabric and advanced users, not something the average
+Invoke-only user would care about. Not worth the effort to make it work on CLI
+at this point.
+
+::
+
+    @task
+    def stuff(var):
+        print(var)
+
+    # NOTE: may need to be part of base executor since Collection has to know
+    # to pass the parameterization option/values into Executor().execute()?
+    class ParameterizedExecutor(Executor):
+        # NOTE: assumes single dimension of parameterization.
+        # Realistically would want e.g. {'name': [values], ...} structure and
+        # then do cross product or something
+        def execute(self, task, args, kwargs, parameter=None, values=None):
+            # Would be nice to generalize this?
+            if parameter:
+                # TODO: handle non-None parameter w/ None values (error)
+                # NOTE: this is where parallelization would occur; probably
+                # need to move into sub-method
+                for value in values:
+                    my_kwargs = dict(kwargs)
+                    my_kwargs[parameter] = value
+                    super(self, ParameterizedExecutor).execute(task, kwargs=my_kwargs)
+            else:
+                super(self, ParameterizedExecutor).execute(task, args, kwargs)
+
+
+Getting hairy: one task, with one pre-task, parameterized
+=========================================================
+
+::
+
+    @task
+    def setup():
+        print("Yay")
+
+    @task(pre=[setup])
+    def build():
+        print("Woo")
+
+    class OhGodExecutor(Executor):
+        def execute(self, task, args, kwargs, parameter, values):
+            # assume always parameterized meh
+            # Run pretasks once only, instead of once per parameter value
+            for pre in task.pre:
+                self.execute(self.collection[pre])
+            for value in values:
+                my_kwargs = dict(kwargs)
+                my_kwargs[parameter] = value
+                super(self, OhGodExecutor).execute(task, kwargs=my_kwargs)
+
+
+Still hairy: one task, with a pre-task that itself has a pre-task
+=================================================================
+
+All the things: two tasks, each with pre-tasks, both parameterized
+==================================================================