mirror of https://github.com/mahmoud/boltons.git
139 lines
4.2 KiB
ReStructuredText
139 lines
4.2 KiB
ReStructuredText
.. boltons documentation master file, created on Sat Mar 21 00:34:18 2015.
|
|
boltons
|
|
=======
|
|
|
|
*boltons should be builtins.*
|
|
|
|
|release| |calver| |changelog|
|
|
|
|
**Boltons** is a set of pure-Python utilities in the same spirit as —
|
|
and yet conspicuously missing from — `the standard library`_,
|
|
including:
|
|
|
|
* :func:`Atomic file saving <boltons.fileutils.atomic_save>`, bolted on with
|
|
:mod:`~boltons.fileutils`
|
|
* A highly-optimized :class:`~boltons.dictutils.OrderedMultiDict`,
|
|
in :mod:`~boltons.dictutils`
|
|
* Two types of :class:`~boltons.queueutils.PriorityQueue`, in
|
|
:mod:`~boltons.queueutils`
|
|
* :func:`Chunked <boltons.iterutils.chunked>` and
|
|
:func:`windowed <boltons.iterutils.windowed>` iteration, in
|
|
:mod:`~boltons.iterutils`
|
|
* A full-featured :class:`~boltons.tbutils.TracebackInfo` type, for
|
|
representing stack traces, in :mod:`~boltons.tbutils`
|
|
* A lightweight :class:`UTC timezone <boltons.timeutils.UTC>`
|
|
available in :mod:`~boltons.timeutils`.
|
|
* Recursive mapping for nested data transforms, with :func:`remap
|
|
<boltons.iterutils.remap>`
|
|
|
|
And that's just a small selection. As of |today|, ``boltons`` is
|
|
|b_type_count| types and |b_func_count| functions, spread across
|
|
|b_mod_count| modules. See them all in the :ref:`genindex`, and see
|
|
what's new by `checking the CHANGELOG`_.
|
|
|
|
.. counts are appx 50, 75, and 23, respectively, as of initial docs writing
|
|
.. in mid 2016, the counts are now 62, 112, and 25, respectively
|
|
|
|
.. _the standard library: https://docs.python.org/3/library/index.html
|
|
.. _checking the CHANGELOG: https://github.com/mahmoud/boltons/blob/master/CHANGELOG.md
|
|
|
|
.. |release| image:: https://img.shields.io/pypi/v/boltons.svg
|
|
:target: https://pypi.python.org/pypi/boltons
|
|
|
|
.. |calver| image:: https://img.shields.io/badge/calver-YY.MINOR.MICRO-22bfda.svg
|
|
:target: http://calver.org
|
|
|
|
.. |changelog| image:: https://img.shields.io/badge/CHANGELOG-UPDATED-b84ad6.svg
|
|
:target: https://github.com/mahmoud/boltons/blob/master/CHANGELOG.md
|
|
|
|
Installation and Integration
|
|
----------------------------
|
|
|
|
Boltons can be added to a project in a few ways. There's the obvious one::
|
|
|
|
pip install boltons
|
|
|
|
On macOS, it can also be installed via `MacPorts`_::
|
|
|
|
sudo port install py-boltons
|
|
|
|
Then dozens of boltons are just an import away::
|
|
|
|
from boltons.cacheutils import LRU
|
|
lru_cache = LRU()
|
|
lru_cache['result'] = 'success'
|
|
|
|
Due to the nature of utilities, application developers might want to
|
|
consider other integration options. See the :ref:`Integration
|
|
<arch_integration>` section of the architecture document for more
|
|
details.
|
|
|
|
Boltons is tested against Python 3.7-3.12, as well as PyPy3.
|
|
|
|
.. _MacPorts: https://ports.macports.org/port/py-boltons/summary
|
|
|
|
Third-party packages
|
|
--------------------
|
|
|
|
The majority of boltons strive to be "good enough" for a wide range of
|
|
basic uses, leaving advanced use cases to Python's `myriad specialized
|
|
3rd-party libraries`_. In many cases the respective ``boltons`` module
|
|
will describe 3rd-party alternatives worth investigating when use
|
|
cases outgrow ``boltons``. If you've found a natural "next-step"
|
|
library worth mentioning, :ref:`consider filing an issue <Gaps>`!
|
|
|
|
.. _myriad specialized 3rd-party libraries: https://pypi.python.org/pypi
|
|
|
|
.. _gaps:
|
|
|
|
Gaps
|
|
----
|
|
|
|
Found something missing in the standard library that should be in
|
|
``boltons``? Found something missing in ``boltons``? First, take a
|
|
moment to read the very brief :doc:`architecture` statement to make
|
|
sure the functionality would be a good fit.
|
|
|
|
Then, if you are very motivated, submit `a Pull Request`_. Otherwise,
|
|
submit a short feature request on `the Issues page`_, and we will
|
|
figure something out.
|
|
|
|
.. _a Pull Request: https://github.com/mahmoud/boltons/pulls
|
|
.. _the Issues Page: https://github.com/mahmoud/boltons/issues
|
|
|
|
Section listing
|
|
---------------
|
|
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
|
|
architecture
|
|
cacheutils
|
|
debugutils
|
|
dictutils
|
|
ecoutils
|
|
fileutils
|
|
formatutils
|
|
funcutils
|
|
gcutils
|
|
ioutils
|
|
iterutils
|
|
jsonutils
|
|
listutils
|
|
mathutils
|
|
mboxutils
|
|
namedutils
|
|
pathutils
|
|
queueutils
|
|
setutils
|
|
socketutils
|
|
statsutils
|
|
strutils
|
|
tableutils
|
|
tbutils
|
|
timeutils
|
|
typeutils
|
|
urlutils
|
|
|
|
(For a quick reference you can ctrl-F, see the :ref:`genindex`.)
|