A simple Python project template for U.S. Geological Survey (USGS) software projects. The main goal of this project is to automatically create a clear, consistent, and structured code project setup for USGS software like the following:

• Simple, clear, consistent, and structured Python project template designed to meet U.S. Geological Survey (USGS) software project needs using Cookiecutter
• Code testing setup with pytest
• Website and code documentation setup with Sphinx
• Formatted AUTHORS, CHANGELOG, CONTRIBUTING, and README files
• Clear LICENSE file for USGS software
• Automatically adds the approved or preliminary disclaimer statements for software from the USGS Fundamental Science Practices
• Helpful project cleanup with an initial Makefile
• Helpful .gitignore file
• Installation ready setup.py file
• Free software - CC0 1.0

To generate a template Python project for USGS software, run the Cookiecutter program in a directory of your choice with the url location of this cookiecutter-python-package template project:

$ cookiecutter https://github.com/usgs/cookiecutter-python-package.git

After running the command above, you will be prompted to answer a few questions about your software project and then your project template will be created in your current working directory.

FYI, there is an example cookiecutter-python-package project template called pyproj located in the examples directory of this repository. The example project template also includes a initial project website located in the docs directory. To open the website, navigate to example/pyproj/docs/_build/html) and open the index.html file in your browser.

• Python - version 2 or 3
• Cookiecutter
• pytest
• Sphinx

You can download and install Python (version 2 or 3) by visiting https://www.python.org/downloads/.

Python ships with a package manager called pip that is used to install and manage Python software packages. After intalling Python, you can use pip from the terminal or Windows command line to install the Cookiecutter program. Using a terminal:

$ pip install cookiecutter

Or, if you have Anaconda, a free scientific Python distrubution, you can use conda:

$ conda install -c https://conda.binstar.org/pydanny cookiecutter

As a side note, on Windows, you can install Git which will provide a Unix-style terminal and a shell called Git Bash.

Please see http://cookiecutter.readthedocs.io/en/latest/installation.html for more information on installing Cookiecutter.

This example shows how Clarence King, first director of the USGS, would have created a cookiecutter-python-package template project for his work as a U.S. Geologist on the Geological Exploration of the Fortieth Parallel, commonly known as the Fortieth Parallel Survey, in 1867.

In the directory where you want your software project to reside, run the cookiecutter program (Cookiecutter) with the url location of the cookiecutter-python-package template project:

$ cookiecutter https://github.com/usgs/cookiecutter-python-package.git

Answer the following prompts where default values are specified in the brackets:

full_name [Jeremiah Lant]: Clarence King
email [[email protected]]: [email protected]
project_name [pyproj]: Fortieth Parallel
project_slug [fortieth_parallel]: <Enter>
project_short_description [pyproj contains all the files and directories you need to create a Python project.]: fortieth_parallel is a command line utility that narrates the geologic exploration of the Fortieth Parallel
release_date [2016-05-14]: 1878-01-01
year [1878]: <Enter>
version [0.1.0]: <Enter>
reviewed_and_approved [no]: yes

Let's take a look at the contents of the template project:

$ tree fortieth_parallel

Let's run our initial tests:

$ cd fortieth_parallel
$ py.test tests

Let's make a project website and then look at it's front page:

$ cd docs
$ make html
sphinx-build ...
...
Build finished. The HTML pages are in _build/html.
$ firefox _build/html/index.html

Here's what the initial code documentation page looks like on the project website

You are now ready to start coding (the fun part!) with the framework and structure of your software project already setup. Have fun!

This software is licensed under CC0 1.0 and is in the public domain because it contains materials that originally came from the U.S. Geological Survey (USGS), an agency of the United States Department of Interior. For more information, see the official USGS copyright policy.

This software has been approved for release by the U.S. Geological Survey (USGS). Although the software has been subjected to rigorous review, the USGS reserves the right to update the software as needed pursuant to further analysis and review. No warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. Furthermore, the software is released on condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from its authorized or unauthorized use.

The USGS provides no warranty, expressed or implied, as to the correctness of the furnished software or the suitability for any purpose. The software has been tested, but as with any complex software, there could be undetected errors. Users who find errors are requested to report them to the USGS.

References to non-USGS products, trade names, and (or) services are provided for information purposes only and do not constitute endorsement or warranty, express or implied, by the USGS, U.S. Department of Interior, or U.S. Government, as to their suitability, content, usefulness, functioning, completeness, or accuracy.

Although this program has been used by the USGS, no warranty, expressed or implied, is made by the USGS or the United States Government as to the accuracy and functioning of the program and related program material nor shall the fact of distribution constitute any such warranty, and no responsibility is assumed by the USGS in connection therewith.

This software is provided "AS IS."

Jeremiah Lant (@jlant-usgs)