Welcome to python_hangman’s documentation!

Contents:

python_hangman

Latest Version Development Status Build Status Coverage Status Documentation Status

A well tested, cli, python version-agnostic, multi-platform hangman game. It’s built following a TDD workflow and a MVC design pattern. Each component services a sensibly distinct logical purpose. Python Hangman is a version agnostic, tox tested, travis-backed program! Documented and distributed.

Features

Screenshot

Compatibility

Supported Python versions
  • Python 2.6
  • Python 2.7
  • Python 3.3
  • Python 3.4
  • Python 3.5
  • PyPy

Call Diagram

Call Diagram

Credits

Tools used in rendering this package:

Installation

At the command line either via easy_install or pip:

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

Uninstall:

$ pip uninstall python_hangman

Design

This game roughly follows the Model-View-Controller(MVC) pattern. In the latest overhaul, these roles have been explicitly named: hangman.model, hangman.view, 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–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 managing that state.

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

For example:

>>> from hangman.model 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

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”–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.

Goals

2.0.0

MVC pattern. The goal was to explicitly 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

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/bionikspoon/python_hangman/issues.

If you are reporting a bug, please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement it.

Write Documentation

python_hangman could always use more documentation, whether as part of the official python_hangman docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/bionikspoon/python_hangman/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up python_hangman for local development.

  1. Fork the python_hangman repo on GitHub.

  2. Clone your fork locally:

    $ git clone git@github.com:your_name_here/python_hangman.git
    
  3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

    $ mkvirtualenv python_hangman
    $ cd python_hangman/
    $ python setup.py develop
    
  4. Create a branch for local development:

    $ git checkout -b feature/name-of-your-feature
    $ git checkout -b hotfix/name-of-your-bugfix
    

    Now you can make your changes locally.

  5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

    $ flake8 hangman tests
    $ python setup.py test
    $ tox
    

    To get flake8 and tox, just pip install them into your virtualenv.

  6. Commit your changes and push your branch to GitHub:

    $ git add .
    $ git commit -m "Your detailed description of your changes."
    $ git push origin name-of-your-bugfix-or-feature
    
  7. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.
  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
  3. The pull request should work for Python 2.6, 2.7, 3.3, 3.4, 3.5, and PyPy. Check https://travis-ci.org/bionikspoon/python_hangman/pull_requests and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

$ py.test tests/test_hangman.py

Credits

Development Lead

Contributors

None yet. Why not be the first?

History

Next Release

  • Stay Posted

2.2.0 (2015-18-05)

  • Fixed max recursion issue with game loop.
  • Updated requirements.
  • Removed gratuitous docs – less is more.
  • 2.2.1 Handle ctrl+d EOF to exit.
  • 2.2.2 Fix broken coverage report.

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.1.1 Fix pypi’s rst render

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)

hangman package

python_hangman

A well tested, cli, python version-agnostic, multi-platform hangman game. It’s built following a TDD workflow and a MVC design pattern. Each component services a sensibly distinct logical purpose. Python Hangman is a version agnostic, tox tested, travis-backed program! Documented and distributed.

Submodules

hangman.__main__

Entry point for hangman command.

hangman.controller

hangman.controller.game_loop(game=hangman(status='______', misses=[], remaining_turns=10), flash=<hangman.utils.FlashMessage object>)[source]

Run a single game.

Parameters:
hangman.controller.run(game=hangman(status='____', misses=[], remaining_turns=10), flash=<hangman.utils.FlashMessage object>)[source]

Run game_loop and handle exiting.

Logic is separated from game_loop to cleanly avoid python recursion limits.

Parameters:

hangman.model

class hangman.model.Hangman(answer=None)[source]

Bases: object

The the logic for managing the status of the game and raising key game related events.

>>> from hangman.model 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
MAX_TURNS = 10
guess(letter)[source]

Add letter to hits or misses.

hits

List of hits.

is_valid_answer(word)[source]

Validate answer. Letters only. Max:16

is_valid_guess(letter)[source]

Validate guess. Letters only. Max:1

misses

List of misses.

remaining_turns

Calculate number of turns remaining.

status

Build a string representation of status.

hangman.utils

App utilities.

class hangman.utils.WordBank[source]

Bases: object

Default collection of words to choose from

WORDS = ['ATTEMPT', 'DOLL', 'ELLEN', 'FLOATING', 'PRIDE', 'HEADING', 'FILM', 'KIDS', 'MONKEY', 'LUNGS', 'HABIT', 'SPIN', 'DISCUSSION', 'OFFICIAL', 'PHILADELPHIA', 'FACING', 'MARTIN', 'NORWAY', 'POLICEMAN', 'TOBACCO', 'VESSELS', 'TALES', 'VAPOR', 'INDEPENDENT', 'COOKIES', 'WEALTH', 'PENNSYLVANIA', 'EXPLANATION', 'DAMAGE', 'OCCASIONALLY', 'EXIST', 'SIMPLEST', 'PLATES', 'CANAL', 'NEIGHBORHOOD', 'PALACE', 'ADVICE', 'LABEL', 'DANNY', 'CLAWS', 'RUSH', 'CHOSE', 'EGYPT', 'POETRY', 'BREEZE', 'WOLF', 'MANUFACTURING', 'OURSELVES', 'SCARED', 'ARRANGEMENT', 'POSSIBLY', 'PROMISED', 'BRICK', 'ACRES', 'TREATED', 'SELECTION', 'POSITIVE', 'CONSTANTLY', 'SATISFIED', 'ZOO', 'CUSTOMS', 'UNIVERSITY', 'FIREPLACE', 'SHALLOW', 'INSTANT', 'SALE', 'PRACTICAL', 'SILLY', 'SATELLITES', 'SHAKING', 'ROCKY', 'SLOPE', 'CASEY', 'REMARKABLE', 'RUBBED', 'HAPPILY', 'MISSION', 'CAST', 'SHAKE', 'REQUIRE', 'DONKEY', 'EXCHANGE', 'JANUARY', 'MOUNT', 'AUTUMN', 'SLIP', 'BORDER', 'LEE', 'MELTED', 'TRAP', 'SOLAR', 'RECALL', 'MYSTERIOUS', 'SWUNG', 'CONTRAST', 'TOY', 'GRABBED', 'AUGUST', 'RELATIONSHIP', 'HUNTER', 'DEPTH', 'FOLKS', 'DEEPLY', 'IMAGE', 'STIFF', 'RHYME', 'ILLINOIS', 'SPECIES', 'ADULT', 'FINEST', 'THUMB', 'SLIGHT', 'GRANDMOTHER', 'SHOUT', 'HARRY', 'MATHEMATICS', 'MILL', 'ESSENTIAL', 'TUNE', 'FORT', 'COACH', 'NUTS', 'GARAGE', 'CALM', 'MEMORY', 'SOAP']
classmethod get()[source]

Get a random word from word list.

classmethod set(*values)[source]

Set word list.

class hangman.utils.FlashMessage[source]

Bases: object

Basic “flash message” implementation.

game_lost = False
game_won = False
message = ''
exception hangman.utils.GameLost[source]

Bases: exceptions.Exception

Raised when out of turns.

exception hangman.utils.GameWon[source]

Bases: exceptions.Exception

Raised when answer has been guessed.

exception hangman.utils.GameOverNotificationComplete[source]

Bases: exceptions.Exception

Raised when controller should break game loop.

hangman.view

View layer, printing and prompting.

hangman.view.build_partial_misses(game_misses)[source]

Generator, build game misses block.

hangman.view.build_partial_picture(remaining_turns)[source]

Generator, build the iconic hangman game status.

hangman.view.draw_board(game, message=<hangman.utils.FlashMessage object>)[source]

Present the game status with pictures.

  • Clears the screen.
  • Flashes any messages.
  • Zip the two halves of the picture together.
+---------------------------------------------+
|              message 45 x 1                 |
+---------------------------------------------+
|              title 45 x 1                   |
+----------+----------------------------------+
|          |                                  |
|          |                                  |
|          |                                  |
|          |                                  |
| picture  |             misses               |
| 10 x 10  |             35 x 10              |
|          |                                  |
|          |                                  |
|          |                                  |
|          |                                  |
+----------+----------------------------------+
|              hits 45 x 1                    |
+---------------------------------------------+
Dare to pick a letter:
_

Example output:

                HANGMAN GAME
    _____
    |   |
        |
        |      MISSES:
        |      _ _ _ _ _ _ _ _ _ _
        |
        |
________|_
          _   _   _   _   _   _   _
Dare to pick a letter:
_
Parameters:
Raises:

hangman.utils.GameOverNotificationComplete

hangman.view.print_partial_body(picture, status)[source]
hangman.view.print_partial_hits(game_status)[source]
hangman.view.print_partial_message(flash, answer)[source]
hangman.view.print_partial_title()[source]
hangman.view.print_spacer()[source]

Print empty line

hangman.view.prompt_guess()[source]

Get a single letter.

hangman.view.prompt_play_again()[source]

Prompt user to play again.

hangman.view.say_goodbye()[source]

Write a goodbye message.

Feedback

If you have any suggestions or questions about python_hangman feel free to email me at bionikspoon@gmail.com.

If you encounter any errors or problems with python_hangman, please let me know! Open an Issue at the GitHub https://github.com/bionikspoon/python_hangman main repository.

Indices and tables