Welcome to cookiecutter-modern-pypackage’s documentation!

Getting Started

Cookiecutter Modern PyPackage

GitHub release (latest SemVer) Python Version License Tests Read the Docs Black pre-commit

Cookiecutter template for a modern Python package.

Features

Quickstart

Install the latest Cookiecutter if you haven’t installed it yet (this requires Cookiecutter 1.4.0 or higher):

pip install -U cookiecutter

Generate a Python package project:

cookiecutter gh:mario-bermonti/cookiecutter-modern-pypackage

Then:

  • Create a repo and put it there.

  • Install the dev requirements into a virtualenv. (poetry install)

  • Install pre-commit hooks. (poetry run inv install-hooks)

  • Configure Codecov repository settings. (Codecov App, CODECOV_TOKEN)

  • Add the repo to your Read the Docs account + turn on the Read the Docs service hook.

  • Configure PyPI token. (PYPI_TOKEN)

  • Release your package by pushing a new tag.

For more details, see the tutorial.

Contributing to this project

All contributions are welcome!

Will find a detailed description of all the ways you can contribute to cookiecutter-modern-pypackage in the contributing guide.

This is a beginner-friendly project so don’t hesitate to ask any questions or get in touch with the project’s maintainers.

Please review the project’s code of conduct before making any contributions.

Credits

This cookiecutter is a fork of fedejaure’s awesome python package template. It uses most of fedejaure’s code and configuration, but it has been adapted so it is easier to use by scientists who have limited technical background in programming.

Please do checkout fedejaure’s template as it is great and may even be better suited for your needs.

This template is also influenced by these awesome projects:

Tutorial

Note

Did you find any of these instructions confusing? Edit this file and submit a pull request with your improvements!

To start with, you will need a GitHub account and an account on PyPI. You only need the Pypi account if you want to publish to pypi. Create these before you get started on this tutorial. If you are new to Git and GitHub, you should probably spend a few minutes on some of the tutorials at the top of the page at GitHub Help.

Step 1: Install Cookiecutter

Install cookiecutter:

$ pip install cookiecutter

We’ll also need poetry so install that too.

Step 2: Generate Your Package

Now it’s time to generate your Python package.

Use cookiecutter, pointing it at the cookiecutter-pypackage repo:

$ cookiecutter gh:mario-bermonti/cookiecutter-modern-pypackage

You’ll be asked to enter a bunch of values to set the package up. If you don’t know what to enter, stick with the defaults.

Step 3: Create a GitHub Repo

Go to your GitHub account and create a new repo named mypackage, where mypackage matches the [project_name] from your answers to running cookiecutter.

You will find one folder named after the [project_name]. Move into this folder, and then setup git to use your GitHub repo and upload the code:

$ cd mypackage
mypackage $ git init .
mypackage $ git add .
mypackage $ git commit -m "Initial skeleton."
mypackage $ git remote add origin git@github.com:myusername/mypackage.git
mypackage $ git push -u origin master

Where myusername and mypackage are adjusted for your username and package name.

You’ll need a ssh key to push the repo. You can Generate a key or Add an existing one.

Step 4: Install Dev Requirements

You should still be in the folder containing the pyproject.toml file.

Install the new project’s local development requirements inside a virtual environment using poetry:

$ poetry install
$ poetry run inv install-hooks

Step 5: Set Up Codecov

Codecov provides highly integrated tools to group, merge, archive, and compare coverage reports.

Log into your account at Codecov. If you don’t have one, create one and log into it.

Click on Add new repository. Choose the desired one. Then follow the instructions to setup the CODECOV_TOKEN on the github secrets.

Install the Codecov github App.

Now your coverage reports will be generated when a new PR is created.

Step 6: Set Up Read the Docs

Read the Docs hosts documentation for the open source community. Think of it as Continuous Documentation.

Log into your account at Read the Docs . If you don’t have one, create one and log into it.

If you are not at your dashboard, choose the pull-down next to your username in the upper right, and select “My Projects”. Choose the button to Import the repository and follow the directions.

Now your documentation will get rebuilt when you make documentation changes to your package.

Step 7: Release on PyPI

Note

This section only applies if you want to publish your project to PyPI.

The Python Package Index or PyPI is the official third-party software repository for the Python programming language. Python developers intend it to be a comprehensive catalog of all open source Python packages.

Log into your account at PyPI. Go to Account Settings and generate an API tokens.

Go to the repository settings on GitHub, and add tow secrets named PYPI_TOKEN with the tokens that you just generated.

Release your package by pushing a new tag.

Having problems?

Visit our Issues page and create a new Issue. Be sure to give as much information as possible.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

2.0.0 - 2021-12-05

Changed

  • Use my info in the project

  • Fix errors with poetry, black, flakehell, and other dependencies

  • Improve the ci actions

  • Add tests

  • Fix license names

  • Change some configs to better suite our needs in research

  • Many dependencies have been updated

1.2.2 - 2021-03-19

Changed

  • xdoctest from 0.15.2 to 0.15.4.

  • pre-commit from ^2.9.3 to ^2.11.1.

  • pytest from ^6.2.1 to ^6.2.2.

  • mypy from ^0.790 to ^0.812.

  • watchdog from ^1.0.2 to ^2.0.2.

  • sphinx from ^3.4.3 to ^3.5.2.

  • darglint from ^1.5.8 to ^1.7.0.

  • flake8-annotations from ^2.5.0 to ^2.6.1.

  • flake8-bugbear from ^20.11.1 to ^21.3.2.

  • flake8-docstrings from 1.5.0 to 1.6.0.

  • codecov/codecov-action from v1.0.13 to v1.3.1.

Fixed

  • bump2version invoke command.

1.2.1 - 2021-01-23

Changed

  • xdoctest from 0.15.0 to 0.15.2.

Fixed

  • bump2version config file.

1.2.0 - 2021-01-17

Added

  • pyproject documentation entry.

  • pyproject tool.poetry.urls section.

Fixed

  • Readme links.

Changed

  • sphinx from ^3.4.0 to ^3.4.3.

  • safety from ^1.10.0 to ^1.10.3.

  • flake8-blind-except from ^0.1.1 to ^0.2.0.

  • flake8-annotations from ^2.1.0 to ^2.5.0.

  • isort from ^5.6.4 to ^5.7.0.

  • invoke from ^1.4.1 to ^1.5.0.

  • flakehell from ^0.7.1 to ^0.9.0.

  • parametrize cli tests.

1.1.3 - 2020-12-23

Changed

  • sphinx from ^3.3.0 to ^3.4.0.

  • recommonmark from 0.6.0 to 0.7.1.

  • watchdog from ^0.10.2 to ^1.0.2.

  • pre-commit from ^2.8.2 to ^2.9.3.

  • flakehell from ^0.7.0 to ^0.7.1.

  • safety from ^1.9.0 to ^1.10.0.

  • darglint from ^1.3.0 to ^1.5.8.

  • flake8-bugbear from ^20.1.4 to ^20.11.1.

  • actions/setup-python from v2.1.4 to v2.2.1.

  • pytest from ^6.1.2 to ^6.2.1.

1.1.2 - 2020-11-07

Changed

  • flakehell from ^0.6.1 to ^0.7.0.

  • create-release action from v1 to v1.1.4.

  • checkout action from v2 to v2.3.4.

  • setup-python action from v2 to v2.1.4.

  • sphinx from ^3.2.1 to ^3.3.0.

  • pre-commit from ^2.7.1 to ^2.8.2.

  • pytest from ^6.1.1 to ^6.1.2.

Fixes

  • mypy nox session requirements.

1.1.1 - 2020-10-18

Fixes

  • docs/conf.py imports.

  • coverage config.

1.1.0 - 2020-10-17

Changed

  • to src structure.

  • poject_name validation.

Added

  • project_title.

1.0.1 - 2020-10-15

Fixed

  • unnecessary validation_depth on mindsers/changelog-reader-action.

1.0.0 - 2020-10-15

Added

  • License section on the docs.

  • Codecov integration.

  • PyPI and TestPyPI steps on the release workflow.

  • Python 3.9 support.

Changed

  • github actions ready to configure activity types.

  • isort from ^5.5.4 to ^5.6.4.

  • bump2version from master to ^1.0.1.

  • mypy from ^0.782 to ^0.790.

  • coverage from ^5.1 to ^5.3.

  • pytest-cov from ^2.8.1 to ^2.10.1.

  • pytest from ^5.4.2 to ^6.1.1.

  • flake8 from ^3.7.9 to ^3.8.4.

Fixed

  • missing pre-commit requirement.

  • get release version on the release workflow.

0.2.1 - 2020-10-05

Changed

  • changelog-reader-action from v1.1.0 to v2.

  • sphinx from 3.0.4 to 3.2.1.

  • flakehell from 0.3.6 to 0.6.1.

  • black from 19.10b0 to 20.8b1.

  • xdoctest from 0.12.0 to 0.15.0.

  • mypy from 0.770 to 0.782

Fixed

  • read the docs dependencies.

0.2.0 - 2020-10-04

Added

  • Dependabot configuration.

  • Safety session to nox.

  • Safety step to the test workflow.

Changed

  • flake8 version to ^3.7.9.

  • isort version to ^5.5.4.

  • poetry export without hashes on the noxfiles.

Removed

  • Pyup.io integration.

  • seed-isort-config from the pre-commit-config.

Fixed

  • docs/readme.md symbolic link to README.md.

  • docs/changelog.md symbolic link to CHANGELOG.md.

  • missing badges.

0.1.4 - 2020-09-07

Changed

  • Python actions to the v2.

Removed

  • Unnecessary python steps on the release workflow.

Fixed

  • bump2version version.

0.1.3 - 2020-08-13

Fixed

  • isort support for pyproject.toml

  • docs conf code style.

Removed

  • sphinx-autodoc-typehints from the dev requirements.

0.1.2 - 2020-06-14

Fixed

  • Read the docs build config.

Removed

  • Pytype from the dev requirements.

0.1.1 - 2020-06-14

Added

  • New option serve to the invoke docs task.

Changed

  • Improve docs tutorial section.

  • Improve docs index section.

Fixed

  • README spelling.

  • Ivoke pytype task typo.

0.1.0 - 2020-06-11

Added

  • First release.

Contributing

Thank you for your interest in improving this project.

All contributions are welcome and greatly appreciated! Every little bit improves the project and helps its users.

The following sections detail a variety of ways to contribute and how to get started.

Credit will always be given to the people making contributions.

If you do decide to work on an issue, please indicate so in a comment to the issue so it’s assigned to you and other people don’t work on it simultaneously.

This is a beginner-friendly project so don’t hesitate to write a comment in the issue you are interested in if you have questions, would like to discuss some issue further, or you need help in any way.

Types of Contributions

Spread the word

Tell others about your experience with cookiecutter-modern-pypackage. You can share it on social media and follow it on GitHub.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/mario-bermonti/cookiecutter-modern-pypackage/issues.

Please let us know about your experience using cookiecutter-modern-pypackage. You can tell us about the things that you like, the things that can be improved, and the things that you would like cookiecutter-modern-pypackage to do.

If you are proposing a feature:

  • How it would help you and other users (mainly researchers).

  • Explain all the details of 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 for this reason it may not be feasible to implement the feature or it may take some time.

Write Documentation

cookiecutter-modern-pypackage could always use more documentation. You can contribute to the documentation by:

  • Fixing typographical, grammatical, or spelling errors.

  • Improving documentation that is unclear or incorrect.

  • Creating or improving examples and tutorials.

  • Writing blog posts, articles, and similar content that share how you are using this project and your best practices with us.

Report Bugs

You can report bugs at https://github.com/mario-bermonti/cookiecutter-modern-pypackage/issues.

Please provide all the details that are asked when you create the issue to make sure it is understood correctly.

Fix existing bugs

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

Implement Features

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

Start contributing!

Set up the development environment

Ready to contribute? Here’s how to set up cookiecutter-modern-pypackage in your local development environment.

You will need Python 3.6+ installed.

  1. Fork the cookiecutter-modern-pypackage repo on GitHub.

  2. Clone your fork locally:

    git clone git@github.com:your_name_here/cookiecutter-modern-pypackage.git

  3. We use poetry to manage dependencies. Install it with the following command.

     curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -

  4. Install the project, its dependencies, and the virtualenv:

     poetry install

  5. Make sure everything is working properly before making any changes by running poetry run invoke dev-tasks.

Development tasks (important side note)

In order to run anything inside the virtual environment every command has to be prefixed with poetry run <command>.

For example, to run python inside the virtual environment you would run poetry run python.

We have most of our development tasks pre-configured to run automatically with invoke. :grin:

The most important tasks are:

Command Description
dev-tasks Run all development tasks.
format Format code.
tests Run tests.
coverage Create coverage report.
lint Run all linting.
mypy Run mypy.
docs Build documentation.
clean Run all clean sub-tasks.

You can find see all the development tasks that pre-configured by running poetry run invoke --list.

Making changes
Workflow

We work by protecting master branch and only merging changes that don’t break existing functionality and are tested.

How do we do it?:

  1. We identify something that must change

  2. We create an issue on GitHub, if it doesn’t already exist

  3. We create a new branch named after the issue we want “fix” (issue-$TASKNUMBER)

  4. We make changes and test everything works

  5. Style the code

  6. We then create a pull request to master branch that is reviewed and if approved, it is merged into master

This way we achieve an easy and scalable development process that avoids merge conflicts and long-living branches.

In this method, the master branch always has the latest working version of the software, is stable, and is working.

How to make changes

Follow this steps when working on changes to the project. Please see the Workflow section for important details about making changes.

  1. Create a branch for local development. All the changes must be in this branch.

    $ git checkout -b name-of-your-bugfix-or-feature

  2. Run the all checks to make sure everything is working before making any changes

     $ poetry run invoke dev-tasks

  3. Add any changes you want

  4. Add tests for the new changes

  5. Run the tests and make sure they all pass

     $ poetry run invoke tests

  6. Edit the documentation if appropriate (this is required for new features)

  7. Make sure the changes to the documentation are correct and that the docs build

     $ poetry run invoke docs

  8. Make sure everything is fine (e.g., tests, code style, coverage)

     $ poetry run invoke dev-tasks

    If you find that something is not working as expected, fix it, check that it is working appropriately by running the appropriate invoke command (see Development tasks section).

     $ poetry run invoke <command>

    After it is fixed, run all development tasks again

     $ poetry run invoke dev-tasks

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

    $ git add .
$ git commit

    Cookiecutter-Modern-Pypackage follows specific guidelines for commit messages:

    • Make a reference to the relevant GitHub issues in your commit message (e.g., Fix #1234) We use imperative mood for commit messages (fix x, instead of fixed x). See this commit guide. A tip is to use a title for your commit message that completes “This commit will…” [Fix issue X].

    • The subject line should have < 80 chars

    • Leave one line blank

    • [Optional] Explain any relevant details or decisions made

  10. Push your changes to GitHub

     $ git push origin name-of-your-bugfix-or-feature

  11. Submit a pull request through GitHub (see the Pull Request Guidelines section).

Pull Request Guidelines

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

  1. The pull request should include tests for new functionality.

  2. If the pull request adds functionality, the docs should be updated.

  3. The pull request should pass all tests and must work for all the supported Python versions. It must also pass all checks in the GitHub CI.

Feel free to submit your pull request early so we can discuss it and iterate on the process.

Tips

We really value your contributions and want to integrate your changes. The following are tips to improve the probability that your changes are accepted.

  • Make sure they don’t break existing functionality

  • Include tests for the changes you made

  • Commit often

  • Make small, easy to understand commits (i.e., atomic commits)

  • Keep your changes in the narrowest scope possible (e.g., create tutorial for using the X object)

  • It is recommended to open an issue before starting work on anything. This will allow a chance to talk it over with the maintainers and validate your approach.

Releasing cookiecutter-modern-pypackage

Maintainers, please review the guide for releasing new versions of cookiecutter-modern-pypackage on Github and Pypi.

Contributor Covenant Code of Conduct

Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Examples of behavior that contributes to creating a positive environment include:

  • Using welcoming and inclusive language

  • Being respectful of differing viewpoints and experiences

  • Gracefully accepting constructive criticism

  • Focusing on what is best for the community

  • Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

  • The use of sexualized language or imagery and unwelcome sexual attention or advances

  • Trolling, insulting/derogatory comments, and personal or political attacks

  • Public or private harassment

  • Publishing others’ private information, such as a physical or electronic address, without explicit permission

  • Other conduct which could reasonably be considered inappropriate in a professional setting

Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at mbermonti1132@gmail or mbermonti@psm.edu. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq

Basics

Prompts

When you create a package, you are prompted to enter these values.

Templated Values

The following appear in various parts of your generated project.

full_name

Your full name.

email

Your email address.

github_username

Your GitHub username.

project_name

The name of your new Python package project. This is used in the package name and the Github repository name, so use - insteed of spaces.

project_slug

The namespace of your Python package. This should be Python import-friendly. Typically, it is the slugified version of project_name.

project_title

The title of your new Python project. This is used in documentation, so spaces and any characters are fine here.

project_short_description

A 1-sentence description of what your Python package does.

version

The starting version number of the package.

Options

The following package configuration options set up different features for your project.

open_source_license

Whether to add a license file. Options: [“MIT”, “BSD”, “ISC”, “Apache Software License 2.0”, “GNU General Public License v3”, “Not open source”s]

command_line_interface

Whether to create a console script using Click. Console script entry point will match the project_name. Options: [“Click”, “No command-line interface”]

Invoke

The generated project is ready to run some useful tasks like formatting, linting, testing.

To do this we use pyinvoke to wrap up the required commands.

Execute inv[oke] –list to see the list of available commands.

$ poerty shell
$ inv[oke] --list
Available tasks:

  clean           Run all clean sub-tasks.
  clean-build     Clean up files from package building.
  clean-docs      Clean up files from documentation builds.
  clean-python    Clean up python file artifacts.
  clean-tests     Clean up files from testing.
  coverage        Create coverage report.
  docs            Build documentation.
  flake8          Run flake8.
  format          Format code.
  hooks           Run pre-commit hooks.
  install-hooks   Install pre-commit hooks.
  lint            Run all linting.
  mypy            Run mypy.
  safety          Run safety.
  tests           Run tests.
  version         Bump version.

Advanced Features

Console Script Setup

Optionally, your package can include a console script using Click (Python 3.6+).

How It Works

If the ‘command_line_interface’ option is set to [‘click’] during setup, cookiecutter will add a file ‘cli.py’ in the project_slug subdirectory. An entry point is added to pyproject.toml that points to the main function in cli.py.

Usage

To use the console script in development:

pip install -e projectdir

‘projectdir’ should be the top level project directory with the pyproject.toml file

The script will be generated with output for no arguments and –help.

--help

show help menu and exit

More Details

You can read more about Click at: http://click.pocoo.org/

MIT License

Copyright (c) 2021 Mario E. Bermonti Pérez

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.