From b801d2d762810bdb401439ff7f6db38bbefc4ff5 Mon Sep 17 00:00:00 2001 From: Mahmoud Hashemi Date: Mon, 6 Apr 2015 02:36:58 -0700 Subject: [PATCH] WIP index.rst refresh --- docs/index.rst | 79 ++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 57 insertions(+), 22 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 20db769..0cd922b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,38 +1,72 @@ .. boltons documentation master file, created on Sat Mar 21 00:34:18 2015. - - boltons ======= *boltons should be builtins.* **Boltons** is a set of pure-Python utilities in the same spirit as -the Python builtins, and yet somehow not present in the standard -library. A few examples include: +the Python builtins, and yet somehow not present in `the standard +library`_. A few examples include: -* Atomic file saving, bolted on with fileutils -* A highly-optimized ``OrderedMultiDict``, in dictutils -* Two types of ``PriorityQueue``, in queueutils -* "Chunked" and "windowed" iteration, among many others, in iterutils -* A full-featured ``TracebackInfo`` type, for representing stack traces, in tbutils + * Atomic file saving, bolted on with :mod:`fileutils` + * A highly-optimized :class:`OrderedMultiDict`, in :mod:`dictutils` + * Two types of ``PriorityQueue``, in :mod:`queueutils` + * "Chunked" and "windowed" iteration, among many others, in :mod:`iterutils` + * A full-featured ``TracebackInfo`` type, for representing stack + traces, in :mod:`tbutils` -Usage ------ +.. _the standard library: https://docs.python.org/2.7/library/index.html -Boltons can be used in a couple ways. +Installation and Integration +---------------------------- -1. Install the boltons package using ``pip`` or ``easy_install``. -2. Copy the whole boltons package into your project. -3. Copy just the ``utils.py`` module that your package needs. +Boltons can be added to a project in a few ways. There's the obvious one:: -The boltons package depends on no packages, making it easy for -inclusion into a project. Furthermore, most individual modules have + pip install boltons + +Then just import away:: + + from boltons.cacheutils import LRU + my_cache = LRU() + +However, because of the nature of utilities, application developers +might want to consider: + + 1. Copying the whole ``boltons`` package into your project. + 2. Copying just the ``utils.py`` file that your package requires. + +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. Boltons take this into account by design. + +Design of a ``bolton`` +---------------------- + +``boltons`` aims to be a living library, an ever-expanding collection +of tested and true utilities. For a ``bolton`` to be a ``bolton``, it +should: + + 1. Be pure-Python and as self-contained as possible. + 2. Perform a common task or fulfill a common role. + 3. Demonstrate and mitigate some insufficiency in the standard library. + 4. Strive for the standard set forth by the standard library by + striking a balance between best practice and "good enough", + correctness and common sense. + +The ``boltons`` package 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. Utility libraries are -often used extensively within a project, and because they are not -often fundamental to the architecture of the application, stability -may take precedence over version recency. +cherrypicking of functionality into projects. +Themes of ``boltons`` +--------------------- + +1. From the docs (queueutils, iterutils, tzutils) +2. Standard lib reimpl (fileutils.copytree, namedutils.namedtuple) +3. One-off implementations discovered in other libs utils.py or equivalent (strutils.slugify, bytes2human, relative time) +4. More powerful multi-purpose data structures (OMD, IndexedSet, BList, namedlist, Table) +5. Personal practice (debugutils, gcutils, tbutils) Third-party packages -------------------- @@ -50,7 +84,8 @@ Found something missing in boltons? If you are very motivated, submit a Pull Request. Otherwise, submit a feature request on the Issues page, and we will figure something out. -Contents: +Section listing +--------------- .. toctree:: :maxdepth: 2