This is a collection of standard files that are typically needed for most Python-related repositories. Not all files in this repository may be needed for every Python project, but it's a good collection of common tools and configurations to which you can refer.
To create a new repository using this template, the first thing you will need is the cookiecutter Python module, which you can install with pip:
pip install cookiecutterOnce you have that, you create the new repository with a command such as:
cookiecutter -o . https://github.com/broadinstitute/cookiecutter-bits-pypi.gitThis command will create a new repository in the current directory using this template. You will then need to answer all questions asked by cookiecutter, which will create a directory with your new repository setup. You can then cd to this directory and run git init to make it a git repository.
A separate Python module (scaraplate) is used to update a repository that was created with a previous revision of this template. This module can be installed with pip:
pip install scaraplatescaraplate also requires the template to be cloned to a local directory:
cd /tmp
git clone https://github.com/broadinstitute/cookiecutter-bits-pypi.gitNow, you can cd into the directory where your repository directory lives (i.e. not the actual repository itself). The directory is assumed to be python-package_name in this example. Use scaraplate to update your repository to the latest configuration:
scaraplate rollup /tmp/cookiecutter-bits-pypi python-package_nameYou will have to confirm the answers (by just hitting Enter) from the original cookiecutter creation of this repository. This should update all the templated files that come from this repository and leave all the other files in your current repository alone.
This process is a bit more involved than just using the template given that cookiecutter will overwrite a directory completely if you point it at a pre-existing repository. Therefore, the best method is to:
- Run
cookiecutterto create a new repository with the same name and settings that would match the repository you want to convert. - Go to your original repository and create a new branch.
- Copy any non-conflicting files from the original repository to this new repository.
- Copy the
.gitdirectory from the original repository to this new templated repository.
When you do a git diff now, you should just see the new files that cookiecutter added. You should then commit these changes to the new branch to save the changes cookiecutter has made.
To test that future updates using scaraplate won't overwrite any inappropriate files, you should then use the scaraplate procedure to update this new branch and make sure no changes were made, since the template should presumably be up to date.
This is a just brief overview of the files.
This is a sample .gitignore that just ignores all files. This is primarily here as a protection for this repository so that files need to be added to the repository forcefully using -f. A normal repository will have a far less restrictive .gitignore.
This is a config for pre-commit, which is a library to control pre-commit hooks for Git. These are just the standard ones BITS uses in Python repositories.
This is a sample TravisCI configuration file that can be used to run TravisCI jobs for commits to your repository for unit tests, linting, etc. It currently supports:
- Python versions 2.7, 3.4, 3.5, and 3.6
- Pip package installation using pipenv
- Unit tests using green
- A pre-flight stage that runs yamllint and pylama on the whole codebase
This is the BITS standard configuration file for the yamllint YAML linting application.
This is a simple script that starts up or builds a development environment in Docker. The way it works is it looks for an image by the name specified at the top of the script. If that image doesn't exist, it uses the Dockerfile in the local directory to build the image. You are then dropped into a bash shell inside that container under the /working path. The present working directory outside the container is volume mapped to /working inside the container as well.
This is a sample Dockerfile that can be used to create a Python container for use as a development environment for whatever Python]1 configuration you wish to use. By default, it uses Python 3.6 and pipenv to install packages.
The default license approved for use at the Broad Institute (BSD 3-Clause "New" or "Revised" License).
The file used by pipenv to install PyPi packages. This file will be removed in a later release as Poetry is now the default dependency manager.
This is the BITS standard configuration file for the pylama Python linting application.
The file used by Poetry to install PyPi packages. Poetry is now the default dependency manager used in place of pipenv. There is a default list of packages included in this file to start. Obviously, more packages will probably be needed depending on the project.
For BITS repos (named bits-reponame), be careful when answering the questions asked by cookiecutter. For example, suppose we are making a new project to automate the widget service:
- project_repo: Make sure this is set to bits-widget
- project_slug: Make sure this is set to just widget
- pypi_repo: Make sure this is set to bits-widget
This has to do with the templates used to generate the repository. They all require these values set in this manner for all the parts to line up correctly.