Need content on "How to create a good Python package"

[kmpaul]

Per our discussion in today's IWG meeting, I'm creating this issue as a placeholder for future work. I think that one of the Initial Content items that was neglected when discussing "Foundational Material" was the idea of how to build a "good" Python package. That would include:

• CI services like GitHub Action (for testing, linting, etc.) and ReadTheDocs (for building and hosting documentation)
• Good package structure (i.e., the structure of the files and folders in the repository)
• Using pre-commit hooks and other enforcing tools (including various pre-commit checks like black/prettier, flake8, isort, talisman, etc.)

Anything else I'm missing?

[brian-rose]

I would add basic instructions for setting up tests (pytest or other), which is needed before using a CI service.

[brian-rose]

This package from @jbusecke could be a very useful starting point:
https://github.com/jbusecke/cookiecutter-science-project

[jbusecke]

I would add basic instructions for setting up tests (pytest or other), which is needed before using a CI service.

I think this the single most important thing to emphasize in order to build good python code. Definite +1 for an intro to testing!

I would also add a simple primer on git maybe?

Also thanks for the shoutout @brian-rose.

I have been treating the cookie-cutter template both as a template and a (admittedly unorganized) collection of my personal 'best practices', if that is of interest I could migrate some of that here? The idea behind the template was to have both something that 'just works out of the box' and also detailed explanations how to set these things up manually. But this (amazing) project seems like a better home for such instructions? Happy to add to existing material if you think that would be helpful.

[brian-rose]

This issue has languished for a while.

My feeling is that this type of material belongs in the Foundations book, perhaps in a new top-level section called "Building Python Packages".

I'll open a new issue over at https://github.com/ProjectPythia/pythia-foundations and perhaps bring this up at the next Pythia EWG meeting.

[andersy005]

I would add basic instructions for setting up tests (pytest or other), which is needed before using a CI service.

This package from @jbusecke could be a very useful starting point:
jbusecke/cookiecutter-science-project

@jacobtomlinson has put together a really nice and well detailed blog post series on this topic: https://jacobtomlinson.dev/series/creating-an-open-source-python-project-from-scratch/. I think the contents from this blog post series in conjunction with Julius's template could result in great material.

[jacobtomlinson]

Thanks for the mention here @andersy005. Hopefully, the series will be useful to this group. I still have a few more posts in the pipeline, but the bulk of it is there.