README.rst
1Toolz
2=====
3
4|Build Status| |Coverage Status| |Version Status|
5
6A set of utility functions for iterators, functions, and dictionaries.
7
8See the PyToolz documentation at https://toolz.readthedocs.io
9
10LICENSE
11-------
12
13New BSD. See `License File <https://github.com/pytoolz/toolz/blob/master/LICENSE.txt>`__.
14
15Install
16-------
17
18``toolz`` is on the Python Package Index (PyPI):
19
20::
21
22 pip install toolz
23
24Structure and Heritage
25----------------------
26
27``toolz`` is implemented in three parts:
28
29|literal itertoolz|_, for operations on iterables. Examples: ``groupby``,
30``unique``, ``interpose``,
31
32|literal functoolz|_, for higher-order functions. Examples: ``memoize``,
33``curry``, ``compose``,
34
35|literal dicttoolz|_, for operations on dictionaries. Examples: ``assoc``,
36``update-in``, ``merge``.
37
38.. |literal itertoolz| replace:: ``itertoolz``
39.. _literal itertoolz: https://github.com/pytoolz/toolz/blob/master/toolz/itertoolz.py
40
41.. |literal functoolz| replace:: ``functoolz``
42.. _literal functoolz: https://github.com/pytoolz/toolz/blob/master/toolz/functoolz.py
43
44.. |literal dicttoolz| replace:: ``dicttoolz``
45.. _literal dicttoolz: https://github.com/pytoolz/toolz/blob/master/toolz/dicttoolz.py
46
47These functions come from the legacy of functional languages for list
48processing. They interoperate well to accomplish common complex tasks.
49
50Read our `API
51Documentation <https://toolz.readthedocs.io/en/latest/api.html>`__ for
52more details.
53
54Example
55-------
56
57This builds a standard wordcount function from pieces within ``toolz``:
58
59.. code:: python
60
61 >>> def stem(word):
62 ... """ Stem word to primitive form """
63 ... return word.lower().rstrip(",.!:;'-\"").lstrip("'\"")
64
65 >>> from toolz import compose, frequencies
66 >>> from toolz.curried import map
67 >>> wordcount = compose(frequencies, map(stem), str.split)
68
69 >>> sentence = "This cat jumped over this other cat!"
70 >>> wordcount(sentence)
71 {'this': 2, 'cat': 2, 'jumped': 1, 'over': 1, 'other': 1}
72
73Dependencies
74------------
75
76``toolz`` supports Python 3.5+ with a common codebase.
77It is pure Python and requires no dependencies beyond the standard
78library.
79
80It is, in short, a lightweight dependency.
81
82
83CyToolz
84-------
85
86The ``toolz`` project has been reimplemented in `Cython <http://cython.org>`__.
87The ``cytoolz`` project is a drop-in replacement for the Pure Python
88implementation.
89See `CyToolz GitHub Page <https://github.com/pytoolz/cytoolz/>`__ for more
90details.
91
92See Also
93--------
94
95- `Underscore.js <https://underscorejs.org/>`__: A similar library for
96 JavaScript
97- `Enumerable <https://ruby-doc.org/core-2.0.0/Enumerable.html>`__: A
98 similar library for Ruby
99- `Clojure <https://clojure.org/>`__: A functional language whose
100 standard library has several counterparts in ``toolz``
101- `itertools <https://docs.python.org/2/library/itertools.html>`__: The
102 Python standard library for iterator tools
103- `functools <https://docs.python.org/2/library/functools.html>`__: The
104 Python standard library for function tools
105
106Contributions Welcome
107---------------------
108
109``toolz`` aims to be a repository for utility functions, particularly
110those that come from the functional programming and list processing
111traditions. We welcome contributions that fall within this scope.
112
113We also try to keep the API small to keep ``toolz`` manageable. The ideal
114contribution is significantly different from existing functions and has
115precedent in a few other functional systems.
116
117Please take a look at our
118`issue page <https://github.com/pytoolz/toolz/issues>`__
119for contribution ideas.
120
121Community
122---------
123
124See our `mailing list <https://groups.google.com/forum/#!forum/pytoolz>`__.
125We're friendly.
126
127.. |Build Status| image:: https://github.com/pytoolz/toolz/workflows/Test/badge.svg
128 :target: https://github.com/pytoolz/toolz/actions
129.. |Coverage Status| image:: https://coveralls.io/repos/pytoolz/toolz/badge.svg?branch=master
130 :target: https://coveralls.io/r/pytoolz/toolz
131.. |Version Status| image:: https://badge.fury.io/py/toolz.svg
132 :target: https://badge.fury.io/py/toolz
133
