Documenting transformations and configurables.

bonobo/config/options.py

@@ -1,8 +1,51 @@
 class Option:
     """
-    An Option is a descriptor for a required or optional parameter of a Configurable.
-    
+    An Option is a descriptor for Configurable's parameters.
+
+    .. attribute:: type
+
+        Option type allows to provide a callable used to cast, clean or validate the option value. If not provided, or
+        None, the option's value will be the exact value user provided.
+
+        (default: None)
+
+    .. attribute:: required
+
+        If an option is required, an error will be raised if no value is provided (at runtime). If it is not, option
+        will have the default value if user does not override it at runtime.
+
+        (default: False)
+
+    .. attribute:: positional
+
+        If this is true, it'll be possible to provide the option value as a positional argument. Otherwise, it must
+        be provided as a keyword argument.
+
+        (default: False)
+
+    .. attribute:: default
+
+        Default value for non-required options.
+
+        (default: None)
+
+    Example:
+
+        .. code-block:: python
+
+            from bonobo.config import Configurable, Option
+
+            class Example(Configurable):
+                title = Option(str, required=True, positional=True)
+                keyword = Option(str, default='foo')
+
+                def call(self, s):
+                    return self.title + ': ' + s + ' (' + self.keyword + ')'
+
+            example = Example('hello', keyword='bar')
+
     """
+
     _creation_counter = 0
 
     def __init__(self, type=None, *, required=False, positional=False, default=None):
@@ -32,6 +75,36 @@ class Option:
 
 
 class Method(Option):
+    """
+    A Method is a special callable-valued option, that can be used in three different ways (but for same purpose).
+
+    * Like a normal option, the value can be provided to the Configurable constructor.
+
+        >>> from bonobo.config import Configurable, Method
+
+        >>> class MethodExample(Configurable):
+        ...     handler = Method()
+
+        >>> example1 = MethodExample(handler=str.upper)
+
+    * It can be used by a child class that overrides the Method with a normal method.
+
+        >>> class ChildMethodExample(MethodExample):
+        ...     def handler(self, s: str):
+        ...         return s.upper()
+
+        >>> example2 = ChildMethodExample()
+
+    * Finally, it also enables the class to be used as a decorator, to generate a subclass providing the Method a value.
+
+        >>> @MethodExample
+        ... def OtherChildMethodExample(s):
+        ...     return s.upper()
+
+        >>> example3 = OtherChildMethodExample()
+
+    """
+
     def __init__(self):
         super().__init__(None, required=False, positional=True)
 

bonobo/config/services.py

@@ -39,6 +39,10 @@ class Service(Option):
             
     The main goal is not to tie transformations to actual dependencies, so the same can be run in different contexts
     (stages like preprod, prod, or tenants like client1, client2, or anything you want).
+
+    .. attribute:: name
+
+        Service name will be used to retrieve the implementation at runtime.
     
     """
 

bonobo/ext/console.py

@@ -1,41 +1,13 @@
-# -*- coding: utf-8 -*-
-#
-# Copyright 2012-2017 Romain Dorgueil
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
 import functools
 import sys
 
-from colorama import Fore, Style
+from colorama import Style, Fore
 
 from bonobo import settings
 from bonobo.plugins import Plugin
 from bonobo.util.term import CLEAR_EOL, MOVE_CURSOR_UP
 
 
-@functools.lru_cache(1)
-def memory_usage():
-    import os, psutil
-    process = psutil.Process(os.getpid())
-    return process.memory_info()[0] / float(2**20)
-
-
-# @lru_cache(64)
-# def execution_time(harness):
-#    return datetime.datetime.now() - harness._started_at
-
-
 class ConsoleOutputPlugin(Plugin):
     """
     Outputs status information to the connected stdout. Can be a TTY, with or without support for colors/cursor
@@ -107,3 +79,10 @@ class ConsoleOutputPlugin(Plugin):
         if rewind:
             print(CLEAR_EOL)
             print(MOVE_CURSOR_UP(t_cnt + 2))
+
+
+@functools.lru_cache(1)
+def memory_usage():
+    import os, psutil
+    process = psutil.Process(os.getpid())
+    return process.memory_info()[0] / float(2**20)

bonobo/ext/console/__init__.py

@@ -1,5 +0,0 @@
-from .plugin import ConsoleOutputPlugin
-
-__all__ = [
-    'ConsoleOutputPlugin',
-]

bonobo/ext/opendatasoft.py

@@ -5,7 +5,6 @@ import requests  # todo: make this a service so we can substitute it ?
 from bonobo.config import Option
 from bonobo.config.processors import ContextProcessor
 from bonobo.config.configurables import Configurable
-from bonobo.util.compat import deprecated
 from bonobo.util.objects import ValueHolder