octopusapi 0.1

Instructions

1. Clone the template project, replacing my-project with the name of the project you are creating:

   git clone https://github.com/seanfisk/python-project-template.git my-project
   cd my-project

2. Edit the metadata file my_module/metadata.py to correctly describe your project.

3. Generate files based upon the project metadata you just entered:

   python internal/generate.py

   The generation script will remove all the template files and generate real files, then self-destruct upon completion.

4. Delete the old git history and optionally re-initialize the repository:

   rm -rf .git # or `ri -recurse -force .git' for PowerShell
   git init

5. Change the license in setup.py and replace the generated LICENSE file with the one of your choice. If you would like to use the MIT license, no change is necessary.

6. Change the classifiers keyword in setup.py. This will require modification.

7. Replace this README with your own text.

8. (Optional, but good practice) Create a new virtual environment for your project:

   With pyenv and pyenv-virtualenv:

   pyenv virtualenv my-project
   pyenv local my-project

   With virtualenvwrapper:

   mkvirtualenv my-project

   With plain virtualenv:

   virtualenv /path/to/my-project-venv
   source /path/to/my-project-venv/bin/activate

   If you are new to virtual environments, please see the Virtual Environment section of Kenneth Reitz’s Python Guide.

9. Install the project’s development and runtime requirements:

   pip install -r requirements-dev.txt

10. Install argparse package when developing on Python 2.6:

    pip install argparse

11. Run the tests:

    paver test_all

    You should see output similar to this:

    $ paver test_all
    ---> pavement.test_all
    No style errors
    ========================================= test session starts =========================================
    platform darwin -- Python 2.7.3 -- pytest-2.3.4
    collected 5 items
    
    tests/test_main.py .....
    
    ====================================== 5 passed in 0.05 seconds =======================================
      ___  _   ___ ___ ___ ___
     | _ \/_\ / __/ __| __|   \
     |  _/ _ \\__ \__ \ _|| |) |
     |_|/_/ \_\___/___/___|___/

    The substitution performed is rather naive, so some style errors may be reported if the description or name cause lines to be too long. Correct these manually before moving to the next step. If any unit tests fail to pass, please report an issue.

Project setup is now complete!

Using Paver

The pavement.py file comes with a number of tasks already set up for you. You can see a full list by typing paver help in the project root directory. The following are included:

Tasks from pavement:
lint             - Perform PEP8 style check, run PyFlakes, and run McCabe complexity metrics on the code.
doc_open         - Build the HTML docs and open them in a web browser.
coverage         - Run tests and show test coverage report.
doc_watch        - Watch for changes in the Sphinx documentation and rebuild when changed.
test             - Run the unit tests.
get_tasks        - Get all paver-defined tasks.
commit           - Commit only if all the tests pass.
test_all         - Perform a style check and run all unit tests.

For example, to run the both the unit tests and lint, run the following in the project root directory:

paver test_all

To build the HTML documentation, then open it in a web browser:

paver doc_open

Using Tox

Tox is a tool for running your tests on all supported Python versions. Running it via tox from the project root directory calls paver test_all behind the scenes for each Python version, and does an additional test run to ensure documentation generation works flawlessly. You can customize the list of supported and thus tested Python versions in the tox.ini file.

Pip Requirements Files vs. Setuptools install_requires Keyword

The difference in use case between these two mechanisms can be very confusing. The pip requirements files is the conventionally-named requirements.txt that sits in the root directory of many repositories, including this one. The Setuptools install_requires keyword is the list of dependencies declared in setup.py that is automatically installed by pip or easy_install when a package is installed. They have similar but distinct purposes:

install_requires keyword

Install runtime dependencies for the package. This list is meant to exclude versions of dependent packages that do not work with this Python package. This is intended to be run automatically by pip or easy_install.

pip requirements file

Install runtime and/or development dependencies for the package. Replicate an environment by specifying exact versions of packages that are confirmed to work together. The goal is to ensure repeatability and provide developers with an identical development environment. This is intended to be run manually by the developer using pip install -r requirements-dev.txt.

For more information, see the answer provided by Ian Bicking (author of pip) to this StackOverflow question.