Consider making contextualization the default

[bitprophet]

Occasionally catch myself doing the following:

from invoke import Collection, task

# stuff

@task
def foo(ctx, blah, otherblah):
    ctx.run("whatever")

ns = Collection(foo)

Which leads to a nice 'test' did not receive all required positional arguments! error, because task != ctask. Also I think part of an FAQ mentions this (!)

If it's something I do myself cuz I haven't written a new Invoke task in a month...it's gonna bite users. The un-contextualized use case is and should be the minority; therefore I really should:

• Update docs to describe a "contextualized by default" setup, including removing mention of @ctask.
  • Maybe be hardcore and just don't even bother with uncontextualized tasks? Eh. Leaving the flag in allows people to rebind the name to an inverted-ctask if they really care about not using the context.
• Update tests to match
• Add new tests enforcing a useful "Did you forget a leading context argument?" add-on to the above error message, probably.
• Implement.
• Update all my stuff (whee! Good thing most of it is in Invocations...)
• Add big honkin' backwards incompatibility note to teh changelog (maybe a good new Releases feature?)

[bitprophet]

Actually thinking this pairs well with #147 because I'm having a heck of a time figuring out how to recast the contexts doc page in light of it not being the main config vector now. Part of this problem is because the entire doc is structured as a "here's why you want to use contexts" and if it's going to need a restructure anyway this might be a good time.

OTOH I've already spent so long on #147...heh.

EDIT: Gonna punt on that for now but this is still something I ought to do soonish :)

[KuangEleven]

Working on removing non-contextualized tasks

[thebjorn]

Perhaps a stupid question...? but if all tasks need a first argument of a specific type, and it's a source of error that users forget this argument.. Wouldn't it be sensible to define a task as a subclass of Task, since then the first argument would be self which when missing is much more likely to be picked up by linters/IDEs? I know you can define a class as a task already (e.g. https://github.com/datakortet/dk-tasklib/blob/master/dktasklib/lessc.py) and even though it works well it feels a little hacky..

[bitprophet]

@thebjorn Not a stupid question! It's true that making them class definitions would make that line up a bit better. The problem is, this type of tool wants to be as DSL-like & lightweight as possible, so any additional boilerplate drives it farther from that goal.

The use of a context object is already a moderate boilerplate addition (one I judged worthwhile because of the large gains in explicitness, architectural sanity & debug friendliness). Adding class-def lines & extra indent levels strikes me as not quite worth the tradeoff.

Relatedly, though - I realized the other day that our problem is literally the same problem as method self args - including the fact that you get a newbie-unfriendly error if you forget self. Updating the docs to highlight this fact - hoping that users are already used to writing classes and having that mental model - might be useful.

Finally, having methods-as-tasks is something we want to have as an optional feature - see #347. I just don't think that should be the default mode.

[bitprophet]

Props to @KuangEleven , this is in now. Bring on the flames! 😒