A Python package template that supports the pyOpenSci pure Python packaging tutorial. This template can be used with copier to initialize a new Python package project structure following the practices outlined in the pyOpenSci pure Python packaging tutorial.
If you want to learn more about packaging, check out our Python packaging guide.
To use this template:
-
Install copier using pipx or pip preferably with a virtual environment.
Global Installation:
pipx install copieror Environment specific installation:
pip install copier -
Run the below copier command. Please note that copier creates a target directory if it doesn't exist yet. It will also create and possibly overwrite files in the given directory, even if it already exists! That includes your current directory if that is your target.
copier copy gh:pyopensci/pyos-package-template path/hereThe command below will create the package directory in your current working directory.
copier copy gh:pyopensci/pyos-package-template .Used in the above way, copier will use the latest tagged release, which is probably the safest option. You can provide an option
--vcs-refto choose specific branches as your source. You can read more about generating your project in the copier documentation.
Once you have installed copier, you are ready to create your Python package using our template.
- First, run the command below from your favorite shell and in a directory where you want to store your package. Note that this step copies our template from GitHub so it requires internet access.
copier copy gh:pyopensci/pyos-package-template .
If you wish to create the package in another directory you can specify the directory like this:
copier copy gh:pyopensci/pyos-package-template dirname-here
The copier template will ask you a series of questions which you can respond to. The questions will help you customize the template.
If you use the minimal option in our template, the template questions will be short. This workflow creates the simplest version of a Python package including a tests\ directory and a docs\ directory using Sphinx.
➜ copier copy gh:pyopensci/pyos-package-template . 🎤 "Welcome to the pyOpenSci package template. Please select the type of template that you want to create today." >> MINIMAL: I want a minimal setup (package, tests and docs; typing); linting not included). FULL DEFAULT: I want to use the default settings but I want it setup for me. FULL CUSTOM: I want it all but I want to fully customize all template elements. 🎤 What is the name of the project? Used as the README.md title, in the pyospackage_juno 🎤 Please provide a short description for the package. (Finish with 'Alt+Enter' or 'Esc then Enter') > A great package that adds and subtracts numbers. 🎤 Who is the author of the package? Used in the package description. juno dawg 🎤 Provide you or your organization's GitHub username. Used to generate pyopensci Copying from template version 0.6.4.1 identical . create CODE_OF_CONDUCT.md create .gitignore create CHANGELOG.md create LICENSE create README.md create tests create tests/unit create tests/unit/test_example.py identical .editorconfig create .github create .github/workflows create .github/workflows/release.yml create .github/workflows/test.yml create .github/PULL_REQUEST_TEMPLATE.md create .github/ISSUE_TEMPLATE create .github/ISSUE_TEMPLATE/config.yml create .github/ISSUE_TEMPLATE/01-bug-report.yml create CONTRIBUTING.md create docs create docs/conf.py create docs/index.md create pyproject.toml create src create src/pyospackage_juno create src/pyospackage_juno/example.py create src/pyospackage_juno/__init__.pyOnce you have created your package, you can install it in editable mode using pip.
First, CD to the directory where your new package lives and install the package in editable mode:
$ cd my_directory $ conda activate myenv # activate your environment with your favorite environment manager $ pip install -e . # install your package in editable mode $ python # open up a python promptWe have included a small module in the package template in case you want to test drive that package in an environment before adding to it.
>>> from your_package import example # we have called the sample module, example.py >>> example.add_numbers(1,2) # this module has a simple function that adds two numbers 3 >>> quit() # exit the python prompt and return to your shellThe template has Hatch environments setup.
You can build your package using Hatch which is included in the template. First, make sure you have Hatch installed in your environment. Then, run hatch build.
$ hatch build ─────────────────── sdist ──────────────── dist/yourpackage-0.1.0.tar.gz ─────────────────── wheel ────────────────── dist/yourpackage-0.1.0-py2.py3-none-any.whlTo use the hatch build environment run:
hatch run build:check
This will create a new venv environment and build your package's wheel and source distributions.
If you want to fully customize your package, then the template workflow will look like the example below:
➜ copier copy gh:pyopensci/pyos-package-template . 🎤 Who is the copyright holder, for example, yourself or your organization? Used in the license pyos 🎤 Who is the author of the package to be? Used in the package description. pyos 🎤 The author's email address. Used in the package description. youremail@youremail.com 🎤 What is the name of the project? Used as the title in the README.md and other places. mypkg 🎤 Please provide a short description for the package. (Finish with 'Alt+Enter' or 'Esc then Enter') > description here 🎤 Do you want to skip all remaining questions and simply use the provided default values? No, I want to fully customize the template. 🎤 What is the project slug? Used in hyperlinks. mypkg 🎤 What is the Python package name? Used as the name of the package and the top-level import. mypkg 🎤 Do you want to use dynamic versioning of your package or static? Dynamic means that versions No 🎤 Do you want to use git with a development platform, like GitHub or GitLab? Yes 🎤 Which development platform are you planning to use? Used to generate certain documentation an GitHub 🎤 Your or your organization's username on GitHub. Used to generate certain documentation and hy pyopensci 🎤 Do you want to include documentation for your project and which framework do you want to use? Sphinx (https://www.pyopensci.org/pyos-sphinx-theme) 🎤 Do you want to use hatch environments for running isolated commands like linting, building do Yes 🎤 Do you want to lint your code and generally check the formatting of your files? Yes 🎤 Do you want to use typing annotations and type check your code? No 🎤 Do you want to test your code? Generally, we strongly recommend that you do, but for a quick Yes 🎤 Which license do you want to use? Used in the license file. MIT 🎤 What is the starting year of the project? Used in copyright statements. 2024The community will likely continue to develop this template. If at any point, you want to adopt those changes for your project, you can update it. Read more about that process in the copier documentation.
Thanks goes to these wonderful people (emoji key):
 Moritz E. Beber 💻 👀 🤔 |  Steven Silvester 💻 👀 🤔 |  Jonny Saunders 💻 👀 |  Jeremy Paige 💻 👀 |  Leah Wasser 💻 👀 |  Agriya Khetarpal 👀 |  Yuvi Panda 💻 👀 |
 Michael-Howes 🐛 |  Erik Whiting 💻 👀 |  Michael Pilosov, PhD 👀 |
This project follows the all-contributors specification. Contributions of any kind welcome!