refactor(api)

pook/api.py

@@ -10,6 +10,8 @@
 def activate(fn=None):
     """
     Enables the HTTP traffic interceptors.
+
+    This function can be used as decorator.
     """
     engine.activate()
 
@@ -30,46 +32,50 @@ def wrapper(*args, **kwargs):
 def on(fn=None):
     """
     Enables the HTTP traffic interceptors.
-    Alias to pock.activate().
+    Alias to pook.activate().
     """
     return activate(fn)
 
 
-def use_network():
+def disable():
     """
-    Enables real networking if no mock can be matched.
+    Disables HTTP traffic interceptors.
     """
-    engine.networking = True
+    engine.disable()
 
 
-def disable_network():
+def off():
     """
-    Disable real networking.
+    Disables HTTP traffic interceptors.
+    Alias to pook.disable().
     """
-    engine.networking = False
+    disable()
 
 
-def disable():
+def use_network():
     """
-    Disables HTTP traffic interceptors.
+    Enables real networking if no mock can be matched.
     """
-    engine.disable()
+    engine.networking = True
 
 
-def off():
+def disable_network():
     """
-    Disables HTTP traffic interceptors.
-    Alias to pock.disable().
+    Disable real networking.
     """
-    disable()
+    engine.networking = False
 
 
 @contextmanager
 def use():
     """
-    Enables the HTTP interceptor for context usage.
-    Example: with pock.use() as engine:
+    Create a new isolated mock engine to be used via context manager.
+
+    Example:
+        >>> with pook.use() as engine:
+        >>>     engine.mock('server.com/foo')
     """
+    engine = Engine()
     engine.activate()
     yield engine
     engine.disable()
@@ -79,60 +85,75 @@ def use():
 def mock(url=None, **kwargs):
     """
     Registers a new mock for GET method.
+
+    Arguments:
+        url (str): request URL to mock.
+
+    Returns:
+        pook.Mock: mock instance
     """
     mock = Mock(url=url, **kwargs)
     engine.add_mock(mock)
     return mock
 
 
-def patch(url=None, method='GET', **kwargs):
+def patch(url=None, **kwargs):
     """
     Registers a new mock.
     Alias to mock()
+
+    Returns:
+        pook.Mock: mock instance
     """
-    mock = Mock(url, method, **kwargs)
-    engine.add_mock(mock)
-    return mock
+    return mock(url, method='PATCH', **kwargs)
 
 
 def get(url):
     """
     Registers a new mock for GET method.
+
+    Returns:
+        pook.Mock: mock instance
     """
     return mock(url)
 
 
 def post(url, **kwargs):
     """
     Registers a new mock for POST method.
+
+    Returns:
+        pook.Mock: mock instance
     """
     return mock(url, method='POST', **kwargs)
 
 
 def put(url, **kwargs):
     """
     Registers a new mock for PUT method.
-    """
-    return mock(url, method='PUT', **kwargs)
 
-
-def patch(url, **kwargs):
-    """
-    Registers a new mock for PATCH method.
+    Returns:
+        pook.Mock: mock instance
     """
-    return mock(url, method='PATCH', **kwargs)
+    return mock(url, method='PUT', **kwargs)
 
 
 def delete(url, **kwargs):
     """
     Registers a new mock for DELETE method.
+
+    Returns:
+        pook.Mock: mock instance
     """
     return mock(url, method='DELETE', **kwargs)
 
 
 def head(url, **kwargs):
     """
     Registers a new mock for HEAD method.
+
+    Returns:
+        pook.Mock: mock instance
     """
     return mock(url, method='HEAD', **kwargs)
 
@@ -141,12 +162,18 @@ def pending():
     """
     Returns the numbers of pending mocks
     to be matched.
+
+    Returns:
+        int: number of pending mocks to reach.
     """
     return 0
 
 
 def is_done():
     """
     Returns True if all the registered mocks has been triggered.
+
+    Returns:
+        bool: True is all the registered mocks are gone, otherwise False.
     """
     return True

pook/decorators.py

@@ -10,22 +10,3 @@ def wrapper(self, *args, **kwargs):
         result = fn(self, *args, **kwargs)
         return self if result is None else result
     return wrapper
-
-
-def expectation(fn):
-    @functools.wraps(fn)
-    def wrapper(self, *args, **kwargs):
-        if not hasattr(self, 'expectations'):
-            self.expectations = {}
-
-        try:
-            return fn(self, *args, **kwargs)
-        finally:
-            name = fn.__name__
-            store = self.expectations.get(name)
-            if not store:
-                store = []
-            store.append(*args)
-            self.expectations[name] = store
-
-    return wrapper

pook/headers.py

@@ -85,12 +85,14 @@ def __iter__(self):
 
     def pop(self, key, default=__marker):
         """
-        D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
-        If key is not found, d is returned if given, otherwise KeyError is raised.
-        """
-        # Using the MutableMapping function directly fails due to the private marker.
-        # Using ordinary dict.pop would expose the internal structures.
-        # So let's reinvent the wheel.
+        D.pop(k[,d]) -> v, remove specified key and return the
+        corresponding value.
+        If key is not found, d is returned if given, otherwise KeyError
+        is raised.
+        """
+        # Using the MutableMapping function directly fails due to the
+        # private marker. Using ordinary dict.pop would expose the
+        # internal structures. So let's reinvent the wheel.
         try:
             value = self[key]
         except KeyError:
@@ -230,7 +232,7 @@ def items(self):
         return list(self.iteritems())
 
     @classmethod
-    def from_httplib(cls, message): # Python 2
+    def from_httplib(cls, message):  # Python 2
         """
         Read headers from a Python 2 httplib message object.
         """