1========= 2Changelog 3========= 4 5- :release:`1.6.0 <2021-07-09>` 6- :release:`1.5.1 <2021-07-09>` 7- :support:`- backported` (Mostly) alphabetize the list of ``run()`` params in 8 the runners API docs. Previously they were an unordered mess. 9- :support:`- backported` Document the ``dry`` keyword argument to ``run``, 10 which had been added in version 1.3 but only documented as a CLI flag; it 11 does also work as a kwarg (and as a config option). 12- :bug:`751` Don't explode on empty-but-for-whitespace task docstrings. Thanks 13 to Matt Hayden for the report & initial patches. 14- :feature:`791` Add a new ``run.echo_format`` configuration option allowing 15 control over the format of echoed commands. It defaults to the previously 16 hardcoded value (wrap in ANSI bold) and is thus backwards compatible. Thanks 17 to David JM Emmett for the patch. 18- :release:`1.5.0 <2020-12-30>` 19- :feature:`454` (also :issue:`577`/:issue:`658`, via 20 :issue:`583`/:issue:`681`/:issue:`607`) Allow any string-compatible object to 21 be passed to `Context.cd <invoke.context.Context.cd>`, enabling use of eg 22 ``pathlib.Path`` instances. Thanks to Jimm Domingo for the original report 23 and Ludovico Bianchi, Mario César, and Floris Lambrechts for patches. 24- :bug:`409 major` (via :issue:`611`/:issue:`580`) Don't silently discard help 25 text for task arguments whose names happen to contain underscores. Reported 26 by ``@iago1460``, original patches by Hayden Flinner and Floris Lambrechts. 27- :bug:`398 major` (via :issue:`611`/:issue:`580`) Don't silently ignore task 28 help specifiers which don't actually map to the decorated task's arguments 29 (eg ``@task(help={"foo": "help for foo"})`` wrapping a task without a ``foo`` 30 argument). Reported by Sohaib Farooqi, with original patches by Hayden 31 Flinner and Floris Lambrechts. 32- :feature:`197` Allow subcollections to act as the default 'tasks' of their 33 parent collections (via the new ``default`` kwarg to 34 `~invoke.collection.Collection.add_collection`). This means that nontrivial 35 task trees can specify eg "use my test subcollection's default task as the 36 global default task" and similar. Thanks to Tye Wang for the request and 37 initial patch. 38- :support:`-` Enhanced test coverage in a handful of modules whose coverage 39 was under 90%. 40- :feature:`-` `~invoke.context.MockContext` now populates its 41 ``NotImplementedError`` exception instances (typically raised when a command 42 is executed which had no pre-prepared result) with the command string that 43 triggered them; this makes it much easier to tell what exactly in a test 44 caused the error. 45- :feature:`-` `~invoke.context.MockContext` now accepts a few quality-of-life 46 shortcuts as keys and values in its ``run``/``sudo`` arguments: 47 48 - Keys may be compiled regular expression objects, as well as strings, and 49 will match any calls whose commands match the regex. 50 - Values may be ``True`` or ``False`` as shorthand for otherwise empty 51 `~invoke.runners.Result` objects with exit codes of ``0`` or ``1`` 52 respectively. 53 - Values may also be strings, as shorthand for otherwise empty 54 `~invoke.runners.Result` objects with those strings given as the 55 ``stdout`` argument. 56 57- :feature:`441` Add a new ``repeat`` kwarg to `~invoke.context.MockContext` 58 which, when True (default: False) causes stored results for its methods to be 59 yielded repeatedly instead of consumed. Feature request courtesy of 60 ``@SwampFalc``. 61- :bug:`- major` Immutable iterable result values handed to 62 `~invoke.context.MockContext` would yield errors (due to the use of 63 ``pop()``). The offending logic has been retooled to be more iterator-focused 64 and now works for tuples and etc. 65- :support:`-` Update the :ref:`testing documentation <testing-user-code>` a 66 bit: cleaned up existing examples and added new sections for the other 67 updates in the 1.5 release. 68- :feature:`700` Automatically populate the ``command`` attribute of 69 `~invoke.runners.Result` objects returned by `~invoke.context.MockContext` 70 methods, with the command string triggering that result. Previously users had 71 to do this by hand or otherwise suffered inaccurate result objects. Thanks to 72 ``@SwampFalc`` for the report & initial patch. 73- :feature:`-` Upgrade `~invoke.context.MockContext` to wrap its methods in 74 ``Mock`` objects if the ``(unittest.)mock`` library is importable. This makes 75 testing Invoke-using codebases even easier. 76- :release:`1.4.1 <2020-01-29>` 77- :release:`1.3.1 <2020-01-29>` 78- :support:`586 backported` Explicitly strip out ``__pycache__`` (and for good 79 measure, ``.py[co]``, which previously we only stripped from the ``tests/`` 80 folder) in our ``MANIFEST.in``, since at least some earlier releases 81 erroneously included such. Credit to Martijn Pieters for the report and 82 Floris Lambrechts for the patch. 83- :bug:`660` Fix an issue with `~invoke.run` & friends having intermittent 84 problems at exit time (symptom was typically about the exit code value being 85 ``None`` instead of an integer; often with an exception trace). Thanks to 86 Frank Lazzarini for the report and to the numerous others who provided 87 reproduction cases. 88- :bug:`518` Close pseudoterminals opened by the `~invoke.runners.Local` class 89 during ``run(..., pty=True)``. Previously, these were only closed 90 incidentally at process shutdown, causing file descriptor leakage in 91 long-running processes. Thanks to Jonathan Paulson for the report. 92- :release:`1.4.0 <2020-01-03>` 93- :bug:`637 major` A corner case in `~invoke.context.Context.run` caused 94 overridden streams to be unused if those streams were also set to be hidden 95 (eg ``run(command, hide=True, out_stream=StringIO())`` would result in no 96 writes to the ``StringIO`` object). 97 98 This has been fixed - hiding for a given stream is now ignored if that stream 99 has been set to some non-``None`` (and in the case of ``in_stream``, 100 non-``False``) value. 101- :bug:`- major` As part of feature work on :issue:`682`, we noticed that the 102 `~invoke.runners.Result` return value from `~invoke.context.Context.run` was 103 inconsistent between dry-run and regular modes; for example, the dry-run 104 version of the object lacked updated values for ``hide``, ``encoding`` and 105 ``env``. This has been fixed. 106- :feature:`682` (originally reported as :issue:`194`) Add asynchronous 107 behavior to `~invoke.runners.Runner.run`: 108 109 - Basic asynchronicity, where the method returns as soon as the subprocess 110 has started running, and that return value is an object with methods 111 allowing access to the final result. 112 - "Disowning" subprocesses entirely, which not only returns immediately but 113 also omits background threading, allowing the subprocesses to outlive 114 Invoke's own process. 115 116 See the updated API docs for the `~invoke.runners.Runner` for details on the 117 new ``asynchronous`` and ``disown`` kwargs enabling this behavior. Thanks to 118 ``@MinchinWeb`` for the original report. 119- :feature:`-` Never accompanied the top-level singleton `~invoke.run` (which 120 simply wraps an anonymous `~invoke.context.Context`'s ``run`` method) with 121 its logical sibling, `~invoke.sudo` - this has been remedied. 122- :release:`1.3.0 <2019-08-06>` 123- :feature:`324` Add basic dry-run support, in the form of a new 124 :option:`--dry` CLI option and matching ``run.dry`` config setting, which 125 causes command runners (eg `~invoke.run`, `Context.run 126 <invoke.context.Context.run>`) to: 127 128 - Act as if the ``echo`` option has been turned on, printing the 129 command-to-be-run to stdout; 130 - Skip actual subprocess invocation (returning before any of that machinery 131 starts running); 132 - Return a dummy `~invoke.runners.Result` object with 'blank' values (empty 133 stdout/err strings, ``0`` exit code, etc). 134 135 This allows quickly seeing what a given task or series of tasks might do, 136 without actually running any shell commands (though naturally, any 137 state-modifying Python code will still run). 138 139 Thanks to Monty Hindman for the feature request and ``@thebjorn`` for the 140 initial patch. 141 142- :bug:`384 major` (via :issue:`653`) Modify config file loading so it detects 143 missing-file IOErrors via their ``errno`` attribute instead of their string 144 rendering (eg ``"No such file"``). This should improve compatibility for 145 non-English locales. Thanks to Patrick Massot for the report and Github user 146 ``@cybiere`` for the patch. 147- :feature:`539` (via :issue:`645`) Add support for command timeouts, i.e. the 148 ability to add an upper bound on how long a call to 149 `~invoke.context.Context.run` may take to execute. Specifically: 150 151 - A ``timeout`` argument to `~invoke.context.Context.run`. 152 - The ``timeouts.command`` config setting mapping to that argument. 153 - The :option:`-T/--command-timeout <-T>` CLI flag. 154 155 Thanks to Israel Fruchter for the request & an early version of the patchset. 156- :bug:`552 major` (also :issue:`553`) Add a new `~invoke.runners.Runner` 157 method, `~invoke.runners.Runner.close_proc_stdin`, and call it when standard 158 input processing detects an EOF. Without this, subprocesses that read their 159 stdin until EOF would block forever, hanging the program. Thanks to 160 ``@plockc`` for the report & initial patch. 161 162 .. note:: 163 This fix only applies when ``pty=False`` (the default); PTYs complicate the 164 situation greatly (but also mean the issue is less likely to occur). 165 166- :bug:`557 major` (with assist from :issue:`640`) Fix the 167 `~invoke.context.Context.cd` and `~invoke.context.Context.prefix` context 168 managers so that ``with cd`` and ``with prefix`` correctly revert their state 169 manipulations after they exit, when exceptions occur. Thanks to Jon Walsh and 170 Artur Puzio for their respective patches. 171- :bug:`466 major` Update the parsing and CLI-program mechanisms so that all 172 core arguments may be given within task CLI contexts; previously this 173 functionality only worked for the ``--help`` flag, and other core arguments 174 given after task names (such as ``--echo``) were silently ignored. 175- :feature:`-` Allow the configuration system to override which 176 `~invoke.executor.Executor` subclass to use when executing tasks (via an 177 import-oriented string). 178 179 Specifically, it's now possible to alter execution by distributing such a 180 subclass alongside, for example, a repository-local config file which sets 181 ``tasks.executor_class``; previously, this sort of thing required use of 182 :ref:`custom binaries <reusing-as-a-binary>`. 183- :release:`1.2.0 <2018-09-13>` 184- :feature:`301` (via :issue:`414`) Overhaul tab completion mechanisms so users 185 can :ref:`print a completion script <print-completion-script>` which 186 automatically matches the emitting binary's configured names (compared to the 187 previous hardcoded scripts, which only worked for ``inv``/``invoke`` by 188 default). Thanks to Nicolas Höning for the foundational patchset. 189- :release:`1.1.1 <2018-07-31>` 190- :release:`1.0.2 <2018-07-31>` 191- :bug:`556` (also `fabric/fabric#1823 192 <https://github.com/fabric/fabric/issues/1823>`_) Pre-emptively check for an 193 error condition involving an unpicklable config file value (Python config 194 files and imported module objects) and raise a useful exception instead of 195 allowing a confusing ``TypeError`` to bubble up later. Reported by Pham Cong 196 Dinh. 197- :bug:`559` (also `fabric/fabric#1812 198 <https://github.com/fabric/fabric/issues/1812>`_) Modify how 199 `~invoke.runners.Runner` performs stdin terminal mode changes, to avoid 200 incorrect terminal state restoration when run concurrently (which could lead 201 to things like terminal echo becoming disabled after the Python process 202 exits). 203 204 Thanks to Adam Jensen and Nick Timkovich for the detailed bug reports & 205 reproduction assistance. 206- :release:`1.1.0 <2018-07-12>` 207- :release:`1.0.1 <2018-07-12>` 208- :feature:`-` Enhance `~invoke.tasks.Call` with a new method 209 (``clone_data``) and new kwarg to an existing method (``clone`` grew 210 ``with_``) to assist subclassers when extending. 211- :bug:`270` (also :issue:`551`) ``None`` values in config levels (most 212 commonly caused by empty configuration files) would raise ``AttributeError`` 213 when `~invoke.config.merge_dicts` was used to merge config levels together. 214 This has been fixed. Thanks to Tyler Hoffman and Vlad Frolov for the reports. 215- :feature:`-` Refactor `~invoke.tasks.Call` internals slightly, exposing some 216 previously internal logic as the ``clone_data`` method; this is useful for 217 client codebases when extending `~invoke.tasks.Call` and friends. 218- :feature:`-` Remove overzealous argument checking in `@task 219 <invoke.tasks.task>`, instead just handing any extra kwargs into the task 220 class constructor. The high level behavior for truly invalid kwargs is the 221 same (``TypeError``) but now extending codebases can add kwargs to their 222 versions of ``@task`` without issue. 223- :feature:`-` Add a ``klass`` kwarg to `@task <invoke.tasks.task>` to allow 224 extending codebases the ability to create their own variants on 225 ``@task``/``Task``. 226- :bug:`-` Fix up the ``__repr__`` of `~invoke.tasks.Call` to reference dynamic 227 class name instead of hardcoding ``"Call"``; this allows subclasses' 228 ``__repr__`` output to be correct instead of confusing. 229- :support:`- backported` Fixed some inaccuracies in the API docs around 230 `~invoke.executor.Executor` and its ``core`` kwarg (was erroneously referring 231 to `~invoke.parser.context.ParserContext` instead of 232 `~invoke.parser.parser.ParseResult`). Includes related cleaning-up of 233 docstrings and tests. 234- :support:`- backported` Apply the `black <https://black.readthedocs.io/>`_ 235 code formatter to our codebase and our CI configuration. 236- :support:`- backported` Fix some test-suite-only failures preventing 237 successful testing on Python 3.7 and PyPy3, and move them out of the 'allowed 238 failures' test matrix quarantine now that they pass. 239- :support:`- backported` Implemented some minor missing tests, such as testing 240 the ``INVOKE_DEBUG`` low-level env var. 241- :feature:`543` Implemented support for using ``INVOKE_RUNTIME_CONFIG`` env 242 var as an alternate method of supplying a runtime configuration file path 243 (effectively, an env var based version of using the ``-f``/``--config`` 244 option). Feature request via Kevin J. Qiu. 245- :bug:`528` Around Invoke 0.23 we broke the ability to weave in subcollections 246 via keyword arguments to `~invoke.collection.Collection`, though it primarily 247 manifests as ``NoneType`` related errors during ``inv --list``. This was 248 unintentional and has been fixed. Report submitted by Tuukka Mustonen. 249- :bug:`-` As part of solving :issue:`528` we found a related bug, where 250 unnamed subcollections also caused issues with ``inv --list 251 --list-format=json``. Specifically, `Collection.serialized 252 <invoke.collection.Collection.serialized>` sorts subcollections by name, 253 which is problematic when that name is ``None``. This is now fixed. 254- :release:`1.0.0 <2018-05-09>` 255- :feature:`-` Added the :ref:`--prompt-for-sudo-password 256 <prompt-for-sudo-password>` CLI option for getpass-based up-front prompting 257 of a sensitive configuration value. 258- :feature:`-` Updated `~invoke.tasks.Task` to mimic the wrapped function's 259 ``__module__`` attribute, allowing for better interaction with things like 260 Sphinx autodoc that attempt to filter out imported objects from a module. 261- :bug:`- major` Removed an old, unused and untested (but, regrettably, 262 documented and public) method that doesn't seem to be much use: 263 ``invoke.config.Config.paths``. Please reach out if you were actually using 264 it and we may consider adding some form of it back. 265 266 .. warning:: 267 This is a backwards incompatible change if you were using ``Config.paths``. 268 269- :bug:`- major` Tweaked the innards of 270 `~invoke.config.Config`/`~invoke.config.DataProxy` to prevent accessing 271 properties & other attributes' values during ``__setattr__`` (the code in 272 question only needed the names). This should have no noticeable effect on 273 user code (besides a marginal speed increase) but fixed some minor test 274 coverage issues. 275- :release:`0.23.0 <2018-04-29>` 276- :bug:`- major` Previously, some error conditions (such as invalid task or 277 collection names being supplied by the user) printed to standard output, 278 instead of standard error. Standard error seems more appropriate here, so 279 this has been fixed. 280 281 .. warning:: 282 This is backwards incompatible if you were explicitly checking the standard 283 output of the ``inv[oke]`` program for some of these error messages. 284 285 .. warning:: 286 If your code is manually raising or introspecting instances of 287 `~invoke.exceptions.Exit`, note that its signature has changed from 288 ``Exit(code=0)`` to ``Exit(message=None, code=None)``. (Thus, this will 289 only impact you if you were calling its constructor instead of raising the 290 class object itself.) 291 292- :bug:`- major` `~invoke.collection.Collection` had some minor bugs or 293 oversights in how it responds to things like ``repr()``, ``==``; boolean 294 behavior; how docstrings appear when created from a Python module; etc. All 295 are now fixed. If you're not sure whether this affects you, it does not :) 296- :bug:`- major` Integer-type CLI arguments were not displaying placeholder 297 text in ``--help`` output (i.e. they appeared as ``--myint`` instead of 298 ``--myint=INT``.) This has been fixed. 299- :feature:`33` Overhaul task listing (formerly just a simple, boolean 300 ``--list``) to make life easier for users with nontrivial task trees: 301 302 - Limit display to a specific namespace by giving an optional argument to 303 ``--list``, e.g. ``--list build``; 304 - Additional output formats besides the default (now known as ``flat``) such 305 as a nested view with ``--list-format nested`` or script-friendly output 306 with ``--list-format json``. 307 - The default ``flat`` format now sorts a bit differently - the previous 308 algorithm would break up trees of tasks. 309 - Limit listing depth, so it's easier to view only the first level or two 310 (i.e. the overall namespaces) of a large tree, e.g. ``--list --list-depth 311 1``; 312 313 Thanks to the many users who submitted various requests under this ticket's 314 umbrella, and to Dave Burkholder in particular for detailed use case analysis 315 & feedback. 316 317- :support:`-` (partially re: :issue:`33`) Renamed the ``--root`` CLI flag to 318 ``--search-root``, partly for clarity (:issue:`33` will be adding namespace 319 display-root related flags, which would make ``--root`` ambiguous) and partly 320 for consistency with the config option, which was already named 321 ``search_root``. (The short version of the flag, ``-r``, is unchanged.) 322 323 .. warning:: 324 This is a backwards incompatible change. To fix, simply use 325 ``--search-root`` anywhere you were previously using ``--root``. 326- :bug:`516 major` Remove the CLI parser ambiguity rule regarding flag-like 327 tokens which are seen after an optional-value flag (e.g. ``inv task 328 --optionally-takes-a-value --some-other-flag``.) Previously, any flag-like 329 value in such a spot was considered ambiguous and raised a 330 `~invoke.exceptions.ParseError`. Now, the surrounding parse context is used 331 to resolve the ambiguity, and no error is raised. 332 333 .. warning:: 334 This behavior is backwards incompatible, but only if you had the minority 335 case where users frequently *and erroneously* give otherwise-legitimate 336 flag-like values to optional-value arguments, and you rely on the parse 337 errors to notify them of their mistake. (If you don't understand what this 338 means, don't worry, you almost certainly don't need to care!) 339 340- :support:`515` Ported the test suite from `spec 341 <https://github.com/bitprophet/spec>`_ (`nose 342 <https://nose.readthedocs.io>`_) to `pytest-relaxed 343 <https://github.com/bitprophet/pytest-relaxed>`_ (`pytest 344 <https://pytest.org>`_) as pytest basically won the test-runner war against 345 nose & has greater mindshare, more shiny toys, etc. 346- :support:`-` Rename ``invoke.platform`` to ``invoke.terminals``; it was 347 inadvertently shadowing the ``platform`` standard library builtin module. 348 This was not causing any bugs we are aware of, but it is still poor hygiene. 349 350 .. warning:: 351 This change is technically backwards incompatible. We don't expect many 352 users import ``invoke.platform`` directly, but if you are, take note. 353 354- :bug:`- major` (partially re: :issue:`449`) Update error message around 355 missing positional arguments so it actually lists them. Includes a minor 356 tweak to the API of `~invoke.parser.context.ParserContext`, namely changing 357 ``needs_positional_arguments`` (bool) to ``missing_positional_arguments`` 358 (list). 359- :release:`0.22.1 <2018-01-29>` 360- :bug:`342` Accidentally hardcoded ``Collection`` instead of ``cls`` in 361 `Collection.from_module <invoke.collection.Collection.from_module>` (an 362 alternate constructor and therefore a classmethod.) This made it rather hard 363 to properly subclass `~invoke.collection.Collection`. Report and initial 364 patch courtesy of Luc Saffre. 365- :support:`433 backported` Add -dev and -nightly style Python versions to our 366 Travis builds. Thanks to ``@SylvainDe`` for the contribution. 367- :bug:`437` When merging configuration levels together (which uses 368 `copy.copy` by default), pass file objects by reference so they don't get 369 closed. Catch & patch by Paul Healy. 370- :support:`469 backported` Fix up the :ref:`doc/example 371 <customizing-config-defaults>` re: subclassing `~invoke.config.Config`. 372 Credit: ``@Aiky30``. 373- :bug:`488` Account for additional I/O related ``OSError`` error strings 374 when attempting to capture only this specific subtype of error. This should 375 fix some issues with less common libc implementations such as ``musl`` (as 376 found on e.g. Alpine Linux.) Thanks to Rajitha Perera for the report. 377- :release:`0.22.0 <2017-11-29>` 378- :bug:`407 major` (also :issue:`494`, :issue:`67`) Update the default value of 379 the ``run.shell`` config value so that it reflects a Windows-appropriate 380 value (specifically, the ``COMSPEC`` env var or a fallback of ``cmd.exe``) on 381 Windows platforms. This prevents Windows users from being forced to always 382 ship around configuration-level overrides. 383 384 Thanks to Maciej 'maQ' Kusz for the original patchset, and to ``@thebjorn`` 385 and Garrett Jenkins for providing lots of feedback. 386- :bug:`- major` Iterable-type CLI args were actually still somewhat broken & 387 were 'eating' values after themselves in the parser stream (thus e.g. 388 preventing parsing of subsequent tasks or flags.) This has been fixed. 389- :support:`364` Drop Python 2.6 and Python 3.3 support, as these versions now 390 account for only very low percentages of the userbase and are unsupported (or 391 about to be unsupported) by the rest of the ecosystem, including ``pip``. 392 393 This includes updating documentation & packaging metadata as well as taking 394 advantage of basic syntax additions like set literals/comprehensions (``{1, 395 2, 3}`` instead of ``set([1, 2, 3])``) and removing positional string 396 argument specifiers (``"{}".format(val)`` instead of ``"{0}".format(val)``). 397 398- :release:`0.21.0 <2017-09-18>` 399- :feature:`132` Implement 'iterable' and 'incrementable' CLI flags, allowing 400 for invocations like ``inv mytask --listy foo --listy bar`` (resulting in a 401 call like ``mytask(listy=['foo', 'bar'])``) or ``inv mytask -vvv`` (resulting 402 in e.g. ``mytask(verbose=3)``. Specifically, these require use of the new 403 :ref:`iterable <iterable-flag-values>` and :ref:`incrementable 404 <incrementable-flag-values>` arguments to `@task <invoke.tasks.task>` - see 405 those links to the conceptual docs for details. 406- :release:`0.20.4 <2017-08-14>` 407- :bug:`-` The behavior of `Config <invoke.config.Config>` when ``lazy=True`` 408 didn't match that described in the API docs, after the recent updates to its 409 lifecycle. (Specifically, any config data given to the constructor was not 410 visible in the resulting instance until ``merge()`` was explicitly called.) 411 This has been fixed, along with other related minor issues. 412- :release:`0.20.3 <2017-08-04>` 413- :bug:`467` (Arguably also a feature, but since it enables behavior users 414 clearly found intuitive, we're considering it a bug.) Split up the parsing 415 machinery of `Program <invoke.program.Program>` and pushed the `Collection 416 <invoke.collection.Collection>`-making out of `Loader 417 <invoke.loader.Loader>`. Combined, this allows us to honor the project-level 418 config file *before* the second (task-oriented) CLI parsing step, instead of 419 after. 420 421 For example, this means you can turn off ``auto_dash_names`` in your 422 per-project configs and not only in your system or user configs. 423 424 Report again courtesy of Luke Orland. 425 426 .. warning:: 427 This is a backwards incompatible change *if* you were subclassing and 428 overriding any of the affected methods in the ``Program`` or ``Loader`` 429 classes. 430 431- :release:`0.20.2 <2017-08-02>` 432- :bug:`465` The ``tasks.auto_dash_names`` config option added in ``0.20.0`` 433 wasn't being fully honored when set to ``False``; this has been fixed. Thanks 434 to Luke Orland for the report. 435- :release:`0.20.1 <2017-07-27>` 436- :bug:`-` Fix a broken ``six.moves`` import within ``invoke.util``; was 437 causing ``ImportError`` in environments without an external copy of ``six`` 438 installed. 439 440 The dangers of one's local and CI environments all pulling down packages that 441 use ``six``! It's everywhere! 442- :release:`0.20.0 <2017-07-27>` 443- :feature:`-` (required to support :issue:`310` and :issue:`329`) Break up the 444 `~invoke.config.Config` lifecycle some more, allowing it to gradually load 445 configuration vectors; this allows the CLI machinery 446 (`~invoke.executor.Executor`) to honor configuration settings from config 447 files which impact how CLI parsing and task loading behaves. 448 449 Specifically, this adds more public ``Config.load_*`` methods, which in 450 tandem with the ``lazy`` kwarg to ``__init__`` (formerly ``defer_post_init``, 451 see below) allow full control over exactly when each config level is loaded. 452 453 .. warning:: 454 This change may be backwards incompatible if you were using or subclassing 455 the `~invoke.config.Config` class in any of the following ways: 456 457 - If you were passing ``__init__`` kwargs such as ``project_home`` or 458 ``runtime_path`` and expecting those files to auto-load, they no longer 459 do; you must explicitly call `~invoke.config.Config.load_project` and/or 460 `~invoke.config.Config.load_runtime` explicitly. 461 - The ``defer_post_init`` keyword argument to ``Config.__init__`` has been 462 renamed to ``lazy``, and controls whether system/user config files are 463 auto-loaded. 464 - ``Config.post_init`` has been removed, in favor of explicit/granular use 465 of the ``load_*`` family of methods. 466 - All ``load_*`` methods now call ``Config.merge`` automatically by default 467 (previously, merging was deferred to the end of most config related 468 workflows.) 469 470 This should only be a problem if your config contents are extremely large 471 (it's an entirely in-memory dict-traversal operation) and can be avoided 472 by specifying ``merge=False`` to any such method. (Note that you must, at 473 some point, call `~invoke.config.Config.merge` in order for the config 474 object to work normally!) 475 476- :feature:`310` (also :issue:`455`, :issue:`291`) Allow configuring collection 477 root directory & module name via configuration files (previously, they were 478 only configurable via CLI flags or generating a custom 479 `~invoke.program.Program`.) 480- :feature:`329` All task and collection names now have underscores turned into 481 dashes automatically, as task parameters have been for some time. This 482 impacts ``--list``, ``--help``, and of course the parser. For details, see 483 :ref:`dashes-vs-underscores`. 484 485 This behavior is controlled by a new config setting, 486 ``tasks.auto_dash_names``, which can be set to ``False`` to go back to the 487 classic behavior. 488 489 Thanks to Alexander Artemenko for the initial feature request. 490- :bug:`396 major` ``Collection.add_task(task, aliases=('other', 'names')`` was 491 listed in the conceptual documentation, but not implemented (technically, it 492 was removed at some point and never reinstated.) It has been (re-)added and 493 now exists. Thanks to ``@jenisys`` for the report. 494 495 .. warning:: 496 This technically changes argument order for `Collection.add_task 497 <invoke.collection.Collection.add_task>`, so be aware if you were using 498 positional arguments! 499 500- :bug:`- major` Display of hidden subprocess output when a command 501 execution failed (end-of-session output starting with ``Encountered a bad 502 command exit code!``) was liable to display encoding errors (e.g. ``'ascii' 503 codec can't encode character ...``) when that output was not 504 ASCII-compatible. 505 506 This problem was previously solved for *non-hidden* (mirrored) subprocess 507 output, but the fix (encode the data with the local encoding) had not been 508 applied to exception display. Now it's applied in both cases. 509- :feature:`322` Allow users to completely disable mirroring of stdin to 510 subprocesses, by specifying ``False`` for the ``run.in_stream`` config 511 setting and/or keyword argument. 512 513 This can help prevent problems when running Invoke under systems that have no 514 useful standard input and which otherwise defeat our pty/fileno related 515 detection. 516- :release:`0.19.0 <2017-06-19>` 517- :feature:`-` Add `MockContext.set_result_for 518 <invoke.context.MockContext.set_result_for>` to allow massaging a mock 519 Context's configured results after instantiation. 520- :release:`0.18.1 <2017-06-07>` 521- :bug:`-` Update Context internals re: command execution & configuration of 522 runner subclasses, to work better in client libraries such as Fabric 2. 523 524 .. note:: 525 If you were using the undocumented ``runner`` configuration value added 526 in :issue:`446`, it is now ``runners.local``. 527 528 .. warning:: 529 This change modifies the internals of methods like 530 `~invoke.context.Context.run` and `~invoke.context.Context.sudo`; users 531 maintaining their own subclasses should be aware of possible breakage. 532 533- :release:`0.18.0 <2017-06-02>` 534- :feature:`446` Implement `~invoke.context.Context.cd` and 535 `~invoke.context.Context.prefix` context managers (as methods on the 536 not-that-one-the-other-one `~invoke.context.Context` class.) These are based 537 on similar functionality in Fabric 1.x. Credit: Ryan P Kilby. 538- :support:`448` Fix up some config-related tests that have been failing on 539 Windows for some time. Thanks to Ryan P Kilby. 540- :feature:`205` Allow giving core flags like ``--help`` after tasks to trigger 541 per-task help. Previously, only ``inv --help taskname`` worked. 542 543 .. note:: 544 Tasks with their own ``--help`` flags won't be able to leverage this 545 feature - the parser will still interpret the flag as being per-task and 546 not global. This may change in the future to simply throw an exception 547 complaining about the ambiguity. (Feedback welcome.) 548 549- :feature:`444` Add support for being used as ``python -m invoke <args>`` on 550 Python 2.7 and up. Thanks to Pekka Klärck for the feature request. 551- :release:`0.17.0 <2017-05-05>` 552- :bug:`439 major` Avoid placing stdin into bytewise read mode when it looks 553 like Invoke has been placed in the background by a shell's job control 554 system; doing so was causing the shell to pause the Invoke process (e.g. with 555 a message like ``suspended (tty output)``.) Reported by Tuukka Mustonen. 556- :bug:`425 major` Fix ``Inappropriate ioctl for device`` errors (usually 557 ``OSError``) when running Invoke without a tty-attached stdin (i.e. when run 558 under 'headless' continuous integration systems or simply as e.g. ``inv 559 sometask < /dev/null`` (redirected stdin.) Thanks to Javier Domingo Cansino 560 for the report & Tuukka Mustonen for troubleshooting assistance. 561- :feature:`-` Add a ``user`` kwarg & config parameter to 562 `Context.sudo <invoke.context.Context.sudo>`, which corresponds roughly to 563 ``sudo -u <user> <command>``. 564- :bug:`440 major` Make sure to skip a call to ``struct``/``ioctl`` on Windows 565 platforms; otherwise certain situations inside ``run`` calls would trigger 566 import errors. Thanks to ``@chrisc11`` for the report. 567- :release:`0.16.3 <2017-04-18>` 568- :bug:`-` Even more setup.py related tomfoolery. 569- :release:`0.16.2 <2017-04-18>` 570- :bug:`-` Deal with the fact that PyPI's rendering of Restructured Text has no 571 idea about our fancy new use of Sphinx's doctest module. Sob. 572- :release:`0.16.1 <2017-04-18>` 573- :bug:`-` Fix a silly typo preventing proper rendering of the packaging 574 ``long_description`` (causing an effectively blank PyPI description.) 575- :release:`0.16.0 <2017-04-18>` 576- :feature:`232` Add support for ``.yml``-suffixed config files (in addition to 577 ``.yaml``, ``.json`` and ``.py``.) Thanks to Matthias Lehmann for the 578 original request & Greg Back for an early patch. 579- :feature:`418` Enhance ability of client libraries to override config 580 filename prefixes. This includes modifications to related functionality, such 581 as how env var prefixes are configured. 582 583 .. warning:: 584 **This is a backwards incompatible change** if: 585 586 - you were relying on the ``env_prefix`` keyword argument to 587 `Config.__init__ <invoke.config.Config.__init__>`; it is now the 588 ``prefix`` or ``env_prefix`` class attribute, depending. 589 - or the kwarg/attribute of the same name in `Program.__init__ 590 <invoke.program.Program.__init__>`; you should now be subclassing 591 ``Config`` and using its ``env_prefix`` attribute; 592 - or if you were relying on how standalone ``Config`` objects defaulted to 593 having a ``None`` value for ``env_prefix``, and thus loaded env vars 594 without an ``INVOKE_`` style prefix. 595 596 See new documentation for this functionality at 597 :ref:`customizing-config-defaults` for details. 598 599- :feature:`309` Overhaul how task execution contexts/configs are handled, such 600 that all contexts in a session now share the same config object, and thus 601 user modifications are preserved between tasks. This has been done in a 602 manner that should not break things like collection-based config (which may 603 still differ from task to task.) 604 605 .. warning:: 606 **This is a backwards incompatible change** if you were relying on the 607 post-0.12 behavior of cloning config objects between each task execution. 608 Make sure to investigate if you find tasks affecting one another in 609 unexpected ways! 610 611- :support:`-` Fixed some Python 2.6 incompatible string formatting that snuck 612 in recently. 613- :feature:`-` Switched the order of the first two arguments of 614 `Config.__init__ <invoke.config.Config.__init__>`, so that the ``overrides`` 615 kwarg becomes the first positional argument. 616 617 This supports the common use case of making a `Config <invoke.config.Config>` 618 object that honors the system's core/global defaults; previously, because 619 ``defaults`` was the first argument, you'd end up replacing those core 620 defaults instead of merging with them. 621 622 .. warning:: 623 **This is a backwards incompatible change** if you were creating custom 624 ``Config`` objects via positional, instead of keyword, arguments. It should 625 have no effect otherwise. 626 627- :feature:`-` `Context.sudo <invoke.context.Context.sudo>` no longer prompts 628 the user when the configured sudo password is empty; thus, an empty sudo 629 password and a ``sudo`` program configured to require one will result in an 630 exception. 631 632 The runtime prompting for a missing password was a temporary holdover from 633 Fabric v1, and in retrospect is undesirable. We may add it back in as an 634 opt-in behavior (probably via subclassing) in the future if anybody misses 635 it. 636 637 .. warning:: 638 **This is a backwards incompatible change**, if you were relying on 639 ``sudo()`` prompting you for your password (vs configuring it). If you 640 *were* doing that, you can simply switch to ``run("sudo <command>")`` and 641 respond to the subprocess' sudo prompt by hand instead. 642 643- :feature:`-` `Result <invoke.runners.Result>` and `UnexpectedExit 644 <invoke.exceptions.UnexpectedExit>` objects now have a more useful ``repr()`` 645 (and in the case of ``UnexpectedExit``, a distinct ``repr()`` from their 646 preexisting ``str()``.) 647- :bug:`432 major` Tighten application of IO thread ``join`` timeouts (in `run 648 <invoke.runners.Runner.run>`) to only happen when :issue:`351` appears 649 actually present. Otherwise, slow/overworked IO threads had a chance of being 650 joined before truly reading all data from the subprocess' pipe. 651- :bug:`430 major` Fallback importing of PyYAML when Invoke has been installed 652 without its vendor directory, was still trying to import the vendorized 653 module names (e.g. ``yaml2`` or ``yaml3`` instead of simply ``yaml``). This 654 has been fixed, thanks to Athmane Madjoudj. 655- :release:`0.15.0 <2017-02-14>` 656- :bug:`426 major` `DataProxy <invoke.config.DataProxy>` based classes like 657 `Config <invoke.config.Config>` and `Context <invoke.context.Context>` didn't 658 like being `pickled <pickle>` or `copied <copy.copy>` and threw 659 ``RecursionError``. This has been fixed. 660- :feature:`-` `Config <invoke.config.Config>`'s internals got cleaned up 661 somewhat; end users should not see much of a difference, but advanced 662 users or authors of extension code may notice the following: 663 664 - Direct modification of config data (e.g. ``myconfig.section.subsection.key 665 = 'value'`` in user/task code) is now stored in its own config 'level'/data 666 structure; previously such modifications simply mutated the central, 667 'merged' config cache. This makes it much easier to determine where a final 668 observed value came from, and prevents accidental data loss. 669 - Ditto for deleted values. 670 - Merging/reconciliation of the config levels now happens automatically when 671 data is loaded or modified, which not only simplifies the object's 672 lifecycle a bit but allows the previous change to function without 673 requiring users to call ``.merge()`` after every modification. 674 675- :bug:`- major` Python 3's hashing rules differ from Python 2, specifically: 676 677 A class that overrides ``__eq__()`` and does not define ``__hash__()`` will 678 have its ``__hash__()`` implicitly set to None. 679 680 `Config <invoke.config.Config>` (specifically, its foundational class 681 `DataProxy <invoke.config.DataProxy>`) only defined ``__eq__`` which, 682 combined with the above behavior, meant that ``Config`` objects appeared to 683 hash successfully on Python 2 but yielded ``TypeErrors`` on Python 3. 684 685 This has been fixed by explicitly setting ``__hash__ = None`` so that the 686 objects do not hash on either interpreter (there are no good immutable 687 attributes by which to define hashability). 688- :bug:`- major` Configuration keys named ``config`` were inadvertently 689 exposing the internal dict representation of the containing config object, 690 instead of displaying the actual value stored in that key. (Thus, a set 691 config of ``mycontext.foo.bar.config`` would act as if it was the key/value 692 contents of the ``mycontext.foo.bar`` subtree.) This has been fixed. 693- :feature:`421` Updated `Config.clone <invoke.config.Config.clone>` (and a few 694 other related areas) to replace use of `copy.deepcopy` with a less-rigorous 695 but also less-likely-to-explode recursive dict copier. This prevents 696 frustrating ``TypeErrors`` while still preserving barriers between different 697 tasks' configuration values. 698- :feature:`-` `Config.clone <invoke.config.Config.clone>` grew a new ``into`` 699 kwarg allowing client libraries with their own `~invoke.config.Config` 700 subclasses to easily "upgrade" vanilla Invoke config objects into their local 701 variety. 702- :bug:`419 major` Optional parser arguments had a few issues: 703 704 - The :ref:`conceptual docs about CLI parsing <optional-values>` mentioned 705 them, but didn't actually show via example how to enable the feature, 706 implying (incorrectly) that they were active always by default. An example 707 has been added. 708 - Even when enabled, they did not function correctly when their default 709 values were of type ``bool``; in this situation, trying to give a value (vs 710 just giving the flag name by itself) caused a parser error. This has been 711 fixed. 712 713 Thanks to ``@ouroboroscoding`` for the report. 714- :support:`204` (via :issue:`412`) Fall back to globally-installed copies of 715 our vendored dependencies, if the import from the ``vendor`` tree fails. In 716 normal situations this won't happen, but it allows advanced users or 717 downstream maintainers to nuke ``vendor/`` and prefer explicitly installed 718 packages of e.g. ``six``, ``pyyaml`` or ``fluidity``. Thanks to Athmane 719 Madjoudj for the patch. 720- :bug:`- major` Fix configuration framework such that nested or dict-like 721 config values may be compared with regular dicts. Previously, doing so caused 722 an ``AttributeError`` (as regular dicts lack a ``.config``). 723- :bug:`413 major` Update behavior of ``DataProxy`` (used within 724 `~invoke.context.Context` and `~invoke.config.Config`) again, fixing two 725 related issues: 726 727 - Creating new configuration keys via attribute access wasn't possible: one 728 had to do ``config['foo'] = 'bar'`` because ``config.foo = 'bar'`` would 729 set a real attribute instead of touching configuration. 730 - Supertypes' attributes weren't being considered during the "is this a real 731 attribute on ``self``?" test, leading to different behavior between a 732 nested config-value-as-attribute and a top-level Context/Config one. 733 734- :release:`0.14.0 <2016-12-05>` 735- :bug:`349 major` Display the string representation of 736 `~invoke.exceptions.UnexpectedExit` when handling it inside of 737 `~invoke.program.Program` (including regular ``inv``), if any output was 738 hidden during the ``run`` that generated it. 739 740 Previously, we only exited with the exception's stored exit code, meaning 741 failures of ``run(..., hide=True)`` commands were unexpectedly silent. 742 (Library-style use of the codebase didn't have this problem, since tracebacks 743 aren't muted.) 744 745 While implementing this change, we also tweaked the overall display of 746 ``UnexpectedExit`` so it's a bit more consistent & useful: 747 748 - noting "hey, you ran with ``pty=True``, so there's no stderr"; 749 - showing only the last 10 lines of captured output in the error message 750 (users can, of course, always manually handle the error & access the full 751 thing if desired); 752 - only showing a given stream when it was not already printed to the user's 753 terminal (i.e. if ``hide=False``, no captured output is shown in the error 754 text; if ``hide='stdout'``, only stdout is shown in the error text; etc.) 755 756 Thanks to Patrick Massot for the original bug report. 757 758- :feature:`-` Expose the (normalized) value of `~invoke.runners.Runner.run`'s 759 ``hide`` parameter in its return-value `~invoke.runners.Result` objects. 760- :bug:`288 major` Address a bug preventing reuse of Invoke as a custom 761 binstub, by moving ``--list`` into the "core args" set of flags present on 762 all Invoke-derived binstubs. Thanks to Jordon Mears for catch & patch. 763- :bug:`283 major` Fix the concepts/library docs so the example of an explicit 764 ``namespace=`` argument correctly shows wrapping an imported task module in a 765 `~invoke.collection.Collection`. Thanks to ``@zaiste`` for the report. 766- :bug:`- major` Fix ``DataProxy`` (used within `~invoke.context.Context` and 767 `~invoke.config.Config`) so that real attributes and methods which are 768 shadowed by configuration keys, aren't proxied to the config during regular 769 attribute get/set. (Such config keys are thus required to be accessed via 770 dict-style only, or (on `~invoke.context.Context`) via the explicit 771 ``.config`` attribute.) 772- :bug:`58 major` Work around bugs in ``select()`` when handling subprocess 773 stream reads, which was causing poor behavior in many nontrivial interactive 774 programs (such as ``vim`` and other fullscreen editors, ``python`` and other 775 REPLs/shells, etc). Such programs should now be largely indistinguishable 776 from their behavior when run directly from a user's shell. 777- :feature:`406` Update handling of Ctrl-C/``KeyboardInterrupt``, and 778 subprocess exit status pass-through, to be more correct than before: 779 780 - Submit the interrupt byte sequence ``\x03`` to stdin of all subprocesses, 781 instead of sending ``SIGINT``. 782 783 - This results in behavior closer to that of truly pressing Ctrl-C when 784 running subprocesses directly; for example, interactive programs like 785 ``vim`` or ``python`` now behave normally instead of prematurely 786 exiting. 787 - Of course, programs that would normally exit on Ctrl-C will still do 788 so! 789 790 - The exit statuses of subprocesses run with ``pty=True`` are more rigorously 791 checked (using `os.WIFEXITED` and friends), allowing us to surface the real 792 exit values of interrupted programs instead of manually assuming exit code 793 ``130``. 794 795 - Typically, this will be exit code ``-2``, but it is system dependent. 796 - Other, non-Ctrl-C-driven signal-related exits under PTYs should behave 797 better now as well - previously they could appear to exit ``0``! 798 799 - Non-subprocess-related ``KeyboardInterrupt`` (i.e. those generated when 800 running top level Python code outside of any ``run`` function calls) 801 will now trigger exit code ``1``, as that is how the Python interpreter 802 typically behaves if you ``KeyboardInterrupt`` it outside of a live 803 REPL. 804 805 .. warning:: 806 These changes are **backwards incompatible** if you were relying on the 807 "exits ``130``" behavior added in version 0.13, or on the (incorrect) 808 ``SIGINT`` method of killing pty-driven subprocesses on Ctrl-C. 809 810- :bug:`- major` Correctly raise ``TypeError`` when unexpected keyword 811 arguments are given to `~invoke.runners.Runner.run`. 812- :feature:`-` Add a `~invoke.context.MockContext` class for easier testing of 813 user-written tasks and related client code. Includes adding a 814 :ref:`conceptual document on how to test Invoke-using code 815 <testing-user-code>`. 816- :feature:`-` Update implementation of `~invoke.runners.Result` so it has 817 default values for all parameters/attributes. This allows it to be more 818 easily used when mocking ``run`` calls in client libraries' tests. 819 820 .. warning:: 821 This is a backwards incompatible change if you are manually instantiating 822 `~invoke.runners.Result` objects with positional arguments: positional 823 argument order has changed. (Compare the API docs between versions to see 824 exactly how.) 825 826- :feature:`294` Implement `Context.sudo <invoke.context.Context.sudo>`, which 827 wraps `~invoke.context.Context.run` inside a ``sudo`` command. It is capable 828 of auto-responding to ``sudo``'s password prompt with a configured password, 829 and raises a specific exception (`~invoke.exceptions.AuthFailure`) if that 830 password is rejected. 831- :feature:`369` Overhaul the autoresponse functionality for `~invoke.run` so 832 it's significantly more extensible, both for its own sake and as part of 833 implementing :issue:`294` (see its own changelog entry for details). 834 835 .. warning:: 836 This is a backwards incompatible change: the ``responses`` kwarg to 837 ``run()`` is now ``watchers``, and accepts a list of 838 `~invoke.watchers.StreamWatcher` objects (such as 839 `~invoke.watchers.Responder`) instead of a dict. 840 841 If you were using ``run(..., responses={'pattern': 'response'}`` 842 previously, just update to instead use ``run(..., 843 watchers=[Responder('pattern', 'response')])``. 844 845- :bug:`- major` Fix a bug in `Config.clone <invoke.config.Config.clone>` where 846 it was instantiating a new ``Config`` instead of a member of the subclass. 847- :release:`0.13.0 <2016-06-09>` 848- :feature:`114` Ripped off the band-aid and removed non-contextualized tasks 849 as an option; all tasks must now be contextualized (defined as ``def 850 mytask(context, ...)`` - see :ref:`defining-and-running-task-functions`) even 851 if not using the context. This simplifies the implementation as well as 852 users' conceptual models. Thanks to Bay Grabowski for the patch. 853 854 .. warning:: This is a backwards incompatible change! 855 856- :bug:`350 major` (also :issue:`274`, :issue:`241`, :issue:`262`, 857 :issue:`242`, :issue:`321`, :issue:`338`) Clean up and reorganize 858 encoding-related parts of the code to avoid some of the more common or 859 egregious encode/decode errors surrounding clearly non-ASCII-compatible text. 860 Bug reports, assistance, feedback and code examples courtesy of Paul Moore, 861 Vlad Frolov, Christian Aichinger, Fotis Gimian, Daniel Nunes, and others. 862- :bug:`351 major` Protect against ``run`` deadlocks involving exceptions in 863 I/O threads & nontrivial amounts of unread data in the corresponding 864 subprocess pipe(s). This situation should now always result in exceptions 865 instead of hangs. 866- :feature:`259` (also :issue:`280`) Allow updating (or replacing) subprocess 867 shell environments, via the ``env`` and ``replace_env`` kwargs to 868 `~invoke.runners.Runner.run`. Thanks to Fotis Gimian for the report, 869 ``@philtay`` for an early version of the final patch, and Erich Heine & Vlad 870 Frolov for feedback. 871- :feature:`67` Added ``shell`` option to `~invoke.runners.Runner.run`, 872 allowing control of the shell used when invoking commands. Previously, 873 ``pty=True`` used ``/bin/bash`` and ``pty=False`` (the default) used 874 ``/bin/sh``; the new unified default value is ``/bin/bash``. 875 876 Thanks to Jochen Breuer for the report. 877- :bug:`152 major` (also :issue:`251`, :issue:`331`) Correctly handle 878 ``KeyboardInterrupt`` during `~invoke.runners.Runner.run`, re: both mirroring 879 the interrupt signal to the subprocess *and* capturing the local exception 880 within Invoke's CLI handler (so there's no messy traceback, just exiting with 881 code ``130``). 882 883 Thanks to Peter Darrow for the report, and to Mika Eloranta & Máté Farkas for 884 early versions of the patchset. 885- :support:`319` Fixed an issue resulting from :issue:`255` which 886 caused problems with how we generate release wheels (notably, some releases 887 such as 0.12.1 fail when installing from wheels on Python 2). 888 889 .. note:: 890 As part of this fix, the next release will distribute individual Python 2 891 and Python 3 wheels instead of one 'universal' wheel. This change should be 892 transparent to users. 893 894 Thanks to ``@ojos`` for the initial report and Frazer McLean for some 895 particularly useful feedback. 896- :release:`0.12.2 <2016-02-07>` 897- :support:`314 backported` (Partial fix.) Update ``MANIFEST.in`` so source 898 distributions include some missing project-management files (e.g. our 899 internal ``tasks.py``). This makes unpacked sdists more useful for things 900 like running the doc or build tasks. 901- :bug:`303` Make sure `~invoke.run` waits for its IO worker threads to cleanly 902 exit (such as allowing a ``finally`` block to revert TTY settings) when 903 ``KeyboardInterrupt`` (or similar) aborts execution in the main thread. 904 Thanks to Tony S Yu and Máté Farkas for the report. 905- :release:`0.12.1 <2016-02-03>` 906- :bug:`308` Earlier changes to TTY detection & its use in determining features 907 such as stdin pass-through, were insufficient to handle edge cases such as 908 nested Invoke sessions or piped stdin to Invoke processes. This manifested as 909 hangs and ``OSError`` messages about broken pipes. 910 911 The issue has been fixed by overhauling all related code to use more specific 912 and accurate checks (e.g. examining just ``fileno`` and/or just ``isatty``). 913 914 Thanks to Tuukka Mustonen and Máté Farkas for the report (and for enduring 915 the subsequent flood of the project maintainer's stream-of-consciousness 916 ticket updates). 917- :bug:`305` (also :issue:`306`) Fix up some test-suite issues causing failures 918 on Windows/Appveyor. Thanks to Paul Moore. 919- :bug:`289` Handful of issues, all fallout from :issue:`289`, which failed to 920 make it out the door for 0.12.0. More are on the way but these should address 921 blockers for some users: 922 923 * Windows support for the new stdin replication functionality (this was 924 totally blocking Windows users, as reported in :issue:`302` - sorry!); 925 * Stdin is now mirrored to stdout when no PTY is present, so you can see 926 what you're typing (plus a new `~invoke.runners.Runner.run` option and 927 config param, ``echo_stdin``, allowing user override of this behavior); 928 * Exposed the stdin read loop's sleep time as `Runner.input_sleep 929 <invoke.runners.Runner.input_sleep>`; 930 * Sped up some tests a bit. 931 932- :release:`0.12.0 <2016-01-12>` 933- :bug:`257 major` Fix a RecursionError under Python 3 due to lack of 934 ``__deepcopy__`` on `~invoke.tasks.Call` objects. Thanks to Markus 935 Zapke-Gründemann for initial report and Máté Farkas for the patch. 936- :support:`265` Update our Travis config to select its newer build 937 infrastructure and also run on PyPy3. Thanks to Omer Katz. 938- :support:`254` Add an ``exclude`` option in our ``setup.py`` so setuptools 939 doesn't try loading our vendored PyYAML's Python 2 sub-package under Python 3 940 (or vice versa - though all reports were from Python 3 users). Thanks to 941 ``@yoshiya0503`` for catch & initial patch. 942- :feature:`68` Disable Python's bytecode caching by default, as it complicates 943 our typical use case (frequently-changing .py files) and offers little 944 benefit for human-facing startup times. Bytecode caching can be explicitly 945 re-enabled by specifying ``--write-pyc`` at runtime. Thanks to Jochen Breuer 946 for feature request and ``@brutus`` for initial patchset. 947- :support:`144` Add code-coverage reporting to our CI builds (albeit `CodeCov 948 <https://codecov.io>`_ instead of `coveralls.io <https://coveralls.io>`_). 949 Includes rejiggering our project-specific coverage-generating tasks. Thanks 950 to David Baumgold for the original request/PR and to Justin Abrahms for the 951 tipoff re: CodeCov. 952- :bug:`297 major` Ignore leading and trailing underscores when turning task 953 arguments into CLI flag names. 954- :bug:`296 major` Don't mutate ``sys.path`` on collection load if task's 955 parent directory is already on ``sys.path``. 956- :bug:`295 major` Make sure that `~invoke.run`'s ``hide=True`` also disables 957 echoing. Otherwise, "hidden" helper ``run`` calls will still pollute output 958 when run as e.g. ``invoke --echo ...``. 959- :feature:`289` (also :issue:`263`) Implement :ref:`autoresponding 960 <autoresponding>` for `~invoke.run`. 961- :support:`-` Removed official Python 3.2 support; sibling projects also did 962 this recently, it's simply not worth the annoyance given the userbase size. 963- :feature:`228` (partial) Modified and expanded implementation of 964 `~invoke.executor.Executor`, `~invoke.tasks.Task` and `~invoke.tasks.Call` to 965 make implementing task parameterization easier. 966- :support:`-` Removed the ``-H`` short flag, leaving just ``--hide``. This was 967 done to avoid conflicts with Fabric's host-oriented ``-H`` flag. Favoritism 968 is real! Apologies. 969 970 .. warning:: This change is backwards compatible if you used ``-H``. 971 972- :feature:`173` Overhauled top level CLI functionality to allow reusing 973 Invoke for distinct binaries, optionally with bundled task namespaces as 974 subcommands. As a side effect, this functionality is now much more extensible 975 to boot. Thanks to Erich Heine for feedback/suggestions during development. 976 977 .. warning:: 978 This change is backwards incompatible if you imported anything from the 979 ``invoke.cli`` module (which is now rearchitected as 980 `~invoke.program.Program`). It should be transparent to everybody else. 981 982 .. seealso:: :ref:`reusing-as-a-binary` 983 984- :bug:`- major` Fixed a bug in the parser where ``invoke --takes-optional-arg 985 avalue --anotherflag`` was incorrectly considering ``--anotherflag`` to be an 986 ambiguity error (as if ``avalue`` had not been given to 987 ``--takes-optional-arg``. 988- :release:`0.11.1 <2015-09-07>` 989- :support:`- backported` Fix incorrect changelog URL in package metadata. 990- :release:`0.11.0 <2015-09-07>` 991- :feature:`-` Add a ``.command`` attribute to `~invoke.runners.Result` to 992 preserve the command executed for post-execution introspection. 993- :feature:`-` Detect local controlling terminal size 994 (`~invoke.terminals.pty_size`) and apply that information when creating 995 pseudoterminals in `~invoke.run` when ``pty=True``. 996- :bug:`- major` Display stdout instead of stderr in the ``repr()`` of 997 `~invoke.exceptions.Failure` objects, when a pseudo-terminal was used. 998 Previously, failure display focused on the stderr stream, which is always 999 empty under pseudo-terminals. 1000- :bug:`- major` Correctly handle situations where `sys.stdin` has been 1001 replaced with an object lacking ``.fileno`` (e.g., some advanced Python 1002 shells, headless code execution tools, etc). Previously, this situation 1003 resulted in an ``AttributeError``. 1004- :bug:`- major` Capture & reraise exceptions generated by command execution I/O 1005 threads, in the main thread, as a `~invoke.exceptions.ThreadException`. 1006- :feature:`235` Allow custom stream objects to be used in `~invoke.run` calls, 1007 to be used instead of the defaults of ``sys.stdout``/``sys.stderr``. 1008 1009 .. warning:: 1010 This change required a major cleanup/rearchitecture of the command 1011 execution implementation. The vendored ``pexpect`` module has been 1012 completely removed and the API of the `~invoke.runners.Runner` class has 1013 changed dramatically (though **the API for run() itself has not**). 1014 1015 Be aware there may be edge-case terminal behaviors which have changed or 1016 broken as a result of removing ``pexpect``. Please report these as bugs! We 1017 expect to crib small bits of what ``pexpect`` does but need concrete test 1018 cases first. 1019 1020- :bug:`234 major` (also :issue:`243`) Preserve task-module load location when 1021 creating explicit collections with 1022 `~invoke.collection.Collection.from_module`; when this was not done, 1023 project-local config files were not loading correctly. Thanks to ``@brutus`` 1024 and Jan Willems for initial report & troubleshooting, and to Greg Back for 1025 identifying the fix. 1026- :bug:`237 major` Completion output lacked "inverse" flag names (e.g. 1027 ``--no-myoption`` as a boolean negative version of a defaulting-to-True 1028 boolean ``myoption``). This has been corrected. 1029- :bug:`239 major` Completion erroneously presented core flags instead of 1030 per-task flags when both are present in the invocation being completed (e.g. 1031 ``inv --debug my_task -<tab>``). This has been fixed. 1032- :bug:`238 major` (partial fix) Update the ``zsh`` completion script to 1033 account for use of the ``--collection`` core flag. 1034- :support:`-` Additional rearranging of ``run``/``Runner`` related concerns 1035 for improved subclassing, organization, and use in other libraries, 1036 including: 1037 1038 * Changed the name of the ``runner`` module to ``runners``. 1039 * Moved the top level ``run`` function from its original home in 1040 ``invoke.runner`` to `invoke.__init__ <invoke>`, to reflect the fact that 1041 it's now simply a convenience wrapper around ``Runner``. 1042 * Tweaked the implementation of `~invoke.runners.Runner` so it can 1043 reference `~invoke.context.Context` objects (useful for anticipated 1044 subclasses). 1045 1046 .. warning:: 1047 These are backwards incompatible changes if your code was doing any imports 1048 from the ``invoke.runner`` module (including especially 1049 ``invoke.runner.run``, which is now only ``invoke.run``). Function 1050 signatures have **not** changed. 1051 1052- :support:`224` Add a completion script for the ``fish`` shell, courtesy of 1053 Jaime Marquínez Ferrándiz. 1054- :release:`0.10.1 <2015-03-17>` 1055- :support:`- backported` Tweak README to reflect recent(-ish) changes in 1056 ``pip`` re: users who install the development version via ``pip`` instead of 1057 using git. 1058- :release:`0.10.0 <2015-03-17>` 1059- :feature:`104` Add core CLI flag ``--complete`` to support shell tab 1060 completion scripts, and add some 'blessed' such scripts for bash (3 and 4) 1061 and zsh. Thanks to Ivan Malison and Andrew Roberts for providing discussion & 1062 early patchsets. 1063- :support:`-` Reorganize `~invoke.runners.Runner`, `~invoke.runners.Local` and 1064 ``invoke.runner.run`` for improved distribution of responsibilities & 1065 downstream subclassing. 1066 1067 .. warning:: 1068 This includes backwards incompatible changes to the API signature of most 1069 members of the ``invoke.runner`` module, including ``invoke.runner.run``. 1070 (However, in the case of ``invoke.runner.run``, the changes are mostly in 1071 the later, optional keyword arguments.) 1072 1073- :feature:`219` Fall back to non-PTY command execution in situations where 1074 ``pty=True`` but no PTY appears present. See `~invoke.runners.Local` for 1075 details. 1076- :support:`212` Implement basic linting support using ``flake8``, and apply 1077 formatting changes to satisfy said linting. As part of this shakeup, also 1078 changed all old-style (``%s``) string formatting to new-style (``{0}``). 1079 Thanks to Collin Anderson for the foundational patch. 1080- :support:`215` (also :issue:`213`, :issue:`214`) Tweak tests & configuration 1081 sections of the code to include Windows compatibility. Thanks to Paul Moore. 1082- :bug:`201 major` (also :issue:`211`) Replace the old, first-draft gross 1083 monkeypatched Popen code used for ``invoke.runner.run`` with a 1084 non-monkeypatched approach that works better on non-POSIX platforms like 1085 Windows, and also attempts to handle encoding and locale issues more 1086 gracefully (meaning: at all gracefully). 1087 1088 Specifically, the new approach uses threading instead of ``select.select``, 1089 and performs explicit encoding/decoding based on detected or explicitly 1090 expressed encodings. 1091 1092 Major thanks to Paul Moore for an enormous amount of 1093 testing/experimentation/discussion, as well as the bulk of the code changes 1094 themselves. 1095 1096 .. warning:: 1097 The top level ``invoke.runner.run`` function has had a minor signature 1098 change: the sixth positional argument used to be ``runner`` and is now 1099 ``encoding`` (with ``runner`` now being the seventh positional argument). 1100 1101- :feature:`147` Drastically overhaul/expand the configuration system to 1102 account for multiple configuration levels including (but not limited to) file 1103 paths, environment variables, and Python-level constructs (previously the 1104 only option). See :ref:`configuration` for details. Thanks to Erich Heine for 1105 his copious feedback on this topic. 1106 1107 .. warning:: 1108 This is technically a backwards incompatible change, though some existing 1109 user config-setting code may continue to work as-is. In addition, this 1110 system may see further updates before 1.0. 1111 1112- :bug:`191 major` Bypass ``pexpect``'s automatic command splitting to avoid 1113 issues running complex nested/quoted commands under a pty. Credit to 1114 ``@mijikai`` for noticing the problem. 1115- :bug:`183 major` Task docstrings whose first line started on the same line as 1116 the opening quote(s) were incorrectly presented in ``invoke --help <task>``. 1117 This has been fixed by using `inspect.getdoc`. Thanks to Pekka Klärck for the 1118 catch & suggested fix. 1119- :bug:`180 major` Empty invocation (e.g. just ``invoke`` with no flags or 1120 tasks, and when no default task is defined) no longer printed help output, 1121 instead complaining about the lack of default task. It now prints help again. 1122 Thanks to Brent O'Connor for the catch. 1123- :bug:`175 major` ``autoprint`` did not function correctly for tasks stored 1124 in sub-collections; this has been fixed. Credit: Matthias Lehmann. 1125- :release:`0.9.0 <2014-08-26>` 1126- :bug:`165 major` Running ``inv[oke]`` with no task names on a collection 1127 containing a default task should (intuitively) have run that default task, 1128 but instead did nothing. This has been fixed. 1129- :bug:`167 major` Running the same task multiple times in one CLI session was 1130 horribly broken; it works now. Thanks to Erich Heine for the report. 1131- :bug:`119 major` (also :issue:`162`, :issue:`113`) Better handle 1132 platform-sensitive operations such as pty size detection or use, either 1133 replacing with platform-specific implementations or raising useful 1134 exceptions. Thanks to Gabi Davar and (especially) Paul Moore, for feedback & 1135 original versions of the final patchset. 1136- :feature:`136` Added the ``autoprint`` flag to 1137 `invoke.tasks.Task`/`@task <invoke.tasks.task>`, allowing users to set up 1138 tasks which act as both subroutines & "print a result" CLI tasks. Thanks to 1139 Matthias Lehmann for the original patch. 1140- :bug:`162 major` Adjust platform-sensitive imports so Windows users don't 1141 encounter import-time exceptions. Thanks to Paul Moore for the patch. 1142- :support:`169` Overhaul the Sphinx docs into two trees, one for main project 1143 info and one for versioned API docs. 1144- :bug:`- major` Fixed a sub-case of the already-mostly-fixed :issue:`149` so 1145 the error message works usefully even with no explicit collection name given. 1146- :release:`0.8.2 <2014-06-15>` 1147- :bug:`149` Print a useful message to stderr when Invoke can't find the 1148 requested collection/tasks file, instead of displaying a traceback. 1149- :bug:`145` Ensure a useful message is displayed (instead of a confusing 1150 exception) when listing empty task collections. 1151- :bug:`142` The refactored Loader class failed to account for the behavior of 1152 `imp.find_module` when run against packages (vs modules) and was exploding at 1153 load time. This has been fixed. Thanks to David Baumgold for catch & patch. 1154- :release:`0.8.1 <2014-06-09>` 1155- :bug:`140` Revert incorrect changes to our ``setup.py`` regarding detection 1156 of sub-packages such as the vendor tree & the parser. Also add additional 1157 scripting to our Travis-CI config to catch this class of error in future. 1158 Thanks to Steven Loria and James Cox for the reports. 1159- :release:`0.8.0 <2014-06-08>` 1160- :feature:`135` (also bugs :issue:`120`, :issue:`123`) Implement post-tasks to 1161 match pre-tasks, and allow control over the arguments passed to both (via 1162 `invoke.tasks.call`). For details, see :ref:`pre-post-tasks`. 1163 1164 .. warning:: 1165 Pre-tasks were overhauled a moderate amount to implement this feature; 1166 they now require references to **task objects** instead of **task 1167 names**. This is a backwards incompatible change. 1168 1169- :support:`25` Trim a bunch of time off the test suite by using mocking and 1170 other tools instead of dogfooding a bunch of subprocess spawns. 1171- :bug:`128 major` Positional arguments containing underscores were not 1172 exporting to the parser correctly; this has been fixed. Thanks to J. Javier 1173 Maestro for catch & patch. 1174- :bug:`121 major` Add missing help output denoting inverse Boolean options 1175 (i.e. ``--[no-]foo`` for a ``--foo`` flag whose value defaults to true.) 1176 Thanks to Andrew Roberts for catch & patch. 1177- :support:`118` Update the bundled ``six`` plus other minor tweaks to support 1178 files. Thanks to Matt Iversen. 1179- :feature:`115` Make it easier to reuse Invoke's primary CLI machinery in 1180 other (non-Invoke-distributed) bin-scripts. Thanks to Noah Kantrowitz. 1181- :feature:`110` Add task docstrings' 1st lines to ``--list`` output. Thanks to 1182 Hiroki Kiyohara for the original PR (with assists from Robert Read and James 1183 Thigpen.) 1184- :support:`117` Tidy up ``setup.py`` a bit, including axing the (broken) 1185 `distutils` support. Thanks to Matt Iversen for the original PR & followup 1186 discussion. 1187- :feature:`87` (also :issue:`92`) Rework the loader module such that recursive 1188 filesystem searching is implemented, and is used instead of searching 1189 `sys.path`. 1190 1191 This adds the behavior most users expect or are familiar with from Fabric 1 1192 or similar tools; and it avoids nasty surprise collisions with other 1193 installed packages containing files named ``tasks.py``. 1194 1195 Thanks to Michael Hahn for the original report & PR, and to Matt Iversen for 1196 providing the discovery algorithm used in the final version of this change. 1197 1198 .. warning:: 1199 This is technically a backwards incompatible change (reminder: we're not 1200 at 1.0 yet!). You'll only notice if you were relying on adding your tasks 1201 module to ``sys.path`` and then calling Invoke elsewhere on the 1202 filesystem. 1203 1204- :support:`-` Refactor the `invoke.runners.Runner` module to differentiate 1205 what it means to run a command in the abstract, from execution specifics. Top 1206 level API is unaffected. 1207- :bug:`131 major` Make sure one's local tasks module is always first in 1208 ``sys.path``, even if its parent directory was already somewhere else in 1209 ``sys.path``. This ensures that local tasks modules never become hidden by 1210 third-party ones. Thanks to ``@crccheck`` for the early report and to Dorian 1211 Puła for assistance fixing. 1212- :bug:`116 major` Ensure nested config overrides play nicely with default 1213 tasks and pre-tasks. 1214- :bug:`127 major` Fill in tasks' exposed ``name`` attribute with body name if 1215 explicit name not given. 1216- :feature:`124` Add a ``--debug`` flag to the core parser to enable easier 1217 debugging (on top of existing ``INVOKE_DEBUG`` env var.) 1218- :feature:`125` Improve output of Failure exceptions when printed. 1219- :release:`0.7.0 <2014.01.28>` 1220- :feature:`109` Add a ``default`` kwarg to 1221 `invoke.collection.Collection.add_task` allowing per-collection control over 1222 default tasks. 1223- :feature:`108` Update `invoke.collection.Collection.from_module` to accept 1224 useful shorthand arguments for tweaking the `invoke.collection.Collection` 1225 objects it creates (e.g. name, configuration.) 1226- :feature:`107` Update configuration merging behavior for more flexible reuse 1227 of imported task modules, such as parameterizing multiple copies of a module 1228 within a task tree. 1229- :release:`0.6.1 <2013.11.21>` 1230- :bug:`96` Tasks in subcollections which set explicit names (via e.g. 1231 ``@task(name='foo')``) were not having those names honored. This is fixed. 1232 Thanks to Omer Katz for the report. 1233- :bug:`98` **BACKWARDS INCOMPATIBLE CHANGE!** Configuration merging has been 1234 reversed so outer collections' config settings override inner collections. 1235 This makes distributing reusable modules significantly less silly. 1236- :release:`0.6.0 <2013.11.21>` 1237- :bug:`86 major` Task arguments named with an underscore broke the help feature; 1238 this is now fixed. Thanks to Stéphane Klein for the catch. 1239- :feature:`89` Implemented configuration for distributed task modules: can set 1240 config options in `invoke.collection.Collection` objects and they are made 1241 available to contextualized tasks. 1242- :release:`0.5.1 <2013.09.15>` 1243- :bug:`81` Fall back to sane defaults for PTY sizes when autodetection gives 1244 insane results. Thanks to ``@akitada`` for the patch. 1245- :bug:`83` Fix a bug preventing underscored keyword arguments from working 1246 correctly as CLI flags (e.g. ``mytask --my-arg`` would not map back correctly 1247 to ``mytask(my_arg=...)``.) Credit: ``@akitada``. 1248- :release:`0.5.0 <2013.08.16>` 1249- :feature:`57` Optional-value flags added - e.g. ``--foo`` tells the parser to 1250 set the ``foo`` option value to True; ``--foo myval`` sets the value to 1251 "myval". The built-in ``--help`` option now leverages this feature for 1252 per-task help (e.g. ``--help`` displays global help, ``--help mytask`` 1253 displays help for ``mytask`` only.) 1254- :bug:`55 major` A bug in our vendored copy of ``pexpect`` clashed with a 1255 Python 2->3 change in import behavior to prevent Invoke from running on 1256 Python 3 unless the ``six`` module was installed in one's environment. This 1257 was fixed - our vendored ``pexpect`` now always loads its sibling vendored 1258 ``six`` correctly. 1259