Add namespaces to task decorators

Start in tasks.py and inspect the @task decorator and invoke.Collection entry points. Compare the proposed namespace forms and default root-collection behavior, then verify that nested namespaces and unqualified tasks behave as described in the examples.

The current mechanism to create namespaces is a lot of work. I've hacked together an example tasks decorator dynamically creates namespaces as needed.

@task('ns1.ns2.ns3') # or @task(collection='ns1.ns2.ns3') or @task(namespace=...)
def do_something(c):
    pass

I'm also of the opinion that anything marked with @task in tasks.py should be added to the root collection by default.

Here's a working example. I'd be more that happy to contribute this as a feature.

import invoke
from collections import deque
namespace = invoke.Collection()

def resolve_collection(namespace_str):
    """
    Returns an existing subcollection for a path (e.g. 'a.b.c') or creates them
    and returns the "leaf" subcollection.
    """
    collection_names = deque(namespace_str.split('.'))
    curr = namespace
    while True:
        collection_name = collection_names.popleft()
        try:
            subcollection = curr.subcollection_from_path(collection_name)
        except KeyError:
            subcollection = None
        # if theres not a matching subcollection add it
        if not subcollection:
            subcollection = invoke.Collection(collection_name)
            curr.add_collection(subcollection)
        curr = subcollection 

        if not collection_names:
            return subcollection

def task(collection = namespace, **kwargs):
    """invoke.task wrapped with some extra goodies"""
    def wrapper(task_fn):
        if isinstance(collection, invoke.Collection):
            collection.add_task(invoke.task(task_fn, **kwargs))

        if isinstance(collection, str):
            resolve_collection(collection).add_task(invoke.task(task_fn, **kwargs))
    return wrapper

#
# Usage
#

@task()
def this_task_will_be_in_the_default_namespace(c):
    pass

@task(collection='docs')
def this_task_will_be_in_docs(c):
    pass