python_hangman 2.1.0

Python Hangman TDD demonstration.

.. __START__ Source defined in docs/github_docs.py


.. This document was procedurally generated by docs/github_docs.py on Friday, December 18, 2015


.. __END__ Source defined in docs/github_docs.py
.. __START__ Source defined in docs/github_docs.py


.. role:: mod(literal)
.. role:: func(literal)
.. role:: data(literal)
.. role:: const(literal)
.. role:: class(literal)
.. role:: meth(literal)
.. role:: attr(literal)
.. role:: exc(literal)
.. role:: obj(literal)
.. role:: envvar(literal)


.. __END__ Source defined in docs/github_docs.py
.. __START__ Source defined in docs/source/readme_title.rst

==============
python_hangman
==============

.. image:: https://img.shields.io/github/downloads/bionikspoon/python_hangman/total.svg
:target: https://github.com/bionikspoon/python_hangman
:alt: Github Downloads

.. image:: https://badge.fury.io/py/python_hangman.svg
:target: https://pypi.python.org/pypi/python_hangman/
:alt: Latest Version

.. image:: https://img.shields.io/pypi/status/python_hangman.svg
:target: https://pypi.python.org/pypi/python_hangman/
:alt: Development Status

.. image:: https://travis-ci.org/bionikspoon/python_hangman.svg?branch=develop
:target: https://travis-ci.org/bionikspoon/python_hangman?branch=develop
:alt: Build Status

.. image:: https://coveralls.io/repos/bionikspoon/python_hangman/badge.svg?branch=develop
:target: https://coveralls.io/github/bionikspoon/python_hangman?branch=develop&service=github
:alt: Coverage Status

.. image:: https://readthedocs.org/projects/python_hangman/badge/?version=develop
:target: https://python_hangman.readthedocs.org/en/develop/?badge=develop
:alt: Documentation Status


A python version agnostic, tox tested, travis-backed program! Documented and distributed.

Has **very high** unit test coverage, with passing tests on every relevant version of python including PyPy.


.. __END__ Source defined in docs/source/readme_title.rst
.. __START__ Source defined in docs/source/readme_features.rst

Features
========

- Free software: MIT license
- Documentation: https://python_hangman.readthedocs.org.
- Hangman!
- Idiomatic code.
- Thoroughly tested with very high coverage.
- Python version agnostic.
- Demonstrates MVC design out of the scope of web development.

.. image:: https://cloud.githubusercontent.com/assets/5052422/11611464/00822c5c-9b95-11e5-9fcb-8c10fd9be7df.jpg
:alt: Screenshot


.. __END__ Source defined in docs/source/readme_features.rst
.. __START__ Source defined in docs/source/readme_compatibility.rst

Compatibility
=============

.. image:: https://img.shields.io/badge/Python-2.6,_2.7,_3.3,_3.4,_3.5,_pypy-brightgreen.svg
:target: https://pypi.python.org/pypi/python_hangman/
:alt: Supported Python versions


- Python 2.6
- Python 2.7
- Python 3.3
- Python 3.4
- Python 3.5
- PyPy


.. __END__ Source defined in docs/source/readme_compatibility.rst
.. __START__ Source defined in docs/source/installation.rst


Installation
============

At the command line either via easy_install or pip

.. code-block:: shell

$ mkvirtualenv hangman # optional for venv users
$ pip install python_hangman
$ hangman


**Uninstall**

.. code-block:: shell

$ pip uninstall python_hangman


.. __END__ Source defined in docs/source/installation.rst
.. __START__ Source defined in docs/source/goals.rst

Goals
=====

2.0.0
-----

**MVC pattern**. The goal was to explicitely demonstrate an MVC pattern out of the scope of web development.

**Idiomatic code**. In this overhaul there's a big emphasis on idiomatic code. The code should be describing its' own intention with the clarity your grandmother could read.


1.0.0
-----

Learning! This was a Test Driven Development(TDD) exercise.

Also, explored:

- Tox, test automation
- Travis CI
- Python version agnostic programming
- Setuptools
- Publishing on pip
- Coverage via coveralls
- Documentation with sphinx and ReadTheDocs
- Cookiecutter development


.. __END__ Source defined in docs/source/goals.rst
.. __START__ Source defined in docs/source/design.rst

Design
======

This game roughly follows the **Model-View-Controller(MVC)** pattern. In the latest overhaul, these roles have been explicitely named: :mod:`hangman.model`, :mod:`hangman.view`, :mod:`hangman.controller`.

Traditionally in MVC the ``controller`` is the focal point. It tells the ``view`` what information to collect from the user and what to show. It uses that information to communicate with the ``model``--also, the data persistence later--and determine the next step. This Hangman MVC adheres to these principals

Model
-----

The model is very simply the hangman game instance--:class:`hangman.model.Hangman`. It's a class. Every class should have "state" and the methods of that class should manage that state. In this case, the "state" is the current "state of the game". The public API are for manageing that state.

The entirety of the game logic is contained in :class:`hangman.model.Hangman`. You could technically play the game in the python console by instantiating the class, submitting guesses with the method :meth:`hangman.model.Hangman.guess` and printing the game state.

For example:


.. code-block:: python

>>> from hangman.hangman import Hangman
>>> game = Hangman(answer='hangman')
>>> game.guess('a')
hangman(status='_A___A_', misses=[], remaining_turns=10)

>>> game.guess('n').guess('z').guess('e')
hangman(status='_AN__AN', misses=['E', 'Z'], remaining_turns=8)

>>> game.status
'_AN__AN'

>>> game.misses
['E', 'Z']

>>> game.remaining_turns
8


View
----

:mod:`hangman.view` is a collection of stateless functions that represent the presentation layer. When called these functions handles printing the art to the console, and collecting input from the user.

Controller
----------

In this program, the ``controller`` is actually the "game_loop"--:func:`hangman.controller.game_loop`. I still think of it as a ``controller`` because the role it plays--communicating I/O from the view with the model-persistence layer.

The controller tells the view later what to print and what data to collect. It uses that information update the state of the game (model) and handle game events.


.. __END__ Source defined in docs/source/design.rst
.. __START__ Source defined in docs/source/readme_call_diagram.rst

Call Diagram
============

.. image:: https://cloud.githubusercontent.com/assets/5052422/11611800/bfc9ec20-9ba5-11e5-9b18-95d361e7ba23.png
:alt: Call Diagram


.. __END__ Source defined in docs/source/readme_call_diagram.rst
.. __START__ Source defined in docs/source/readme_credits.rst

Credits
=======

Tools used in rendering this package:

* Cookiecutter_
* `bionikspoon/cookiecutter-pypackage`_ forked from `audreyr/cookiecutter-pypackage`_

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`bionikspoon/cookiecutter-pypackage`: https://github.com/bionikspoon/cookiecutter-pypackage
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage


.. __END__ Source defined in docs/source/readme_credits.rst


History
=======

2.1.0 (2015-18-05)
------------------

* Updated docs, divided and automated in a more reasonable way.
* renamed the github repo to mirror pypi name.


2.0.0 (2015-12-05)
------------------

* Establishing a changelog.
* Massive refactoring, explicit MVC structure.
* Code is even more idiomatic!
* Created a `FlashMessage` utility.
* Removed poorly implemented classes in favor of stateless functions.
* Add, Remove support for py35, py32.
* 100% code coverage. (2 untestable, inconsequential lines ignored)