Namespacing

[bitprophet]

General needs (should tie into Collection):

• Organize tasks in a logical namespace tree instead of a flat namespace
  • Emphasis on logical - while module level scanning for Tasks should be an option it should not be the primary interface.
• Refer to them with dot syntax (foo.bar) both on CLI and in e.g. pre/post
• Aliasing (having a task or even a subtree show up in >1 location in the tree)
  • Including at the same level, of course
• Moving/renaming (like aliasing, but masking out the "original" location)
  • Hopefully not required anymore with an explicit API, like it would have been with Fab 1 style implicit-module stuff?
  • I.e. users who need this can simply alter the calls building the tree.
• Flexible display in --list
  • I.e. invoke --list --root foo.bar to display only the subtree beginning with foo.bar
  • Again, maybe not required if we can give users enough control, e.g. when the use case is to give non-admin users a different view, could define a real top level list task that does e.g. show_tasks('user') or whatever?

[bitprophet]

Have much of this working now.

At one point, considered having the from_module classmethod suck in Collection members of a module, but realized that the only really useful point of this is to ape the existing "recursively chew my imported modules" behavior, except with more boilerplate, and not actually removing any of the problems we have now with the implicit module tree crawl.

So I think it really makes the most sense to have convention be that you construct the namespace collection "in" one location, you import all the modules you need for your namespace, and explicitly from_module them into your root Collection.

We might want to add a convenience method/kwarg to say "no I do want Fab 1 style import crawling behavior" (in which case we may as well just implement it Fab 1 style, no module-level Collection stuff) but I think it's best to leave it out for now and see if anybody complains. The inverse -- folks getting used to that being "the" way to do it, then running into all the issues we have now with Fab -- feels worse. Maybe.

Guess this is ye olde "make them go the explicit route off the bat because they'll need it eventually" random-script-files-vs-Web-frameworks argument really.

Also, the "I want something quick n easy" base case does still exist in the form of an unadulterated, no-collections-in-it tasks.py, so it's not like true beginners have to write any explicit boilerplate besides @task.

---

tl;dr remove any docs/tests mentioning that Collection.from_module loads Collection instances, and power on.

[bitprophet]

Almost done now!

Realized that a module within a package has its full dotted path as __name__, e.g. invocations.docs, even when imported as from invocations import docs, is still __name__'d invocations.docs.

• So we need to do something like grab the last dotted section, or say "you should always explicitly name any from_module results" (possibly by allowing the name to be given in from_module).
  • I can't think of any serious downsides of the former approach, though, and it's much easier for all involved.
  • Cleanest might be to strip out module.__package__? Or would that still leave us with dots for sub-sub-modules? EDIT: hm sub-sub-modules don't even have anything in __package__ so scratch that.

[bitprophet]

Still almost there, things work at the Collection level and for --list, but parsing is still somehow messing up such that namespaced tasks raise parse errors, poking/testing now.

[bitprophet]

Fixed, yay testing.

Only thing left (yes, there was another one. God bless dogfooding. Best testing ever.) is making default tasks show up in both --list and parse contexts.

[bitprophet]

That one is actually not 100% obvious, I posted this gist to ask a few other folks their opinion, got some good answers already.

[bitprophet]

As of this comment on that gist (plus the followup) pretty sure I'm going to go with "don't show aliases/defaults as their own line, just parenthesized next to the 'real' item".

[bitprophet]

Got hilariously sidetracked as I found out the aliases feature was in fact entirely broken; boo on implementing only the lower levels of an API "in prep" for the full end-to-end.

Cannot for the life of me remember why I had Collection.add_task accepting task alias and is-default values instead of deferring to the Task itself, unless it was so one could "rebind" a task under different aliases/default-ness (like we can with name). Seems pointless to me for now and meant that things were quite broken, so fixed all of that up and removed some tests in the process.

Hopefully back to even keel soon.

[bitprophet]

oh god it works!