restore (but deprecate) @taskset.task decorator; updated readme, chan…

…gelog and authors; minor docstring tweaks

AUTHORS.rst

@@ -0,0 +1,5 @@
+Authors
+=======
+
+* Mikhail Korobov <kmike84@gmail.com>;
+* Denis Untevskiy.

CHANGES.rst

@@ -0,0 +1,19 @@
+
+Changes
+=======
+
+0.2 (TBA)
+---------
+
+- ``@task`` decorator is deprecated and replaced with ``@task_method``.
+  This was a bad name because of ``@fabric.task`` decorator
+  (thanks Denis Untevskiy);
+- ``Taskset.expose_as_module`` method that allows to use TaskSet instances
+  from command line without creating dummy modules on disk
+  (thanks Denis Untevskiy).
+
+
+0.1 (2012-03-03)
+----------------
+
+Initial release.

MANIFEST.in

@@ -1,3 +1,4 @@
 include LICENSE
 include README.rst
-include AUTHORS
+include AUTHORS.rst
+include CHANGES.rst

README.rst

@@ -21,37 +21,59 @@ Usage
 
 Example::
 
-    # my_lib/say.py
-    from taskset import TaskSet, task
+
+    # fabfile.py
+    from taskset import TaskSet, task_method
 
     class SayBase(TaskSet):
         def say(self, what):
             raise NotImplemented()
 
-        @task(default=True, alias='hi')
+        @task_method(default=True, alias='hi')
         def hello(self):
             self.say('hello')
 
     class EchoSay(SayBase):
         def say(self, what):
             local('echo ' + what)
 
-    instance = EchoSay()
-    instance.expose_to_current_module()
+    say = EchoSay().expose_as_module('say')
 
-    # fabfile.py
-    from mylib import say
 
 and then e.g.::
 
     $ fab say.hi
     hello
 
 
-``taskset.task`` is a decorator declaring the wrapped method to be task.
+``taskset.task_method`` is a decorator declaring the wrapped method to be task.
 It acceps the same arguments as ``fabric.decorators.task`` so
 use it on methods just like fabric's decorator is used on functions.
 
+You can also create an "on-disk" Python module and populate it with tasks::
+
+    # my_lib/say.py
+    from taskset import TaskSet, task_method
+
+    class SayBase(TaskSet):
+        def say(self, what):
+            raise NotImplemented()
+
+        @task_method(default=True, alias='hi')
+        def hello(self):
+            self.say('hello')
+
+    class EchoSay(SayBase):
+        def say(self, what):
+            local('echo ' + what)
+
+    instance = EchoSay()
+    instance.expose_to_current_module()
+
+    # fabfile.py
+    from mylib import say
+
+
 
 Acknowledgements
 ----------------

setup.py

@@ -19,7 +19,7 @@
     license = 'MIT license',
     description = """ Expose class members as Fabric tasks """,
 
-    long_description = open('README.rst').read(),
+    long_description = open('README.rst').read() + open('CHANGES.rst').read(),
     requires = ['Fabric (>= 1.1)'],
 
     classifiers=(

taskset/__init__.py

@@ -3,6 +3,7 @@
 import inspect
 import sys
 import types
+import warnings
 from fabric.tasks import WrappedCallableTask
 
 def task_method(*args, **kwargs):
@@ -29,6 +30,10 @@ def decorator(func):
 
     return decorator if invoked else decorator(func)
 
+def task(*args, **kwargs):
+    msg = "@taskset.task decorator is deprecated and will be removed soon; please use @taskset.task_method instead."
+    warnings.warn(msg, DeprecationWarning)
+    return task_method(*args, **kwargs)
 
 
 class TaskSet(object):
@@ -88,11 +93,11 @@ def expose_to_current_module(self):
         frm = inspect.stack()[1]
         mod = inspect.getmodule(frm[0])
         return self.expose_to(mod.__name__)
-    
+
     def expose_as_module(self, module_name, module_type=types.ModuleType):
-        """ 
-        Creates new module of type ``module_type`` and named ``module_name`` 
-        populates it with tasks and returns it. 
+        """
+        Creates a new module of type ``module_type`` and named ``module_name``,
+        populates it with tasks and returns this newly created module.
         """
         module = module_type(module_name)
         for name, task in self._get_fabric_tasks():
@@ -104,7 +109,7 @@ def _expose_to(self, module_name):
         for name, task in self._get_fabric_tasks():
             setattr(module_obj, name, task)
             yield name
-    
+
     def _is_task(self, func):
         return hasattr(func, '_task_info')