Merge pull request #66 from sgissinger/master

RST update: fixes #57, splitted operator page, added mock operators, other doc refactor

README.rst

@@ -17,7 +17,7 @@ lightweight assertion library for Python_ that aims to make testing more product
 It also comes with a detailed, human-friendly `error reporting`_ system that aims to reduce friction,
 provide better feedback and improve human speed and agility while identifying and fixing errors.
 
-To get started, take a look to the `showcase`_ code, `tutorial`_, available `plugins`_ and `operators documentation`_.
+To get started, take a look to the `showcase`_ code, `getting started`_, available `plugins`_ and operators documentation (`accessors`_, `attributes`_, `matchers`_).
 
 For HTTP protocol assertions, see `grappa-http`_.
 
@@ -33,7 +33,7 @@ Showcase
 --------
 
 A small example demonstrating some `grappa` features.
-See `documentation`_ and `tutorial`_ for more examples.
+See `documentation`_ and `getting started`_ for more examples.
 
 .. code-block:: python
 
@@ -105,26 +105,11 @@ Let's see how the error report looks like in ``grappa`` running in ``pytest``.
 
 See `error reporting`_ documentation for more details about how ``grappa`` error report system works.
 
-.. code-block:: python
+.. code-block:: bash
 
     ======================================================================
     FAIL: tests.should_test.test_grappa_assert
     ======================================================================
-    Traceback (most recent call last):
-    File ".pyenv/versions/3.6.0/lib/python3.6/site-packages/nose/case.py", line 198, in runTest
-    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
       subject "[1, 2, 3]" should be have length of "4"
 
@@ -167,14 +152,6 @@ See `error reporting`_ documentation for more details about how ``grappa`` error
     21|      False | should.be.false | should.be.equal.to(False)
     22|      False | should.be.false | should.not_be.equal.to(True)
 
-Demo
-----
-
-.. image:: https://asciinema.org/a/d6yd2475m41thdku7d3ntkeir.png
-   :width: 900
-   :alt: showcase
-   :align: center
-   :target: https://asciinema.org/a/d6yd2475m41thdku7d3ntkeir?autoplay=1&speed=3&size=small
 
 Why grappa?
 -----------
@@ -206,7 +183,7 @@ Features
 -  Behavior-oriented expressive fluent API.
 -  Built-in assertion DSL with English lexicon and semantics.
 -  Supports both ``expect`` and ``should`` assertion styles.
--  Full-featured built-in `assertion operators`_.
+-  Full-featured built-in `accessors`_, `attributes`_ and `matchers`_ operators.
 -  Human-friendly and detailed `error reporting`_.
 -  Built-in expectations difference comparison between subject and expected values.
 -  Extensible assertions supporting third-party `plugins`_.
@@ -236,12 +213,13 @@ Or install the latest sources from Github:
 
 .. _Python: http://python.org
 .. _`documentation`: http://grappa.readthedocs.io
-.. _`operators documentation`: http://grappa.readthedocs.io/en/latest/operators.html
-.. _`tutorial`: http://grappa.readthedocs.io/en/latest/tutorial.html
+.. _`accessors`: http://grappa.readthedocs.io/en/latest/accessors-operators.html
+.. _`attributes`: http://grappa.readthedocs.io/en/latest/attributes-operators.html
+.. _`matchers`: http://grappa.readthedocs.io/en/latest/matchers-operators.html
+.. _`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/errors.html
+.. _`error reporting`: http://grappa.readthedocs.io/en/latest/error-reporting.html
 .. _`assertion styles`: http://grappa.readthedocs.io/en/latest/style.html
-.. _`assertion operators`: http://grappa.readthedocs.io/en/latest/operators.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

@@ -0,0 +1,138 @@
+Accessors Operators
+===================
+
+These operators do not accept expectation arguments but performs assertion logic.
+
+Example operators: none_, true_, false_, empty_, callable_ ...
+
+
+true
+----
+
+Asserts if a given subject is `True` value.
+
+=======================  ========================
+ **Related operators**   false_
+=======================  ========================
+
+.. code-block:: python
+
+    'foo' | should.be.true
+    'foo' | should.not_be.true
+
+.. code-block:: python
+
+    expect('foo').to.be.true
+    expect('foo').to_not.be.true
+
+
+false
+-----
+
+Asserts if a given subject is `False` value.
+
+=======================  ========================
+ **Related operators**   true_
+=======================  ========================
+
+.. code-block:: python
+
+    'foo' | should.be.false
+    'foo' | should.not_be.false
+
+.. code-block:: python
+
+    expect('foo').to.be.false
+    expect('foo').to_not.be.false
+
+
+callable
+--------
+
+Asserts if a given subject is a callable type or an object that
+implements ``__call__()`` magic method.
+
+=======================  ========================
+ **Related operators**   implements_
+=======================  ========================
+
+.. code-block:: python
+
+    (lambda x: x) | should.be.callable
+    None | should.not_be.callable
+
+.. code-block:: python
+
+    expect(lambda x: x).to.be.callable
+    expect(None).to_not.be.callable
+
+
+empty
+-----
+
+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.be.empty
+    [1, 2, 3] | should.not_be.empty
+
+.. code-block:: python
+
+    expect(tuple()).to.be.empty
+    expect((1, 2, 3)).to_not.be.empty   
+
+
+none
+----
+
+Asserts if a given subject is ``None``.
+
+=======================  ========================
+ **Related operators**   present_ empty_
+=======================  ========================
+
+.. code-block:: python
+
+    None | should.be.none
+    'foo' | should.not_be.none
+
+.. code-block:: python
+
+    expect(None).to.be.none
+    expect('foo').to_not.be.none
+
+
+exists
+------
+present
+-------
+
+Asserts if a given subject is not ``None`` or a negative value
+if evaluated via logical unary operator.
+
+This operator is the opposite of empty_.
+
+=======================  ========================
+ **Related operators**   none_ empty_
+=======================  ========================
+
+.. code-block:: python
+
+    'foo' | should.be.present
+    '' | should.not_be.present
+
+.. code-block:: python
+
+    expect('foo').to.be.present
+    expect(False).to_not.be.present
+
+
+.. _`implements`: http://grappa.readthedocs.io/en/latest/matchers-operators.html#implements

docs/attributes-operators.rst

@@ -0,0 +1,120 @@
+Attributes Operators
+====================
+
+These operators provides assertion/negation logic.
+
+Example operators: to_, be_ not_be_, which_ ...
+
+
+Assertion
+---------
+
+be
+^^
+to
+^^
+has
+^^^
+have
+^^^^
+do
+^^
+include
+^^^^^^^
+satisfy
+^^^^^^^
+satisfies
+^^^^^^^^^
+_is
+^^^
+which
+^^^^^
+that
+^^^^
+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
+=======================  ========================
+
+.. code-block:: python
+
+    '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('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
+--------
+
+not_be
+^^^^^^
+not_present
+^^^^^^^^^^^
+not_to
+^^^^^^
+to_not
+^^^^^^
+does_not
+^^^^^^^^
+do_not
+^^^^^^
+dont
+^^^^
+have_not
+^^^^^^^^
+not_have
+^^^^^^^^
+has_not
+^^^^^^^
+not_has
+^^^^^^^
+that_not
+^^^^^^^^
+which_not
+^^^^^^^^^
+is_not
+^^^^^^
+_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
+=======================  ========================
+
+.. code-block:: python
+
+    'foo' | should.not_be.equal.to('bar')
+    'foo' | should.have_not.length.of(3)
+
+.. code-block:: python
+
+    expect('foo').to_not.equal.to('bar')
+    expect('foo').to.not_have.length.of(3)

docs/composition.rst

@@ -14,9 +14,6 @@ Use ``|`` operator for composing assertions that matches the following condition
 - Assertions that DO tests the same subject.
 - Assertions that uses operators that DOES NOT yield a new test subject.
 
-Example
-^^^^^^^
-
 .. code-block:: python
 
     'foo' | should.have.length.of(3) | should.contain('o')
@@ -33,9 +30,6 @@ Use ``>`` operator for composing assertions that matches the following condition
 - Assertions that DOES NOT test the same subject.
 - Assertions that uses operators that YIELDS a new test subject in the assertion chain.
 
-Example
-^^^^^^^
-
 .. code-block:: python
 
     [1, 2, 3] | should.be.a(list) > should.have.index.at(2) | should.be.equal.to(3)