Package: octopusapi
This project provides a best-practices template Python project which integrates several different tools. It saves you work by setting up a number of things, including documentation, code checking, and unit test runners.As it is an all-in-one solution, the tools used are rather opinionated. They include:Paverfor running miscellaneous tasksSetuptoolsfor distribution (Setuptools andDistributehavemerged)Sphinxfor documentationflake8for source code checkingpytestfor unit testingmockfor mocking (not required by the template, but included anyway)toxfor testing on multiple Python versionsIf you are new to Python or new to creating Python projects, see Kenneth Reitz’sHitchhiker’s Guide to Pythonfor an explanation of some of the tools used here.Project SetupThis will be the README for your project. For now, follow these instructions to get this project template set up correctly. Then, come back and replace the contents of this README with contents specific to your project.InstructionsClone the template project, replacingmy-projectwith the name of the project you are creating:git clone https://github.com/seanfisk/python-project-template.git my-project
cd my-projectEdit the metadata filemy_module/metadata.pyto correctly describe your project.Generate files based upon the project metadata you just entered:python internal/generate.pyThe generation script will remove all the template files and generate real files, then self-destruct upon completion.Delete the old git history and optionally re-initialize the repository:rm -rf .git # or `ri -recurse -force .git' for PowerShell
git initChange the license insetup.pyand replace the generatedLICENSEfile with the one of your choice. If you would like to use the MIT license, no change is necessary.Change theclassifierskeyword insetup.py. Thiswillrequire modification.Replace this README with your own text.(Optional, but good practice)Create a new virtual environment for your project:Withpyenvandpyenv-virtualenv:pyenv virtualenv my-project
pyenv local my-projectWithvirtualenvwrapper:mkvirtualenv my-projectWith plainvirtualenv:virtualenv /path/to/my-project-venv
source /path/to/my-project-venv/bin/activateIf you are new to virtual environments, please see theVirtual Environment sectionof Kenneth Reitz’s Python Guide.Install the project’s development and runtime requirements:pip install -r requirements-dev.txtInstallargparsepackage when developing on Python 2.6:pip install argparseRun the tests:paver test_allYou 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 PaverThepavement.pyfile comes with a number of tasks already set up for you. You can see a full list by typingpaver helpin 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_allTo build the HTML documentation, then open it in a web browser:paver doc_openUsing ToxTox is a tool for running your tests on all supported Python versions.
Running it viatoxfrom the project root directory callspaver test_allbehind 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 thetox.inifile.Pip Requirements Files vs. Setuptoolsinstall_requiresKeywordThe difference in use case between these two mechanisms can be very confusing. Thepip requirements filesis the conventionally-namedrequirements.txtthat sits in the root directory of many repositories, including this one. TheSetuptools install_requires keywordis the list of dependencies declared insetup.pythat is automatically installed bypiporeasy_installwhen a package is installed. They have similar but distinct purposes:install_requireskeywordInstall runtime dependencies for the package. This list is meant toexcludeversions of dependent packages that do not work with this Python package. This is intended to be run automatically bypiporeasy_install.pip requirements fileInstall 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 toensure repeatabilityand provide developers with an identical development environment. This is intended to be run manually by the developer usingpip install-rrequirements-dev.txt.For more information, see the answer provided by Ian Bicking (author of pip) tothis StackOverflow question.Supported Python VersionsPython Project Template supports the following versions out of the box:CPython 2.6, 2.7, 3.3PyPy 1.9CPython 3.0-3.2 may also work but are at this point unsupported. PyPy 2.0.2 is known to work but is not run on Travis-CI.JythonandIronPythonmay also work, but have not been tested. If there is interest in support for these alternative implementations, please open a feature request!LicensesThe code which makes up this Python project template is licensed under the MIT/X11 license. Feel free to use it in your free software/open-source or proprietary projects.The template also uses a number of other pieces of software, whose licenses are listed here for convenience. It is your responsibility to ensure that these licenses are up-to-date for the version of each tool you are using.ProjectLicensePython itselfPython Software Foundation Licenseargparse (now in stdlib)Python Software Foundation LicenseSphinxSimplified BSD LicensePaverModified BSD LicensecoloramaModified BSD Licenseflake8MIT/X11 LicensemockModified BSD LicensepytestMIT/X11 LicensetoxMIT/X11 LicenseIssuesPlease report any bugs or requests that you have using the Github issue tracker!DevelopmentIf you wish to contribute, first make your changes. Then run the following from the project root directory:source internal/test.shThis will copy the template directory to a temporary directory, run the generation, then run tox. Any arguments passed will go directly to the tox command line, e.g.:source internal/test.sh -e py27This command line would just test Python 2.7.AuthorsSean FiskBenjamin Schwarze