astrojuanlu / cookiecutter-pylib

cookiecutter template for pure Python libraries. As simple as possible. No magic.

cookiecutter-pylib

This project is archived, use https://github.com/astrojuanlu/copier-pylib instead

Cookiecutter template for pure Python libraries.

As simple as possible. No magic.

Features

• flit for simple packaging.
• pytest for testing.
• tox for automation of test runners and other stuff.
• Sphinx for documentation
• GitHub Actions for continuous integration and publishing to PyPI.
• Read the Docs for continuous documentation.
• mypy for type checks.
• black for automatic Python code formatting.
• flake8, isort and pydocstyle for style checks.
• pre-commit for optional automation of style checks.

Usage

Install cookiecutter:

pip install cookiecutter

Generate a Python package:

cookiecutter gh:astrojuanlu/cookiecutter-pylib

License

MIT License

cookiecutter-pylib's Issues

pyproject description updates

Still trying to figure out how everything works and fits together, but here is what I have found so far. This was originally triggered by looking into arviz-devs/xarray-einstats#18, but it is not necessarily related, to try and fix this I ended up doing some workarounds that are far from ideal but ti seems they will be necessary for the time being.

The pyproject.toml template currently lists two dynamic fields:

cookiecutter-pylib/{{cookiecutter.project_name}}/pyproject.toml

Line 24 in 3a7b112

dynamic = ["version", "description"]

From what I understood, this means that they are not defined in the pyproject file itself but should instead be retrieved dynamically by the build library during the install process. flit seems to then magically take the correct version for the package and a short description. The version thing works great, but the short description does not. What ends up being used as short description is the first line of the __init__.py package level docstring:

cookiecutter-pylib/{{cookiecutter.project_name}}/src/{{cookiecutter.package_name}}/__init__.py

Lines 1 to 5 in 3a7b112

	"""
	{{ cookiecutter.project_name }}
	{{ cookiecutter.short_description }}
	"""

that means that with the current config, the package name is repeated as short description instead of using the actual short description. This can be seen in https://pypi.org/project/xarray-einstats/ for example:

xarray-einstats. is used as short description (side note, since pydocstyle was added to tox checks, I think line two needs to end with a dot for a clean generated project to pass the checks). This can be fixed by updating the docstring template in init.py or by making the description be a static field, I am not sure it is worth it to have description as a dynamic field using the first line of the dosctring as it is still hardcoded in the readme.

I can submit a PR for either of the two options. Let me know which one do you prefer or if you think a 3rd option would be better.

Add explicti typing and _static directory

Thank you @astrojuanlu for this cookiecutter template!

I noticed that if the tox command is executed from a clean/raw download it outputs some "errors" regarding mypy and the undefined _static directory inside docs/source. These "bugs" might be fixed by including:

# File: conf.py
from typing import List
extensions: List[str] = []
exclude_patterns: List[str] = [] 

Regarding the _static/ folder, what about a .gitkeep?

Relases with release-notary?

https://github.com/aevea/release-notary

Versioning with miniver?

https://github.com/jbweston/miniver

More opinionated choices on docs?

I used the template to create https://github.com/arviz-devs/xarray-einstats and it has made my job much much easier and more enjoyable, thank you so much. I have basically done only minor changes to the infrastructure build by the template in all areas except on doc related things. I know I am way more opinionated on those than I am on everything else, but there are still some things that I think could benefit everyone, not only doc focused people like me:

• Importing the project in conf.py for autosummary and autodoc to work
• Add some common things like "Thumbs.db", ".DS_Store", ".ipynb_checkpoints" to exclude_patterns
• Adding sphinx-copybutton to extensions.
• Adding pydocstyle to tox- e check

Let me know what you think, I'd be happy to send a PR for some or all of these.

Explore copier

In my current job we're using cookiecutter a lot but I'm sad to see it's not maintained anymore, and I'm looking into Copier: https://github.com/copier-org/copier

Apparently it solves some of the pain points of cookiecutter, for example the ability to update a project with respect to a given template, and one minor thing: being able to start a project in the current directory (rather than a subdirectory).

@OriolAbril have you ever heard of this?

Update for PEP 621

https://www.python.org/dev/peps/pep-0621/

To note: https://discuss.python.org/t/module-vs-dist-name-in-pep-621/9264/10