refactor(docs): use reStructuredText. refactor(matchers)

Makefile

@@ -1,26 +1,34 @@
+OK_COLOR=\033[32;01m
+NO_COLOR=\033[0m
+
 all: lint unit
 
 export PYTHONPATH:=${PWD}
-version=`python -c 'import pook;print pook.version'`
-filename=pook-`python -c 'import pook;print pook.version'`.tar.gz
+version=`python -c 'import pook; print(pook.version)'`
+filename=pook-`python -c 'import pook; print(pook.version)'`.tar.gz
 
 lint:
+	@echo "$(OK_COLOR)==> Linting code $(version)$(NO_COLOR)"
 	@flake8 .
 
-test: clean lint
-	@echo "Running tests ..."
+test: clean
+	@echo "$(OK_COLOR)==> Runnings tests...$(NO_COLOR)"
 	# @python -m unittest discover
 	@py.test
 
+tag:
+	@echo "$(OK_COLOR)==> Creating tag $(version)...$(NO_COLOR)"
+	@git tag -a "v$(version)" -m "Version $(version)"
+	@echo "$(OK_COLOR)==> Pushing tag $(version) to origin...$(NO_COLOR)"
+	@git push origin "v$(version)"
+
 clean:
-	@printf "Cleaning up files that are already in .gitignore... "
+	@echo "$(OK_COLOR)==> Cleaning up files that are already in .gitignore...$(NO_COLOR)"
 	@for pattern in `cat .gitignore`; do find . -name "$$pattern" -delete; done
-	@echo "OK!"
 
 release: clean publish
-	@printf "Exporting to $(filename)... "
+	@echo "$(OK_COLOR)==> Exporting to $(filename)...$(NO_COLOR)"
 	@tar czf $(filename) pook setup.py README.md LICENSE
-	@echo "DONE!"
 
 publish:
 	@python setup.py sdist register upload

README.rst

@@ -0,0 +1,115 @@
+pook |Build Status| |PyPI| |Coverage Status| |Documentation Status|
+===================================================================
+
+Simply and expressive utility library for mocking and expectations for
+HTTP traffic in `Python`_.
+
+Small and dependency-free package to infer file type and MIME type
+checking the `magic numbers`_ signature of a file or buffer.
+
+pook is heavily inspired by `gock`_.
+
+**Note**: this is a work in progress.
+
+Features
+--------
+
+-  Simple, expressive and fluent API
+-  Full-featured, idiomatic HTTP expectations.
+-  JSON schema based body matching.
+-  Extensible: write your own HTTP expections.
+-  HTTP client agnostic (works with most popular HTTP libraries).
+-  Pluggable hackable API.
+-  Compatible with Python 2 and 3.
+
+Supported HTTP clients
+----------------------
+
+-  [x] urllib3
+-  [x] requests
+-  [ ] urllib
+-  [ ] aiohttp
+-  [ ] pycurl
+
+Installation
+------------
+
+Using ``pip`` package manager:
+
+.. code:: bash
+
+    pip install pook
+
+Or install the latest sources from Github::
+
+.. code:: bash
+
+    pip install -e git+git://github.com/h2non/pook.git#egg=pook
+
+API
+---
+
+See `annotated API reference`_.
+
+Examples
+--------
+
+Basic mocking
+^^^^^^^^^^^^^
+
+.. code:: python
+
+    import pook
+    import requests
+
+    @pook.activate
+    def test_my_api():
+        mock = httpok.get('http://twitter.com/api/1/foobar',
+                        type='application/json',
+                        json={'error': 'not found'})
+        mock.reply(404, json={'error': 'foo'})
+
+        resp = requests.get('http://twitter.com/api/1/foobar')
+        assert resp.json() == {"error": "not found"}
+        assert len(mock.calls) == 1
+        assert mock.calls[0].request.url == 'http://twitter.com/api/1/foobar'
+        assert mock.calls[0].response.text == '{"error": "not found"}'
+
+Using the fluent API
+^^^^^^^^^^^^^^^^^^^^
+
+.. code:: python
+
+    import pook
+    import requests
+
+    @pook.activate
+    def test_my_api():
+        mock = pook.get('http://twitter.com/api/1/foobar'). \
+               status(404). \
+               json({'error': 'not found'})
+
+        resp = requests.get('http://twitter.com/api/1/foobar')
+        assert resp.json() == {"error": "not found"}
+        assert len(mock.calls) == 1
+        assert mock.calls[0].request.url == 'http://twitter.com/api/1/foobar'
+        assert mock.calls[0].response.text == '{"error": "not found"}'
+
+License
+-------
+
+MIT - Tomas Aparicio
+
+.. _Python: http://python.org
+.. _magic numbers: https://en.wikipedia.org/wiki/Magic_number_(programming)#Magic_numbers_in_files
+.. _gock: https://github.com/h2non/gock
+.. _annotated API reference: https://h2non.github.io/pook
+
+.. |Build Status| image:: https://travis-ci.org/h2non/pook.svg?branch=master
+   :target: https://travis-ci.org/h2non/pook
+.. |PyPI| image:: https://img.shields.io/pypi/v/pook.svg?maxAge=2592000?style=flat-square
+   :target: https://pypi.python.org/pypi/pook
+.. |Coverage Status| image:: https://coveralls.io/repos/github/h2non/pook/badge.svg?branch=master
+   :target: https://coveralls.io/github/h2non/pook?branch=master
+.. |Documentation Status| image:: https://readthedocs.org/projects/pook/badge/?version=latest
+   :target: http://pook.readthedocs.io/en/latest/?badge=latest

pook/__init__.py

@@ -2,4 +2,6 @@
 
 __author__ = 'Tomas Aparicio'
 __license__ = 'MIT'
-__version__ = '0.1.0'
+
+# Current package version
+__version__ = version = '0.1.0'

pook/interceptors/urllib3.py

@@ -11,12 +11,12 @@
 
 if sys.version_info < (3,):     # Python 2
     from httplib import responses as http_reasons
-    from cStringIO import StringIO as BytesIO
-    from urlparse import urlparse
+    # from cStringIO import StringIO as BytesIO
+    # from urlparse import urlparse
 else:                           # Python 3
     from http.client import responses as http_reasons
-    from io import BytesIO
-    from urllib.parse import urlparse
+    # from io import BytesIO
+    # from urllib.parse import urlparse
 
 PATCHES = (
     'requests.packages.urllib3.connectionpool.HTTPConnectionPool.urlopen',

pook/matchers/__init__.py

@@ -4,8 +4,17 @@
 from .query import QueryMatcher
 from .body import BodyMatcher
 
+__all__ = [
+    'matchers',
+    'MethodMatcher',
+    'URLMatcher',
+    'HeadersMatcher',
+    'QueryMatcher',
+    'BodyMatcher'
+]
+
 # Expose built-in matchers
-store = [
+matchers = [
     MethodMatcher,
     URLMatcher,
     HeadersMatcher,

pook/matchers/base.py

@@ -0,0 +1,27 @@
+from copy import deepcopy
+
+
+class BaseMatcher(object):
+    def __init__(self, expectation):
+        self.expectation = expectation
+
+    def match(self):
+        raise NotImplemented('not implemented yet')
+
+    @property
+    def name(self):
+        return self.__class__.__name__
+
+    @property
+    def expectation(self):
+        return self._expectation if hasattr(self, '_expectation') else None
+
+    @expectation.setter
+    def expectation(self, value):
+        self._expectation = value
+
+    def to_dict(self):
+        return {self.name: deepcopy(self.expectation)}
+
+    def __repr__(self):
+        return '{}({})'.format(self.name, self.expectation)