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 tutorial.
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.
pyos-package-template (☊ minimal) [🏎️ 💨 ×6] via 🐍 v3.12.5 (test.py3.12)
➜ copier copy . _law_tests --vcs-ref minimal
🎤 Who is the copyright holder, for example, yourself or your organization? Used in the license file and project description.
Your Name
🎤 Who is the author of the package to be? Used in the package description.
Your Name
🎤 The author's email address. Used in the package description.
[email protected]
🎤 What is the name of the project? Used as the title in the README.md and other places.
project_name
🎤 Please provide a short description for the package.
(Finish with 'Alt+Enter' or 'Esc then Enter')
> An example Python package with a minimal setup.
🎤 Do you want to skip all remaining questions and use the default values?
>> Yes, but with a minimal setup (package, tests and docs only).
Copying from template version 0.6.1.post44.dev0+7863796
create CODE_OF_CONDUCT.md
create CHANGELOG.md
create CONTRIBUTING.md
create LICENSE
create README.md
create tests
create tests/unit
create tests/unit/.keep
create tests/integration
create tests/integration/.keep
create tests/system
create tests/system/test_import.py
create tests/system/.keep
identical .editorconfig
identical .gitignore
create docs
create docs/conf.py
create docs/index.md
create pyproject.toml
create src
create src/pyopensci
create src/pyopensci/example.py
create src/pyopensci/__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 in case you want to test it out.
>>> 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 shellYou 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.whlIf 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.
[email protected]
🎤 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 💻 👀 |
This project follows the all-contributors specification. Contributions of any kind welcome!