fixes #52, #68, updated doc

README.rst

@@ -37,68 +37,73 @@ See `documentation`_ and `getting started`_ for more examples.
 
 .. code-block:: python
 
-    from grappa import should
+      # should style
+      from grappa import should
 
-    True | should.be.true
-    False | should.be.false
-    None | should.be.none
+      True | should.be.true
+      False | should.be.false
+      None | should.be.none
 
-    '' | should.be.empty
-    [] | should.be.empty
-    'foo' | should.exists
+      3.14 | should.be.lower.than(4)
+      3.14 | should.be.higher.than(3)
+      3.14 | should.be.within(2, 4)
 
-    3.14 | should.be.lower.than(4)
-    3.14 | should.be.higher.than(3)
-    3.14 | should.be.within(2, 4)
+      'hello, grappa' | should.starts_with('hello')
+      'hello, grappa' | should.ends_with('grappa')
+      [1, 2, 3, 4] | should.starts_with(1)
+      [1, 2, 3, 4] | should.ends_with(4)
 
-    'bar' | should.be.equal.to('bar', msg='value is not "bar"')
-    [1, 2, 3] | should.be.equal.to([1, 2, 3])
+      'Hello grappa' | should.match('(\W)+ grappa$')
+      'Hello grappa' | should.contain('grappa') | should.contain('he')
+      ['foo', 'bar'] | should.contain('foo') | should.do_not.contain('baz')
 
-    'hello, grappa' | should.startswith('hello')
-    'hello, grappa' | should.endswith('grappa')
-    [1, 2, 3, 4] | should.startswith(1)
-    [1, 2, 3, 4] | should.endswith(4)
+      'foo' | should.pass_test(lambda x: x in 'foo bar')
+      'foo' | should.pass_function(lambda x: len(x) > 2)
 
-    'Hello grappa' | should.match('(\W)+ grappa$')
-    'Hello grappa' | should.contain('grappa') | should.contain('he')
-    ['foo', 'bar'] | should.contain('foo') | should.do_not.contain('baz')
+      {'foo': 'bar'} | should.have.key('foo').that.should.be.equal('bar')
+      (1, 2, 3, 4) | should.be.a(tuple) > should.have.index.at(3) > should.be.equal.to(4)
 
-    'foo' | should.be.a('string')
-    {'foo': True} | should.be.a('dict')
+      {'foo': True, 'bar': False} | should.all(should.have.key('foo'), should.have.key('bar'))
+      {'foo': True, 'bar': False} | should.any(should.have.key('foo'), should.have.key('baz'))
 
-    iter([1, 2, 3]) | should.have.length.of(3)
-    [1, 2, 3] | should.be.a('list') > should.have.length.of(3)
+      ({'bar': [1, 2, 3]}
+         | should.have.key('bar')
+         > should.be.a('list')
+         > should.have.length.of(3)
+         > should.contain.item(3)
+         > should.have.index.at(1)
+         > should.be.equal.to(2))
 
-    (lambda x: x) | should.be.callable
-    (lambda x: x) | should.not_have.type.of('generator')
 
-    'foo' | should.pass_test(lambda x: x in 'foo bar')
-    'foo' | should.pass_function(lambda x: len(x) > 2)
+      # expect style
+      from grappa import expect
 
-    (lambda: x) | should.raises(NameError)
-    (lambda: x) | should.does_not.raises(RuntimeError)
+      expect('').to.be.empty
+      expect([]).to.be.empty
+      expect('foo').to.exists
 
-    {'foo': 'bar'} | should.have.key('foo').that.should.be.equal('bar')
-    (1, 2, 3, 4) | should.be.a(tuple) > should.have.index.at(3) > should.be.equal.to(4)
+      expect('bar').to.be.equal.to('bar', msg='value is not "bar"')
+      expect([1, 2, 3]).to.equal([1, 2, 3])
 
-    an_object | should.have.properties('foo', 'bar', 'baz')
-    an_object | should.implement.methods('foo', 'bar', 'baz')
+      expect('foo').to.be.a('string')
+      expect({'foo': True}).to.be.a('dict')
 
-    {'foo': True, 'bar': False} | should.all(should.have.key('foo'), should.have.key('bar'))
-    {'foo': True, 'bar': False} | should.any(should.have.key('foo'), should.have.key('baz'))
+      expect(iter([1, 2, 3])).to.have.length.of(3)
+      expect([1, 2, 3]).to.be.a('list') > should.have.length.of(3)
 
-    ({'bar': [1, 2, 3]}
-        | should.have.key('bar')
-        > should.be.a('list')
-        > should.have.length.of(3)
-        > should.contain.item(3)
-        > should.have.index.at(1)
-        > should.be.equal.to(2))
+      expect(lambda x: x).to.be.callable
+      expect(lambda x: x).to.not_have.type.of('generator')
 
-    with should('foo'):
-        should.be.a(str)
-        should.have.length.of(3)
-        should.be.equal.to('foo')
+      expect(lambda: x).to.raise_error(NameError) > expect.to.be('Invalid argument')
+      ecpect(lambda: x).to_not.raise_error(RuntimeError)
+
+      expect(an_object).to.have.properties(('foo', 'bar', 'baz'))
+      expect(an_object).to.implement.methods(['foo', 'bar', 'baz'])
+
+      with expect('foo'):
+         to.be.a(str)
+         to.have.length.of(3)
+         to.be.equal.to('foo')
 
 
 Let's see how the error report looks like in ``grappa`` running in ``pytest``.
@@ -110,7 +115,9 @@ See `error reporting`_ documentation for more details about how ``grappa`` error
     ======================================================================
     FAIL: tests.should_test.test_grappa_assert
     ======================================================================
-    The following assertion was not satisfied
+    File "grappa/tests/should_test.py", line 16, in test_grappa_assert
+    x | should.be.have.length.of(4)
+    AssertionError: The following assertion was not satisfied
       subject "[1, 2, 3]" should be have length of "4"
 
     Message
@@ -219,7 +226,7 @@ Or install the latest sources from Github:
 .. _`getting started`: http://grappa.readthedocs.io/en/latest/getting-started.html
 .. _`plugins`: http://grappa.readthedocs.io/en/latest/plugins.html
 .. _`error reporting`: http://grappa.readthedocs.io/en/latest/error-reporting.html
-.. _`assertion styles`: http://grappa.readthedocs.io/en/latest/style.html
+.. _`assertion styles`: http://grappa.readthedocs.io/en/latest/assertions-styles.html
 .. _`grappa-http`: https://github.com/grappa-py/http
 
 .. |Build Status| image:: https://travis-ci.org/grappa-py/grappa.svg?branch=master

docs/accessors-operators.rst

@@ -1,47 +1,37 @@
-Accessors Operators
+Accessors operators
 ===================
 
-These operators do not accept expectation arguments but performs assertion logic.
-
-Example operators: none_, true_, false_, empty_, callable_ ...
+These operators perform simple assertion logic.
 
 
 true
 ----
 
-Asserts if a given subject is `True` value.
-
-=======================  ========================
- **Related operators**   false_
-=======================  ========================
+Asserts if a given subject is ``True`` value.
 
 .. code-block:: python
 
+    # should style
     'foo' | should.be.true
     'foo' | should.not_be.true
 
-.. code-block:: python
-
+    # expect style
     expect('foo').to.be.true
     expect('foo').to_not.be.true
 
 
 false
 -----
 
-Asserts if a given subject is `False` value.
-
-=======================  ========================
- **Related operators**   true_
-=======================  ========================
+Asserts if a given subject is ``False`` value.
 
 .. code-block:: python
 
+    # should style
     'foo' | should.be.false
     'foo' | should.not_be.false
 
-.. code-block:: python
-
+    # expect style
     expect('foo').to.be.false
     expect('foo').to_not.be.false
 
@@ -52,17 +42,13 @@ callable
 Asserts if a given subject is a callable type or an object that
 implements ``__call__()`` magic method.
 
-=======================  ========================
- **Related operators**   implements_
-=======================  ========================
-
 .. code-block:: python
 
+    # should style
     (lambda x: x) | should.be.callable
     None | should.not_be.callable
 
-.. code-block:: python
-
+    # expect style
     expect(lambda x: x).to.be.callable
     expect(None).to_not.be.callable
 
@@ -75,17 +61,13 @@ Asserts if a given subject is an empty object.
 A subject is considered empty if it's ``None``, ``0`` or ``len(subject)``
 is equals to ``0``.
 
-=======================  ========================
- **Related operators**   present_ none_
-=======================  ========================
-
 .. code-block:: python
 
+    # should style
     [] | should.be.empty
     [1, 2, 3] | should.not_be.empty
 
-.. code-block:: python
-
+    # expect style
     expect(tuple()).to.be.empty
     expect((1, 2, 3)).to_not.be.empty   
 
@@ -95,17 +77,13 @@ none
 
 Asserts if a given subject is ``None``.
 
-=======================  ========================
- **Related operators**   present_ empty_
-=======================  ========================
-
 .. code-block:: python
 
+    # should style
     None | should.be.none
     'foo' | should.not_be.none
 
-.. code-block:: python
-
+    # expect style
     expect(None).to.be.none
     expect('foo').to_not.be.none
 
@@ -120,19 +98,12 @@ if evaluated via logical unary operator.
 
 This operator is the opposite of empty_.
 
-=======================  ========================
- **Related operators**   none_ empty_
-=======================  ========================
-
 .. code-block:: python
 
+    # should style
     'foo' | should.be.present
     '' | should.not_be.present
 
-.. code-block:: python
-
+    # expect style
     expect('foo').to.be.present
     expect(False).to_not.be.present
-
-
-.. _`implements`: http://grappa.readthedocs.io/en/latest/matchers-operators.html#implements

docs/style.rst → docs/assertions-styles.rst

@@ -1,4 +1,4 @@
-Assertion Styles
+Assertion styles
 ================
 
 ``grappa`` is a behavior-oriented library that comes in two flavors: ``expect`` and ``should``.

docs/attributes-operators.rst

@@ -1,13 +1,13 @@
-Attributes Operators
+Attributes operators
 ====================
 
-These operators provides assertion/negation logic.
+These operators provide positive and negative assertion logic.
 
-Example operators: to_, be_ not_be_, which_ ...
+They semantically describe assertions to make them more expressive.
 
 
-Assertion
----------
+Positive
+--------
 
 be
 ^^
@@ -36,34 +36,26 @@ that_is
 which_is
 ^^^^^^^^
 
-Semantic chainable attributes that defines non-negative assertions.
-
-Typically, you will use them implicitly in order to semantically describe your assertions.
-
-=======================  ========================
- **Assertion mode**      positive
------------------------  ------------------------
- **Resets context**      no
-=======================  ========================
+Chainable semantic attributes which define positive assertions.
 
 .. code-block:: python
 
+    # should style
     'foo' | should.be.equal.to('bar')
     'foo' | should.have.length.of(3)
 
     {'foo': 'bar'} | should.have.key('foo').which.should.be.equal.to('bar')
     {'foo': 'bar'} | should.have.key('foo').that.should.have.length.of(3)
 
-.. code-block:: python
-
+    # expect style
     expect('foo').to.equal.to('bar')
     expect('foo').to.have.length.of(3)
 
     expect({'foo': 'bar'}).to.have.key('foo').which.expect.to.be.equal('bar')
     expect({'foo': 'bar'}).to.have.key('foo').which.expect.to.have.length.of(3)
 
 
-Negation
+Negative
 --------
 
 not_be
@@ -99,22 +91,14 @@ _not
 not_satisfy
 ^^^^^^^^^^^
 
-Semantic chainable attributes that defines negative assertions.
-
-Typically, you will use them implicitly in order to semantically describe your assertions.
-
-=======================  ========================
- **Assertion mode**      negation
------------------------  ------------------------
- **Resets context**      no
-=======================  ========================
+Chainable semantic attributes which define negative assertions.
 
 .. code-block:: python
 
+    # should style
     'foo' | should.not_be.equal.to('bar')
     'foo' | should.have_not.length.of(3)
 
-.. code-block:: python
-
+    # expect style
     expect('foo').to_not.equal.to('bar')
     expect('foo').to.not_have.length.of(3)

docs/error-reporting.rst

@@ -1,4 +1,4 @@
-Error Reporting
+Error reporting
 ===============
 
 Feedback while testing is key. Seeing errors in your tests is not a nice thing
@@ -59,17 +59,7 @@ Now, a ``grappa`` error report using ``nosetests``:
     self.test(*self.arg)
     File "grappa/tests/should_test.py", line 16, in test_grappa_assert
     x | should.be.have.length.of(4)
-    File "grappa/grappa/test.py", line 248, in __ror__
-    return self.__overload__(value)
-    File "grappa/grappa/test.py", line 236, in __overload__
-    return self.__call__(subject, overload=True)
-    File "grappa/grappa/test.py", line 108, in __call__
-    return self._trigger() if overload else Test(subject)
-    File "grappa/grappa/test.py", line 153, in _trigger
-    raise err
-    AssertionError: Oops! Something went wrong!
-
-    The following assertion was not satisfied
+    AssertionError: The following assertion was not satisfied
     subject "[1, 2, 3]" should be have length of "4"
 
     Reasons