boltons has a minimalist architecture: remain as consistent, and
self-contained as possible, with an eye toward maintaining its range
of use cases and usage patterns as wide as possible.
Utility libraries are often used extensively within a project, and because they are not often fundamental to the architecture of the application, simplicity and stability may take precedence over version recency. In these cases, developers can:
- Copy the whole
boltonspackage into a project.
- Copy just the
utils.pyfile that a project requires.
Boltons take this into account by design. The
depends on no packages, making it easy for inclusion into a
project. Furthermore, virtually all individual modules have been
written to be as self-contained as possible, allowing cherrypicking of
functionality into projects.
Design of a
boltons aims to be a living library, an ever-expanding collection
of tested and true utilities. For a bolton to be a bolton, it
- Be pure-Python and as self-contained as possible.
- Perform a common task or fulfill a common role.
- Demonstrate and mitigate some insufficiency in the standard library.
- Strive for the standard set forth by the standard library by striking a balance between best practice and “good enough”, correctness and common sense. When in doubt, ask, “what would the standard library do?”
- Have approachable documentation with at least one helpful
doctest, links to relevant standard library functionality, as well as any 3rd-party packages that provide further capabilities.
Finally, boltons should be substantial implementations of commonly trivialized stumbling blocks and not the other way around. The larger the problem solved, the less likely the functionality is suitable for inclusion in boltons; boltons are fundamental and self-contained, not sweeping and architecture-defining.
boltons has had a wide variety of inspirations over the years, but
a definite set of themes have emerged:
- From the Python docs:
- Reimplementations and tweaks of the standard library:
- One-off implementations discovered in multiple other libraries’
- More powerful multi-purpose data structures
- Personal practice and experience