Python on Rails

2019 May 13

Over the past couple of weeks, I've worked on building a Python project template and a Yeoman generator that creates that template.[1] There was already at least one popular template, and it links to a few more, but I know there are countless others, and I've not looked at them all. I went ahead and added my own to the pile to fill a gap that I feel is left by the ones I've seen.

I want a project template that is focused on supporting what I consider to be the 90% use case: an all-Python library or tool that you want to share with yourself or others in the Python Package Index (PyPI). The template should

  • be approachable to beginners. Every piece that goes into it should be well-documented to the point a new user can get up and running quickly, knowing at least as much as they need to know without bogging them down in details. If a piece is included that a user doesn't understand or want, they should be able to easily remove it, and the documentation should help them figure out how.

  • be lean, or in other words, minimize (and ideally eliminate) the number and size of configuration files. A good start is to use the to-be-standardized-in-PEP-518 project metadata file pyproject.toml, which stands to replace a growing set of redundant, confusing, non-standard configuration files like, requirements.txt, setup.cfg,, and Pipfile. The next step is to prefer convention over configuration, a philosophy with roots in Ruby on Rails, from which this post takes its title. Finally, the template shouldn't be cluttered with support for advanced or uncommon use cases (like C extensions).

  • be truly cross-platform, working equally well on the Big Three platforms: Windows, Linux, and OSX. For production, that means the included continuous integration should test on all of them. For development, it means replacing a Makefile with an Invokefile.

These are the qualities that I think set my template apart from the rest. In addition, it shares a few qualities that people have come to expect from templates. It tries to follow best practices, especially for project structure, and to ease development with tools and included scripts, making it easy to

  • add or remove dependencies
  • run tests, style checkers, and static analyzers
  • build and publish documentation
  • package and publish to PyPI

Please try it out and let me know what you think! Leave a comment or file an issue, and I'll try to answer. All feedback is welcome; it will help me improve the project and its documentation.


  1. Why Yeoman instead of Cookiecutter? I explain why in another post. ↩︎