From 037b10a42fcc9d1e42f6b191b85198812a7fa7e3 Mon Sep 17 00:00:00 2001 From: James Bourbeau Date: Fri, 4 Oct 2024 11:11:35 -0500 Subject: [PATCH] Update docs (#590) --- .readthedocs.yaml | 17 +++++++++++++++++ doc/requirements.txt | 2 ++ doc/source/conf.py | 4 ++-- doc/source/heritage.rst | 32 ++++++++++++++------------------ doc/source/install.rst | 2 +- doc/source/laziness.rst | 9 ++++----- toolz/itertoolz.py | 1 + toolz/sandbox/parallel.py | 8 ++++++++ 8 files changed, 49 insertions(+), 26 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 doc/requirements.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..32966c8c --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,17 @@ +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +version: 2 +build: + os: ubuntu-22.04 + tools: + python: "3.12" + +sphinx: + configuration: doc/source/conf.py + # Temporarily turning off to get docs build passing + # fail_on_warning: true + +python: + install: + - requirements: doc/requirements.txt + - method: pip + path: . \ No newline at end of file diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 00000000..27fedc44 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,2 @@ +sphinx +furo \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index 4063f01b..8acbf3af 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -93,7 +93,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +html_theme = 'furo' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -105,7 +105,7 @@ # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +html_title = "Toolz" # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None diff --git a/doc/source/heritage.rst b/doc/source/heritage.rst index f2fc587a..e12636d6 100644 --- a/doc/source/heritage.rst +++ b/doc/source/heritage.rst @@ -2,13 +2,13 @@ Heritage ======== While Python was originally intended as an imperative language -[Guido_], it contains all elements necessary to support a rich set of features +[`Guido`_], it contains all elements necessary to support a rich set of features from the functional paradigm. In particular its core data structures, lazy iterators, and functions as first class objects can be combined to implement a common standard library of functions shared among many functional languages. This was first recognized and supported through the standard libraries -itertools_ and functools_ which contain functions like ``permutations``, +itertools_ and `functools`_ which contain functions like ``permutations``, ``chain`` and ``partial`` to complement the standard ``map``, ``filter``, ``reduce`` already found in the core language. While these libraries contain substantial functionality they do not achieve the same level of adoption found @@ -17,15 +17,15 @@ incomplete and lack a number of commonly related functions like ``compose`` and ``groupby`` which often complement these core operations. A completion of this set of functions was first attempted in the projects -itertoolz_ and functoolz_ (note the z). These libraries contained -several functions that were absent in the standard itertools_/functools_ +`itertoolz`_ and `functoolz`_ (note the z). These libraries contained +several functions that were absent in the standard itertools_ / `functools`_ libraries. The ``itertoolz``/``functoolz`` libraries were eventually merged into the monolithic ``toolz`` project described here. Most contemporary functional languages (Haskell, Scala, Clojure, ...) contain some variation of the functions found in ``toolz``. The ``toolz`` project generally adheres closely to the API found in the Clojure standard library (see -cheatsheet_) and where disagreements occur that API usually dominates. The +`cheatsheet`_) and where disagreements occur that API usually dominates. The ``toolz`` API is also strongly affected by the principles of the Python language itself, and often makes deviations in order to be more approachable to that community. @@ -33,19 +33,15 @@ that community. The development of a functional standard library within a popular imperative language is not unique. Similar projects have arisen in other imperative-by-design languages that contain the necessary elements to support a -functional standard library. Underscore.js_ in JavaScript has attained +functional standard library. `Underscore.js `_ in JavaScript has attained notable popularity in the web community. ``LINQ`` in C# follows a similar philosophy but mimics declarative database languages rather than functional -ones. Enumerable_ is is the closest project in Ruby. Other excellent projects -also exist within the Python ecosystem, most notably Fn.py_ and Funcy_. +ones. `Enumerable `_ is is the closest project in Ruby. Other excellent projects +also exist within the Python ecosystem, most notably `Fn.py `_ and `Funcy `_. -.. [itertools] https://docs.python.org/2/library/itertools.html -.. [functools] https://docs.python.org/2/library/functools.html -.. [itertoolz] https://github.com/mrocklin/itertoolz -.. [functoolz] https://github.com/mrocklin/functoolz -.. [Underscore.js] https://underscorejs.org -.. [cheatsheet] https://clojure.org/cheatsheet -.. [Guido] https://python-history.blogspot.com/2009/04/origins-of-pythons-functional-features.html -.. [Enumerable] https://ruby-doc.org/core-2.0.0/Enumerable.html -.. [funcy] https://github.com/suor/funcy/ -.. [fn.py] https://github.com/kachayev/fn.py +.. _itertools: https://docs.python.org/library/itertools.html +.. _functools: https://docs.python.org/library/functools.html +.. _itertoolz: https://github.com/mrocklin/itertoolz +.. _functoolz: https://github.com/mrocklin/functoolz +.. _cheatsheet: https://clojure.org/cheatsheet +.. _Guido: https://python-history.blogspot.com/2009/04/origins-of-pythons-functional-features.html diff --git a/doc/source/install.rst b/doc/source/install.rst index 6ed2a5c8..faed7ad7 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -11,4 +11,4 @@ three ways: 1. Toolz is pure Python 2. Toolz relies only on the standard library -3. Toolz simultaneously supports Python versions 3.5+ and PyPy +3. Toolz simultaneously supports Python versions 3.8+ and PyPy diff --git a/doc/source/laziness.rst b/doc/source/laziness.rst index 73d4da57..c32ad609 100644 --- a/doc/source/laziness.rst +++ b/doc/source/laziness.rst @@ -9,8 +9,9 @@ memory. They act like lists but don't take up space. Example - A Tale of Two Cities ------------------------------ -We open a file containing the text of the classic text "A Tale of Two Cities" -by Charles Dickens[1_]. +We open `a file `_ containing +the text of the classic text "A Tale of Two Cities" +by Charles Dickens. .. code:: @@ -98,6 +99,4 @@ In this case ``frequencies`` is a sort of reduction. At no time were more than a few hundred bytes of Tale of Two Cities necessarily in memory. We could just have easily done this computation on the entire Gutenberg collection or on Wikipedia. In this case we are limited by the size and speed of our hard drive -and not by the capacity of our memory. - -.. [1] http://www.gutenberg.org/cache/epub/98/pg98.txt +and not by the capacity of our memory. \ No newline at end of file diff --git a/toolz/itertoolz.py b/toolz/itertoolz.py index 634f4869..1ab54851 100644 --- a/toolz/itertoolz.py +++ b/toolz/itertoolz.py @@ -817,6 +817,7 @@ def join(leftkey, leftseq, rightkey, rightseq, This is a semi-streaming operation. The LEFT sequence is fully evaluated and placed into memory. The RIGHT sequence is evaluated lazily and so can be arbitrarily large. + (Note: If right_default is defined, then unique keys of rightseq will also be stored in memory.) diff --git a/toolz/sandbox/parallel.py b/toolz/sandbox/parallel.py index 114077d2..e47a1240 100644 --- a/toolz/sandbox/parallel.py +++ b/toolz/sandbox/parallel.py @@ -14,10 +14,18 @@ def fold(binop, seq, default=no_default, map=map, chunksize=128, combine=None): """ Reduce without guarantee of ordered reduction. + Parameters + ---------- + binops + Associative operator. The associative property allows us to + leverage a parallel map to perform reductions in parallel. + + inputs: ``binop`` - associative operator. The associative property allows us to leverage a parallel map to perform reductions in parallel. + ``seq`` - a sequence to be aggregated ``default`` - an identity element like 0 for ``add`` or 1 for mul