Skip to content

Commit

Permalink
Fixed up the docs ReST formatting to bring it into shape for the next…
Browse files Browse the repository at this point in the history 
… release
  • Loading branch information
@offbyone
offbyone committed Jul 7, 2013
1 parent 50929c1 commit fd4ef99
Show file tree
Hide file tree
Showing 3 changed files with 92 additions and 96 deletions.
174 changes: 89 additions & 85 deletions README.md → README.rst
View file
@@ -1,7 +1,15 @@
![PyHamcrest](http://hamcrest.org/images/logo.jpg)
PyHamcrest
==========

[![Release Status](https://pypip.in/P/PyHamcrest/badge.png)](https://crate.io/packages/PyHamcrest)
[![Build Status](https://travis-ci.org/hamcrest/PyHamcrest.png?branch=master)](https://travis-ci.org/hamcrest/PyHamcrest)
.. image:: http://hamcrest.org/images/logo.jpg
:alt: PyHamcrest

.. image:: https://pypip.in/v/PyHamcrest/badge.png
:alt: Release Status
:target: https://crate.io/packages/PyHamcrest
.. image:: https://travis-ci.org/hamcrest/PyHamcrest.png?branch=master
:alt: Build Status
:target: https://travis-ci.org/hamcrest/PyHamcrest

Introduction
============
Expand Down Expand Up @@ -34,21 +42,21 @@ My first PyHamcrest test

We'll start by writing a very simple PyUnit test, but instead of using PyUnit's
``assertEqual`` method, we'll use PyHamcrest's ``assert_that`` construct and
the standard set of matchers::
the standard set of matchers:

.. code:: python
```python
from hamcrest import *
import unittest
from hamcrest import *
import unittest
class BiscuitTest(unittest.TestCase):
def testEquals(self):
theBiscuit = Biscuit('Ginger')
myBiscuit = Biscuit('Ginger')
assert_that(theBiscuit, equal_to(myBiscuit))
class BiscuitTest(unittest.TestCase):
def testEquals(self):
theBiscuit = Biscuit('Ginger')
myBiscuit = Biscuit('Ginger')
assert_that(theBiscuit, equal_to(myBiscuit))
if __name__ == '__main__':
unittest.main()
```
if __name__ == '__main__':
unittest.main()
The ``assert_that`` function is a stylized sentence for making a test
assertion. In this example, the subject of the assertion is the object
Expand All @@ -58,18 +66,18 @@ object is equal to another using the Python ``==`` operator. The test passes
since the ``Biscuit`` class defines an ``__eq__`` method.

If you have more than one assertion in your test you can include an identifier
for the tested value in the assertion::
for the tested value in the assertion:

.. code:: python
```python
assert_that(theBiscuit.getChocolateChipCount(), equal_to(10), 'chocolate chips')
assert_that(theBiscuit.getHazelnutCount(), equal_to(3), 'hazelnuts')
```
assert_that(theBiscuit.getChocolateChipCount(), equal_to(10), 'chocolate chips')
assert_that(theBiscuit.getHazelnutCount(), equal_to(3), 'hazelnuts')
As a convenience, assert_that can also be used to verify a boolean condition::
As a convenience, assert_that can also be used to verify a boolean condition:

```python
assert_that(theBiscuit.isCooked(), 'cooked')
```
.. code:: python
assert_that(theBiscuit.isCooked(), 'cooked')
This is equivalent to the ``assert_`` method of unittest.TestCase, but because
it's a standalone function, it offers greater flexibility in test writing.
Expand All @@ -85,8 +93,7 @@ PyHamcrest comes with a library of useful matchers:
* ``equal_to`` - match equal object
* ``has_length`` - match ``len()``
* ``has_property`` - match value of property with given name
* ``has_properties`` - match an object that has all of the given
properties.
* ``has_properties`` - match an object that has all of the given properties.
* ``has_string`` - match ``str()``
* ``instance_of`` - match object type
* ``none``, ``not_none`` - match ``None``, or not ``None``
Expand All @@ -103,8 +110,7 @@ PyHamcrest comes with a library of useful matchers:
* ``contains_string`` - match part of a string
* ``ends_with`` - match the end of a string
* ``equal_to_ignoring_case`` - match the complete string but ignore case
* ``equal_to_ignoring_whitespace`` - match the complete string but ignore
extra whitespace
* ``equal_to_ignoring_whitespace`` - match the complete string but ignore extra whitespace
* ``matches_regexp`` - match a regular expression in a string
* ``starts_with`` - match the beginning of a string
* ``string_contains_in_order`` - match parts of a string, in relative order
Expand All @@ -113,17 +119,15 @@ PyHamcrest comes with a library of useful matchers:

* ``all_of`` - ``and`` together all matchers
* ``any_of`` - ``or`` together all matchers
* ``anything`` - match anything, useful in composite matchers when you don't
care about a particular value
* ``anything`` - match anything, useful in composite matchers when you don't care about a particular value
* ``is_not`` - negate the matcher

* Sequence

* ``contains`` - exactly match the entire sequence
* ``contains_inanyorder`` - match the entire sequence, but in any order
* ``has_item`` - match if given item appears in the sequence
* ``has_items`` - match if all given items appear in the sequence, in any
order
* ``has_items`` - match if all given items appear in the sequence, in any order
* ``is_in`` - match if item appears in the given sequence
* ``only_contains`` - match if sequence's items appear in given list

Expand All @@ -150,23 +154,23 @@ Syntactic sugar

PyHamcrest strives to make your tests as readable as possible. For example, the
``is_`` matcher is a wrapper that doesn't add any extra behavior to the
underlying matcher. The following assertions are all equivalent::
underlying matcher. The following assertions are all equivalent:

.. code:: python
```python
assert_that(theBiscuit, equal_to(myBiscuit))
assert_that(theBiscuit, is_(equal_to(myBiscuit)))
assert_that(theBiscuit, is_(myBiscuit))
```
assert_that(theBiscuit, equal_to(myBiscuit))
assert_that(theBiscuit, is_(equal_to(myBiscuit)))
assert_that(theBiscuit, is_(myBiscuit))
The last form is allowed since ``is_(value)`` wraps most non-matcher arguments
with ``equal_to``. But if the argument is a type, it is wrapped with
``instance_of``, so the following are also equivalent::
``instance_of``, so the following are also equivalent:

```python
assert_that(theBiscuit, instance_of(Biscuit))
assert_that(theBiscuit, is_(instance_of(Biscuit)))
assert_that(theBiscuit, is_(Biscuit))
```
.. code:: python
assert_that(theBiscuit, instance_of(Biscuit))
assert_that(theBiscuit, is_(instance_of(Biscuit)))
assert_that(theBiscuit, is_(Biscuit))
*Note that PyHamcrest's ``is_`` matcher is unrelated to Python's ``is``
operator. The matcher for object identity is ``same_instance``.*
Expand All @@ -183,49 +187,49 @@ bundle the fragment into a single assertion. By writing your own matcher you'll
eliminate code duplication and make your tests more readable!

Let's write our own matcher for testing if a calendar date falls on a Saturday.
This is the test we want to write::
This is the test we want to write:

.. code:: python
def testDateIsOnASaturday(self):
d = datetime.date(2008, 04, 26)
assert_that(d, is_(on_a_saturday()))
```python
def testDateIsOnASaturday(self):
d = datetime.date(2008, 04, 26)
assert_that(d, is_(on_a_saturday()))
```
And here's the implementation:

And here's the implementation::
.. code:: python
```python
from hamcrest.core.base_matcher import BaseMatcher
from hamcrest.core.helpers.hasmethod import hasmethod
from hamcrest.core.base_matcher import BaseMatcher
from hamcrest.core.helpers.hasmethod import hasmethod
class IsGivenDayOfWeek(BaseMatcher):
class IsGivenDayOfWeek(BaseMatcher):
def __init__(self, day):
self.day = day # Monday is 0, Sunday is 6
def __init__(self, day):
self.day = day # Monday is 0, Sunday is 6
def _matches(self, item):
if not hasmethod(item, 'weekday'):
return False
return item.weekday() == self.day
def _matches(self, item):
if not hasmethod(item, 'weekday'):
return False
return item.weekday() == self.day
def describe_to(self, description):
day_as_string = ['Monday', 'Tuesday', 'Wednesday', 'Thursday',
'Friday', 'Saturday', 'Sunday']
description.append_text('calendar date falling on ') \
.append_text(day_as_string[self.day])
def describe_to(self, description):
day_as_string = ['Monday', 'Tuesday', 'Wednesday', 'Thursday',
'Friday', 'Saturday', 'Sunday']
description.append_text('calendar date falling on ') \
.append_text(day_as_string[self.day])
def on_a_saturday():
return IsGivenDayOfWeek(5)
```
def on_a_saturday():
return IsGivenDayOfWeek(5)
For our Matcher implementation we implement the ``_matches`` method - which
calls the ``weekday`` method after confirming that the argument (which may not
be a date) has such a method - and the ``describe_to`` method - which is used
to produce a failure message when a test fails. Here's an example of how the
failure message looks::
failure message looks:

```python
assert_that(datetime.date(2008, 04, 06), is_(on_a_saturday()))
```
.. code:: python
assert_that(datetime.date(2008, 04, 06), is_(on_a_saturday()))
fails with the message::

Expand All @@ -234,21 +238,21 @@ fails with the message::
got: <2008-04-06>

Let's say this matcher is saved in a module named ``isgivendayofweek``. We
could use it in our test by importing the factory function ``on_a_saturday``::
could use it in our test by importing the factory function ``on_a_saturday``:

.. code:: python
```python
from hamcrest import *
import unittest
from isgivendayofweek import on_a_saturday
from hamcrest import *
import unittest
from isgivendayofweek import on_a_saturday
class DateTest(unittest.TestCase):
def testDateIsOnASaturday(self):
d = datetime.date(2008, 04, 26)
assert_that(d, is_(on_a_saturday()))
class DateTest(unittest.TestCase):
def testDateIsOnASaturday(self):
d = datetime.date(2008, 04, 26)
assert_that(d, is_(on_a_saturday()))
if __name__ == '__main__':
unittest.main()
```
if __name__ == '__main__':
unittest.main()
Even though the ``on_a_saturday`` function creates a new matcher each time it
is called, you should not assume this is the only usage pattern for your
Expand Down
2 changes: 1 addition & 1 deletion doc/conf.py
View file
Expand Up @@ -72,7 +72,7 @@
exclude_patterns = ['_build']

# The reST default role (used for this markup: `text`) to use for all documents.
default_role = ':py:obj:'
default_role = 'py:obj'

# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = False
Expand Down
12 changes: 2 additions & 10 deletions doc/object_matchers.rst
View file
Expand Up @@ -19,15 +19,8 @@ has_string

.. automodule:: hamcrest.library.object.hasstring

has_properties
^^^^^^^^^^^^^^

.. automodule:: hamcrest.library.object.hasproperty
:exclude-members: has_properties
.. autofunction:: has_properties(matcher_dict)

has_property
^^^^^^^^^^^^
has_properties/has_property
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. automodule:: hamcrest.library.object.hasproperty

Expand All @@ -50,4 +43,3 @@ calling, raises
^^^^^^^^^^^^^^^

.. automodule:: hamcrest.core.core.raises

0 comments on commit fd4ef99

Please sign in to comment.