From ac480769fda99033a3652393be08ba5992b6596e Mon Sep 17 00:00:00 2001 From: Michal Nazarewicz Date: Sat, 5 May 2018 12:03:19 +0100 Subject: [PATCH] Require Sphinx 1.3 plus small fixes to docstrings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sphinx 1.3 has been released over three years ago so it shouldn’t be too much to ask for people (or machines) building the documentaion to have it. Since Napoleon is included in that version change the its extension name. While doing all that, fix some docstrings. Nothing major, just small typos and wording improvements. Fixes: https://github.com/google/pygtrie/issues/22 --- conf.py | 4 ++-- pygtrie.py | 45 ++++++++++++++++++++++++++------------------- version-history.rst | 6 +++--- 3 files changed, 31 insertions(+), 24 deletions(-) diff --git a/conf.py b/conf.py index 1e5c4e7..966c720 100644 --- a/conf.py +++ b/conf.py @@ -14,7 +14,7 @@ # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +needs_sphinx = '1.3' import os import sys @@ -24,7 +24,7 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', - 'sphinx.ext.viewcode', 'sphinxcontrib.napoleon'] + 'sphinx.ext.viewcode', 'sphinx.ext.napoleon'] # Add any paths that contain templates here, relative to this directory. templates_path = [] diff --git a/pygtrie.py b/pygtrie.py index 1c40a98..4b16b54 100644 --- a/pygtrie.py +++ b/pygtrie.py @@ -21,7 +21,8 @@ - A full mutable mapping implementation. -- Supports iterating over as well as deleting a subtrie. +- Supports iterating over as well as deleting of a branch of a trie + (i.e. subtrie) - Supports prefix checking as well as shortest and longest prefix look-up. @@ -32,7 +33,7 @@ - Can store any value including None. -For some simple examples see ``example.py`` file. +For a few simple examples see ``example.py`` file. """ __author__ = 'Michal Nazarewicz ' @@ -275,15 +276,15 @@ def __setstate__(self, state): class Trie(_collections.MutableMapping): """A trie implementation with dict interface plus some extensions. - Keys used with the :class:`pygtrie.Trie` must be iterable, yielding hashable - objects. In other words, for a given key, ``dict.fromkeys(key)`` must be - valid. + Keys used with the :class:`pygtrie.Trie` class must be iterable which each + component being a hashable objects. In other words, for a given key, + ``dict.fromkeys(key)`` must be valid expression. - In particular, strings work fine as trie keys, however when getting keys - back from iterkeys() method for example, instead of strings, tuples of - characters are produced. For that reason, :class:`pygtrie.CharTrie` or - :class:`pygtrie.StringTrie` may be preferred when using - :class:`pygtrie.Trie` with string keys. + In particular, strings work well as trie keys, however when getting them + back (for example via :func:`Trie.iterkeys` method), instead of strings, + tuples of characters are produced. For that reason, + :class:`pygtrie.CharTrie` or :class:`pygtrie.StringTrie` classes may be + preferred when using string keys. """ def __init__(self, *args, **kwargs): @@ -429,7 +430,7 @@ def iteritems(self, prefix=_SENTINEL, shallow=False): unspecified by default. In other words, in the above example, the ``('qux', 'Qux')`` pair might have been at the end of the list. At an expense of efficiency, this can be changed via - :func:`Trie.enable_sorting`. + :func:`Trie.enable_sorting` method. With ``prefix`` argument, only items with specified prefix are generated (i.e. only given subtrie is traversed) as demonstrated by:: @@ -561,7 +562,7 @@ def has_node(self, key): True There are two higher level methods built on top of this one which give - easier interface for the information. :func:`Trie.has_key` and returns + easier interface for the information. :func:`Trie.has_key` returns whether node has a value associated with it and :func:`Trie.has_subtrie` checks whether node is a prefix. Continuing previous example:: @@ -850,7 +851,7 @@ def __delitem__(self, key_or_slice): Raises: ShortKeyError: If the key has no value associated with it but is - a prefix of some key with a value. This is not thrown is + a prefix of some key with a value. This is not thrown if key_or_slice is a slice -- in such cases, the whole subtrie is removed. Note that :class:`ShortKeyError` is subclass of :class:`KeyError`. @@ -1172,10 +1173,10 @@ def traverse(self, node_factory, prefix=_SENTINEL): consequences: * To traverse into node's children, the generator must be iterated over. - This can by accomplished by a simple "children = list(children)" + This can by accomplished by a simple ``children = list(children)`` statement. * Ignoring the argument allows node_factory to stop the traversal from - going into the children of the node. In other words, whole subtrie + going into the children of the node. In other words, whole subtries can be removed from traversal if node_factory chooses so. * If children is stored as is (i.e. as a generator) when it is iterated over later on it will see state of the trie as it is during the @@ -1258,11 +1259,13 @@ def traverse_callback(path_conv, path, children, is_file=False): prone to rising a RuntimeError exception when Python's maximum recursion depth is reached. This can be addressed by not iterating over children inside of the node_factory. For example, the below code converts a trie - into an undirected graph using adjacency list representation: + into an undirected graph using adjacency list representation:: def undirected_graph_from_trie(t): '''Converts trie into a graph and returns its nodes.''' + Node = collections.namedtuple('Node', 'path neighbours') + class Builder(object): def __init__(self, path_conv, path, children, _=None): self.node = Node(path_conv(path), []) @@ -1306,8 +1309,8 @@ class CharTrie(Trie): The only difference between :class:`pygtrie.CharTrie` and :class:`pygtrie.Trie` is that when :class:`pygtrie.CharTrie` returns keys - back to the client (for instance in keys() method is called), those keys are - returned as strings. + back to the client (for instance when :func:`Trie.keys` method is called), + those keys are returned as strings. Canonical example where this class can be used is a dictionary of words in a natural language. For example:: @@ -1336,7 +1339,8 @@ class StringTrie(Trie): """:class:`pygtrie.Trie` variant accepting strings with a separator as keys. The trie accepts strings as keys which are split into components using - a separator specified during initialisation ("/" by default). + a separator specified during initialisation (forward slash,i.e. ``/``, by + default). Canonical example where this class can be used is when keys are paths. For example, it could map from a path to a request handler:: @@ -1509,13 +1513,16 @@ def add(self, key): self._trie[key:] = True def discard(self, key): + """Raises NotImplementedError.""" raise NotImplementedError( 'Removing keys from PrefixSet is not implemented.') def remove(self, key): + """Raises NotImplementedError.""" raise NotImplementedError( 'Removing keys from PrefixSet is not implemented.') def pop(self): + """Raises NotImplementedError.""" raise NotImplementedError( 'Removing keys from PrefixSet is not implemented.') diff --git a/version-history.rst b/version-history.rst index 2ce1750..a00eb89 100644 --- a/version-history.rst +++ b/version-history.rst @@ -3,8 +3,8 @@ Version History 2.2: 2017/06/03 -- Fixes to setup.py breaking on Windows which prevents installation - among other things. +- Fixes to ``setup.py`` breaking on Windows which prevents + installation among other things. 2.1: 2017/03/23 @@ -12,7 +12,7 @@ Version History - Value returend by ``shortest_prefix`` and ``longest_prefix`` evaluates to false if no prefix was found. This is in addition to it being - a pair of Nones of course. + a pair of ``None``s of course. 2.0: 2016/07/06