Easier 'self-importing' / building hybrid namespaces

[bitprophet]

Use case

One's local tasks.py marries some imported task modules (e.g. from Invocations) and some custom local-to-project tasks. It has to be done like this right now:

from invocations import docs, test
from invoke import task, Collection

@task
def mylocaltask():
    pass

ns = Collection(docs, test, mylocaltask)

This isn't awful on the face of it, but it means that one has to remember to edit that ns line every time one changes the contents of the local module. This is extremely error-prone (I say this via experience...) and thus frustrating.

Solutions

Make it easier to add "self" to a Collection so one may state something like:

ns = Collection(docs, test, __self__)

Or more realistically:

# Inspects dict contents for values which are Tasks, similar to Collection.from_module
ns = Collection.from_dict(locals())
ns.add_collection(docs)
ns.add_collection(test)

Alternately/additionally:

• Helper that automatically calls locals() (or globals()?) and does abovementioned scraping of Task values. Again, same logic as from_module just w/ a dict instead of a module object.
• Extend from_dict, from_collection and/or some new classmethod (from_here?) so they can take additional args like __init__ does.
  • I.e. don't make me run one new add_collection line for every imported module, let me do something like Collection.from_dict(locals(), docs, test).
  • Or add add_collections that takes >1 arg...
  • Alternately, let __init__ be told to call e.g. from_dict on dict input, just like how it handles modules, collections & tasks already. E.g. ns = Collection(locals(), docs, test).
  • Though here we'd want it to be "based on" locals() - we don't want locals() to end up in another sub-namespace. It needs to be the root namespace.
  • Emphasis should be on __init__ always just being sugar for calling other public methods by hand.
• In this scenario, locals() and/or globals() may include the imported sub-modules from Invocations. Make sure any syntactic sugar implementation does the least surprising thing here, and that working around it / avoiding using it is not a big slog.

---

Related to #59.

[bitprophet]

Another option besides using locals() + a dict constructor, would be simply reusing the module constructor with sys.modules[__name__]. Probably nice.

---

Still have to solve the actual API for this for a few cases:

• "Just give me everything in this file - all imported modules, all local tasks, as if I was manually throwing them into Collection.__init__() - with no additional tweaks or rebindings"
  • e.g. ns = Collection.from_here()
• "Let me reference 'all the tasks in this file' easily, but otherwise let me decide exactly how to construct a Collection from it + imports"
  • Originally thought ns = Collection(here(), imported_module_as_is, differentname=another_imported_module) but that falls afoul of the previously-noted "pulls local tasks in as a subcollection, instead of using it as the root itself"
  • ns = Collection.from_here(imported_module_as_is, differentname=another_imported_module) is confusing/ugly
  • Using a kwarg might work: ns = Collection(root=here(), imported_module_as_is, differentname=another_imported_module) (or base= instead of root=)
  • but sorta clashes with the general "kwargs as binding"
  • and actually that example is illegal as it goes kwarg, posarg, kwarg; and doing Collection( imported_module_as_is, differentname=another_imported_module, root=here()) doesn't read/write very well because the fact that it's rooted in the local module is obscured
  • Maybe just half-and-half it by saying "initialize + add" but put in a .add_collections() plural-adder which acts just like __init__, so: ns = Collection.from_here() ns.add_collections(imported_module_as_is, differentname=another_imported_module)
  • Or go the "chain" route if we're desperate, using instancemethods: ns = Collection.from_here().with(imported_module_as_is, differentname=another_imported_module) but I'm not a big fan of that, really.