From 816207bb5a8d89a340a2266f090cb2bdfd6aceb2 Mon Sep 17 00:00:00 2001 From: Ben Kurtovic Date: Tue, 21 Aug 2012 23:15:30 -0400 Subject: [PATCH] Simplify docs massively. --- docs/api/mwparserfromhell.nodes.rst | 1 + mwparserfromhell/__init__.py | 2 +- mwparserfromhell/nodes/__init__.py | 32 ++++---- mwparserfromhell/nodes/extras/__init__.py | 4 +- mwparserfromhell/nodes/extras/attribute.py | 10 +-- mwparserfromhell/nodes/extras/parameter.py | 4 +- mwparserfromhell/nodes/heading.py | 2 +- mwparserfromhell/nodes/tag.py | 7 +- mwparserfromhell/nodes/template.py | 27 +++---- mwparserfromhell/parser/__init__.py | 16 ++-- mwparserfromhell/parser/builder.py | 7 +- mwparserfromhell/parser/tokenizer.py | 2 +- mwparserfromhell/parser/tokens.py | 6 +- mwparserfromhell/smart_list.py | 26 +++--- mwparserfromhell/string_mixin.py | 10 +-- mwparserfromhell/utils.py | 14 ++-- mwparserfromhell/wikicode.py | 123 +++++++++++++---------------- 17 files changed, 129 insertions(+), 164 deletions(-) diff --git a/docs/api/mwparserfromhell.nodes.rst b/docs/api/mwparserfromhell.nodes.rst index 4f43021..6bd175f 100644 --- a/docs/api/mwparserfromhell.nodes.rst +++ b/docs/api/mwparserfromhell.nodes.rst @@ -7,6 +7,7 @@ nodes Package .. automodule:: mwparserfromhell.nodes .. autoclass:: mwparserfromhell.nodes.Node + :special-members: :mod:`heading` Module --------------------- diff --git a/mwparserfromhell/__init__.py b/mwparserfromhell/__init__.py index 90d06a7..58b57c6 100644 --- a/mwparserfromhell/__init__.py +++ b/mwparserfromhell/__init__.py @@ -37,4 +37,4 @@ __email__ = "ben.kurtovic@verizon.net" from . import nodes, parser, smart_list, string_mixin, wikicode parse = lambda text: parser.Parser(text).parse() -parse.__doc__ = "Short for ``mwparserfromhell.parser.Parser(text).parse()``." +parse.__doc__ = "Short for :py:meth:`.Parser.parse`." diff --git a/mwparserfromhell/nodes/__init__.py b/mwparserfromhell/nodes/__init__.py index b5f45a1..f066c0e 100644 --- a/mwparserfromhell/nodes/__init__.py +++ b/mwparserfromhell/nodes/__init__.py @@ -21,14 +21,12 @@ # SOFTWARE. """ -This package contains :py:class:`~mwparserfromhell.wikicode.Wikicode` "nodes", -which represent a single unit of wikitext, such as a Template, an HTML tag, -a Heading, or plain text. The node "tree" is far from flat, as most types can -contain additional :py:class:`~mwparserfromhell.wikicode.Wikicode` types within -them - and with that, more nodes. For example, the name of a -:py:class:`~mwparserfromhell.nodes.template.Template` is a -:py:class:`~mwparserfromhell.wikicode.Wikicode` object that can contain text or -more templates. +This package contains :py:class:`~.Wikicode` "nodes", which represent a single +unit of wikitext, such as a Template, an HTML tag, a Heading, or plain text. +The node "tree" is far from flat, as most types can contain additional +:py:class:`~.Wikicode` types within them - and with that, more nodes. For +example, the name of a :py:class:`~.Template` is a :py:class:`~.Wikicode` +object that can contain text or more templates. """ from __future__ import unicode_literals @@ -43,15 +41,15 @@ class Node(StringMixIn): :py:meth:`__unicode__` must be overridden. It should return a ``unicode`` or (``str`` in py3k) representation of the node. If the node contains - :py:class:`~mwparserfromhell.wikicode.Wikicode` objects inside of it, - :py:meth:`__iternodes__` should be overridden to yield tuples of - (``wikicode``, ``node_in_wikicode``) for each node in each wikicode, as - well as the node itself (``None``, ``self``). If the node is printable, - :py:meth:`__strip__` should be overridden to return the printable version - of the node - it does not have to be a string, but something that can be - converted to a string with ``str()``. Finally, :py:meth:`__showtree__` can - be overridden to build a nice tree representation of the node, if desired, - for :py:meth:`~mwparserfromhell.wikicode.Wikicode.get_tree`. + :py:class:`~.Wikicode` objects inside of it, :py:meth:`__iternodes__` + should be overridden to yield tuples of (``wikicode``, + ``node_in_wikicode``) for each node in each wikicode, as well as the node + itself (``None``, ``self``). If the node is printable, :py:meth:`__strip__` + should be overridden to return the printable version of the node - it does + not have to be a string, but something that can be converted to a string + with ``str()``. Finally, :py:meth:`__showtree__` can be overridden to build + a nice tree representation of the node, if desired, for + :py:meth:`~.Wikicode.get_tree`. """ def __unicode__(self): raise NotImplementedError() diff --git a/mwparserfromhell/nodes/extras/__init__.py b/mwparserfromhell/nodes/extras/__init__.py index 2f165d1..2ce4bb1 100644 --- a/mwparserfromhell/nodes/extras/__init__.py +++ b/mwparserfromhell/nodes/extras/__init__.py @@ -22,8 +22,8 @@ """ This package contains objects used by -:py:class:`~mwparserfromhell.nodes.Node`\ s, but are not nodes themselves. -This includes the parameters of Templates or the attributes of HTML tags. +:py:class:`~.Node`\ s, but are not nodes themselves. This includes the +parameters of Templates or the attributes of HTML tags. """ from .attribute import Attribute diff --git a/mwparserfromhell/nodes/extras/attribute.py b/mwparserfromhell/nodes/extras/attribute.py index 002eec7..3fb448f 100644 --- a/mwparserfromhell/nodes/extras/attribute.py +++ b/mwparserfromhell/nodes/extras/attribute.py @@ -30,9 +30,9 @@ __all__ = ["Attribute"] class Attribute(StringMixIn): """Represents an attribute of an HTML tag. - This is used by :py:class:`~mwparserfromhell.nodes.tag.Tag` objects. For - example, the tag ```` contains an Attribute whose name is - ``"name"`` and whose value is ``"foo"``. + This is used by :py:class:`~.Tag` objects. For example, the tag + ```` contains an Attribute whose name is ``"name"`` and + whose value is ``"foo"``. """ def __init__(self, name, value=None, quoted=True): @@ -50,12 +50,12 @@ class Attribute(StringMixIn): @property def name(self): - """The name of the attribute as a ``Wikicode`` object.""" + """The name of the attribute as a :py:class:`~.Wikicode` object.""" return self._name @property def value(self): - """The value of the attribute as a ``Wikicode`` object.""" + """The value of the attribute as a :py:class:`~.Wikicode` object.""" return self._value @property diff --git a/mwparserfromhell/nodes/extras/parameter.py b/mwparserfromhell/nodes/extras/parameter.py index 37a7b32..b3f53c1 100644 --- a/mwparserfromhell/nodes/extras/parameter.py +++ b/mwparserfromhell/nodes/extras/parameter.py @@ -50,12 +50,12 @@ class Parameter(StringMixIn): @property def name(self): - """The name of the parameter as a ``Wikicode`` object.""" + """The name of the parameter as a :py:class:`~.Wikicode` object.""" return self._name @property def value(self): - """The value of the parameter as a ``Wikicode`` object.""" + """The value of the parameter as a :py:class:`~.Wikicode` object.""" return self._value @property diff --git a/mwparserfromhell/nodes/heading.py b/mwparserfromhell/nodes/heading.py index ddd11a0..1d8c5e2 100644 --- a/mwparserfromhell/nodes/heading.py +++ b/mwparserfromhell/nodes/heading.py @@ -53,7 +53,7 @@ class Heading(Node): @property def title(self): - """The title of the heading itself, as a ``Wikicode`` object.""" + """The title of the heading, as a :py:class:`~.Wikicode` object.""" return self._title @property diff --git a/mwparserfromhell/nodes/tag.py b/mwparserfromhell/nodes/tag.py index edf888e..c58db86 100644 --- a/mwparserfromhell/nodes/tag.py +++ b/mwparserfromhell/nodes/tag.py @@ -172,20 +172,19 @@ class Tag(Node): @property def tag(self): - """The tag itself, as a ``Wikicode`` object.""" + """The tag itself, as a :py:class:`~.Wikicode` object.""" return self._tag @property def contents(self): - """The contents of the tag, as a ``Wikicode`` object.""" + """The contents of the tag, as a :py:class:`~.Wikicode` object.""" return self._contents @property def attrs(self): """The list of attributes affecting the tag. - Each attribute is an instance of - :py:class:`~mwparserfromhell.nodes.extras.attribute.Attribute`. + Each attribute is an instance of :py:class:`~.Attribute`. """ return self._attrs diff --git a/mwparserfromhell/nodes/template.py b/mwparserfromhell/nodes/template.py index 1ce6301..c1abc2a 100644 --- a/mwparserfromhell/nodes/template.py +++ b/mwparserfromhell/nodes/template.py @@ -152,7 +152,7 @@ class Template(Node): @property def name(self): - """The name of the template, as a ``Wikicode`` object.""" + """The name of the template, as a :py:class:`~.Wikicode` object.""" return self._name @property @@ -184,11 +184,10 @@ class Template(Node): """Get the parameter whose name is *name*. The returned object is a - :py:class:`~mwparserfromhell.nodes.extras.parameter.Parameter` - instance. Raises :py:exc:`ValueError` if no parameter has this name. - Since multiple parameters can have the same name, we'll return the last - match, since the last parameter is the only one read by the MediaWiki - parser. + :py:class:`~.Parameter` instance. Raises :py:exc:`ValueError` if no + parameter has this name. Since multiple parameters can have the same + name, we'll return the last match, since the last parameter is the only + one read by the MediaWiki parser. """ name = name.strip() if isinstance(name, basestring) else str(name) for param in reversed(self.params): @@ -200,14 +199,14 @@ class Template(Node): """Add a parameter to the template with a given *name* and *value*. *name* and *value* can be anything parasable by - :py:func:`mwparserfromhell.utils.parse_anything`; pipes (and equal - signs, if appropriate) are automatically escaped from *value* where - applicable. If *showkey* is given, this will determine whether or not - to show the parameter's name (e.g., ``{{foo|bar}}``'s parameter has a - name of ``"1"`` but it is hidden); otherwise, we'll make a safe and - intelligent guess. If *name* is already a parameter, we'll replace its - value while keeping the same spacing rules unless *force_nonconformity* - is ``True``. We will also try to guess the dominant spacing convention + :py:func:`.utils.parse_anything`; pipes (and equal signs, if + appropriate) are automatically escaped from *value* where applicable. + If *showkey* is given, this will determine whether or not to show the + parameter's name (e.g., ``{{foo|bar}}``'s parameter has a name of + ``"1"`` but it is hidden); otherwise, we'll make a safe and intelligent + guess. If *name* is already a parameter, we'll replace its value while + keeping the same spacing rules unless *force_nonconformity* is + ``True``. We will also try to guess the dominant spacing convention when adding a new parameter using :py:meth:`_get_spacing_conventions` unless *force_nonconformity* is ``True``. """ diff --git a/mwparserfromhell/parser/__init__.py b/mwparserfromhell/parser/__init__.py index 3c8dda0..da24b2f 100644 --- a/mwparserfromhell/parser/__init__.py +++ b/mwparserfromhell/parser/__init__.py @@ -22,9 +22,8 @@ """ This package contains the actual wikicode parser, split up into two main -modules: the :py:mod:`~mwparserfromhell.parser.tokenizer` and the -:py:mod:`~mwparserfromhell.parser.builder`. This module joins them together -under one interface. +modules: the :py:mod:`~.tokenizer` and the :py:mod:`~.builder`. This module +joins them together under one interface. """ try: @@ -40,12 +39,9 @@ class Parser(object): """Represents a parser for wikicode. Actual parsing is a two-step process: first, the text is split up into a - series of tokens by the - :py:class:`~mwparserfromhell.parser.tokenizer.Tokenizer`, and then the - tokens are converted into trees of - :py:class:`~mwparserfromhell.wikicode.Wikicode` objects and - :py:class:`~mwparserfromhell.nodes.Node`\ s by the - :py:class:`~mwparserfromhell.parser.builder.Builder`. + series of tokens by the :py:class:`~.Tokenizer`, and then the tokens are + converted into trees of :py:class:`~.Wikicode` objects and + :py:class:`~.Node`\ s by the :py:class:`~.Builder`. """ def __init__(self, text): @@ -54,7 +50,7 @@ class Parser(object): self._builder = Builder() def parse(self): - """Return a string as a parsed ``Wikicode`` object tree.""" + """Return a string as a parsed :py:class:`~.Wikicode` object tree.""" tokens = self._tokenizer.tokenize(self.text) code = self._builder.build(tokens) return code diff --git a/mwparserfromhell/parser/builder.py b/mwparserfromhell/parser/builder.py index a31f638..82233e4 100644 --- a/mwparserfromhell/parser/builder.py +++ b/mwparserfromhell/parser/builder.py @@ -34,10 +34,9 @@ __all__ = ["Builder"] class Builder(object): """Combines a sequence of tokens into a tree of ``Wikicode`` objects. - To use, pass a list of :py:class:`~mwparserfromhell.parser.tokens.Token`\ s - to the :py:meth:`build` method. The list will be exhausted as it is parsed - and a :py:class:`~mwparserfromhell.wikicode.Wikicode` object will be - returned. + To use, pass a list of :py:class:`~.Token`\ s to the :py:meth:`build` + method. The list will be exhausted as it is parsed and a + :py:class:`~.Wikicode` object will be returned. """ def __init__(self): diff --git a/mwparserfromhell/parser/tokenizer.py b/mwparserfromhell/parser/tokenizer.py index c549209..8cf6efd 100644 --- a/mwparserfromhell/parser/tokenizer.py +++ b/mwparserfromhell/parser/tokenizer.py @@ -92,7 +92,7 @@ class Tokenizer(object): """Fail the current tokenization route. Discards the current stack/context/textbuffer and raises - :py:exc:`~mwparserfromhell.parser.tokenizer.BadRoute`. + :py:exc:`~.BadRoute`. """ self._pop() raise BadRoute() diff --git a/mwparserfromhell/parser/tokens.py b/mwparserfromhell/parser/tokens.py index bb91a94..23a04b2 100644 --- a/mwparserfromhell/parser/tokens.py +++ b/mwparserfromhell/parser/tokens.py @@ -24,10 +24,8 @@ This module contains the token definitions that are used as an intermediate parsing data type - they are stored in a flat list, with each token being identified by its type and optional attributes. The token list is generated in -a syntactically valid form by the -:py:class:`~mwparserfromhell.parser.tokenizer.Tokenizer`, and then converted -into the :py:class`~mwparserfromhell.wikicode.Wikicode` tree by the -:py:class:`~mwparserfromhell.parser.builder.Builder`. +a syntactically valid form by the :py:class:`~.Tokenizer`, and then converted +into the :py:class`~.Wikicode` tree by the :py:class:`~.Builder`. """ from __future__ import unicode_literals diff --git a/mwparserfromhell/smart_list.py b/mwparserfromhell/smart_list.py index 3d260f8..1f1f505 100644 --- a/mwparserfromhell/smart_list.py +++ b/mwparserfromhell/smart_list.py @@ -21,10 +21,9 @@ # SOFTWARE. """ -This module contains the :py:class:`~mwparserfromhell.smart_list.SmartList` -type, as well as its :py:class:`~mwparserfromhell.smart_list._ListProxy` child, -which together implement a list whose sublists reflect changes made to the main -list, and vice-versa. +This module contains the :py:class:`~.SmartList` type, as well as its +:py:class:`~._ListProxy` child, which together implement a list whose sublists +reflect changes made to the main list, and vice-versa. """ from __future__ import unicode_literals @@ -36,9 +35,8 @@ __all__ = ["SmartList"] def inheritdoc(method): """Set __doc__ of *method* to __doc__ of *method* in its parent class. - Since this is used on - :py:class:`~mwparserfromhell.smart_list.SmartList`, the "parent class" used - is ``list``. This function can be used as a decorator. + Since this is used on :py:class:`~.SmartList`, the "parent class" used is + ``list``. This function can be used as a decorator. """ method.__doc__ = getattr(list, method.__name__).__doc__ return method @@ -51,10 +49,9 @@ class SmartList(list): list (such as the addition, removal, or replacement of elements) will be reflected in the sublist, or vice-versa, to the greatest degree possible. This is implemented by having sublists - instances of the - :py:class:`~mwparserfromhell.smart_list._ListProxy` type - dynamically - determine their elements by storing their slice info and retrieving that - slice from the parent. Methods that change the size of the list also change - the slice info. For example:: + :py:class:`~._ListProxy` type - dynamically determine their elements by + storing their slice info and retrieving that slice from the parent. Methods + that change the size of the list also change the slice info. For example:: >>> parent = SmartList([0, 1, 2, 3]) >>> parent @@ -183,10 +180,9 @@ class SmartList(list): class _ListProxy(list): """Implement the ``list`` interface by getting elements from a parent. - This is created by a :py:class:`~mwparserfromhell.smart_list.SmartList` - object when slicing. It does not actually store the list at any time; - instead, whenever the list is needed, it builds it dynamically using the - :py:meth:`_render` method. + This is created by a :py:class:`~.SmartList` object when slicing. It does + not actually store the list at any time; instead, whenever the list is + needed, it builds it dynamically using the :py:meth:`_render` method. """ def __init__(self, parent, sliceinfo): diff --git a/mwparserfromhell/string_mixin.py b/mwparserfromhell/string_mixin.py index 70d88af..d63f25d 100644 --- a/mwparserfromhell/string_mixin.py +++ b/mwparserfromhell/string_mixin.py @@ -21,9 +21,8 @@ # SOFTWARE. """ -This module contains the :py:class:`~mwparserfromhell.string_mixin.StringMixIn` -type, which implements the interface for the ``unicode`` type (``str`` on py3k) -in a dynamic manner. +This module contains the :py:class:`~.StringMixIn` type, which implements the +interface for the ``unicode`` type (``str`` on py3k) in a dynamic manner. """ from __future__ import unicode_literals @@ -35,9 +34,8 @@ __all__ = ["StringMixIn"] def inheritdoc(method): """Set __doc__ of *method* to __doc__ of *method* in its parent class. - Since this is used on - :py:class:`~mwparserfromhell.string_mixin.StringMixIn`, the "parent class" - used is ``str``. This function can be used as a decorator. + Since this is used on :py:class:`~.StringMixIn`, the "parent class" used is + ``str``. This function can be used as a decorator. """ method.__doc__ = getattr(str, method.__name__).__doc__ return method diff --git a/mwparserfromhell/utils.py b/mwparserfromhell/utils.py index 4e7bf8a..eea2946 100644 --- a/mwparserfromhell/utils.py +++ b/mwparserfromhell/utils.py @@ -33,20 +33,16 @@ from .nodes import Node from .smart_list import SmartList def parse_anything(value): - """Return a :py:class:`~mwparserfromhell.wikicode.Wikicode` for *value*. + """Return a :py:class:`~.Wikicode` for *value*, allowing multiple types. This differs from :py:func:`mwparserfromhell.parse` in that we accept more than just a string to be parsed. Unicode objects (strings in py3k), strings (bytes in py3k), integers (converted to strings), ``None``, existing - :py:class:`~mwparserfromhell.nodes.Node` or - :py:class:`~mwparserfromhell.wikicode.Wikicode` objects, as well as an + :py:class:`~.Node` or :py:class:`~.Wikicode` objects, as well as an iterable of these types, are supported. This is used to parse input - on-the-fly by various methods of - :py:class:`~mwparserfromhell.wikicode.Wikicode` and others like - :py:class:`~mwparserfromhell.nodes.template.Template`, such as - :py:meth:`wikicode.insert() ` - or setting :py:meth:`template.name - `. + on-the-fly by various methods of :py:class:`~.Wikicode` and others like + :py:class:`~.Template`, such as :py:meth:`wikicode.insert() + <.Wikicode.insert>` or setting :py:meth:`template.name <.Template.name>`. """ wikicode = mwparserfromhell.wikicode.Wikicode if isinstance(value, wikicode): diff --git a/mwparserfromhell/wikicode.py b/mwparserfromhell/wikicode.py index e507143..d144f7b 100644 --- a/mwparserfromhell/wikicode.py +++ b/mwparserfromhell/wikicode.py @@ -158,10 +158,10 @@ class Wikicode(StringMixIn): @property def nodes(self): - """A list of :py:class:`~mwparserfromhell.nodes.Node` objects. + """A list of :py:class:`~.Node` objects. This is the internal data actually stored within a - :py:class:`~mwparserfromhell.wikicode.Wikicode` object. + :py:class:`~.Wikicode` object. """ return self._nodes @@ -178,9 +178,9 @@ class Wikicode(StringMixIn): Raises :py:exc:`IndexError` if *index* is out of range, or :py:exc:`ValueError` if *value* cannot be coerced into one - :py:class:`~mwparserfromhell.nodes.Node`. To insert multiple nodes at - an index, use :py:meth:`get` with either :py:meth:`remove` and - :py:meth:`insert` or :py:meth:`replace`. + :py:class:`~.Node`. To insert multiple nodes at an index, use + :py:meth:`get` with either :py:meth:`remove` and :py:meth:`insert` or + :py:meth:`replace`. """ nodes = parse_anything(value).nodes if len(nodes) > 1: @@ -213,10 +213,9 @@ class Wikicode(StringMixIn): def insert(self, index, value): """Insert *value* at *index* in the list of nodes. - *value* can be anything parasable by - :py:func:`mwparserfromhell.utils.parse_anything`, which includes - strings or other :py:class:`~mwparserfromhell.wikicode.Wikicode` or - :py:class:`~mwparserfromhell.nodes.Node` objects. + *value* can be anything parasable by :py:func:`.parse_anything`, which + includes strings or other :py:class:`~.Wikicode` or :py:class:`~.Node` + objects. """ nodes = parse_anything(value).nodes for node in reversed(nodes): @@ -225,13 +224,11 @@ class Wikicode(StringMixIn): def insert_before(self, obj, value, recursive=True): """Insert *value* immediately before *obj* in the list of nodes. - *obj* can be either a string or a - :py:class:`~mwparserfromhell.nodes.Node`. *value* can be anything - parasable by :py:func:`mwparserfromhell.utils.parse_anything`. If - *recursive* is ``True``, we will try to find *obj* within our child - nodes even if it is not a direct descendant of this - :py:class:`~mwparserfromhell.wikicode.Wikicode` object. If *obj* is not - in the node list, :py:exc:`ValueError` is raised. + *obj* can be either a string or a :py:class:`~.Node`. *value* can be + anything parasable by :py:func:`.parse_anything`. If *recursive* is + ``True``, we will try to find *obj* within our child nodes even if it + is not a direct descendant of this :py:class:`~.Wikicode` object. If + *obj* is not in the node list, :py:exc:`ValueError` is raised. """ callback = lambda self, i, value: self.insert(i, value) self._do_search(obj, recursive, callback, self, value) @@ -239,13 +236,11 @@ class Wikicode(StringMixIn): def insert_after(self, obj, value, recursive=True): """Insert *value* immediately after *obj* in the list of nodes. - *obj* can be either a string or a - :py:class:`~mwparserfromhell.nodes.Node`. *value* can be anything - parasable by :py:func:`mwparserfromhell.utils.parse_anything`. If - *recursive* is ``True``, we will try to find *obj* within our child - nodes even if it is not a direct descendant of this - :py:class:`~mwparserfromhell.wikicode.Wikicode` object. If *obj* is not - in the node list, :py:exc:`ValueError` is raised. + *obj* can be either a string or a :py:class:`~.Node`. *value* can be + anything parasable by :py:func:`.parse_anything`. If *recursive* is + ``True``, we will try to find *obj* within our child nodes even if it + is not a direct descendant of this :py:class:`~.Wikicode` object. If + *obj* is not in the node list, :py:exc:`ValueError` is raised. """ callback = lambda self, i, value: self.insert(i + 1, value) self._do_search(obj, recursive, callback, self, value) @@ -253,13 +248,11 @@ class Wikicode(StringMixIn): def replace(self, obj, value, recursive=True): """Replace *obj* with *value* in the list of nodes. - *obj* can be either a string or a - :py:class:`~mwparserfromhell.nodes.Node`. *value* can be anything - parasable by :py:func:`mwparserfromhell.utils.parse_anything`. If - *recursive* is ``True``, we will try to find *obj* within our child - nodes even if it is not a direct descendant of this - :py:class:`~mwparserfromhell.wikicode.Wikicode` object. If *obj* is not - in the node list, :py:exc:`ValueError` is raised. + *obj* can be either a string or a :py:class:`~.Node`. *value* can be + anything parasable by :py:func:`.parse_anything`. If *recursive* is + ``True``, we will try to find *obj* within our child nodes even if it + is not a direct descendant of this :py:class:`~.Wikicode` object. If + *obj* is not in the node list, :py:exc:`ValueError` is raised. """ def callback(self, i, value): self.nodes.pop(i) @@ -270,8 +263,7 @@ class Wikicode(StringMixIn): def append(self, value): """Insert *value* at the end of the list of nodes. - *value* can be anything parasable by - :py:func:`mwparserfromhell.utils.parse_anything`. + *value* can be anything parasable by :py:func:`.parse_anything`. """ nodes = parse_anything(value).nodes for node in nodes: @@ -280,12 +272,10 @@ class Wikicode(StringMixIn): def remove(self, obj, recursive=True): """Remove *obj* from the list of nodes. - *obj* can be either a string or a - :py:class:`~mwparserfromhell.nodes.Node`. If *recursive* is ``True``, - we will try to find *obj* within our child nodes even if it is not a - direct descendant of this - :py:class:`~mwparserfromhell.wikicode.Wikicode` object. If *obj* is not - in the node list, :py:exc:`ValueError` is raised. + *obj* can be either a string or a :py:class:`~.Node`. If *recursive* is + ``True``, we will try to find *obj* within our child nodes even if it + is not a direct descendant of this :py:class:`~.Wikicode` object. If + *obj* is not in the node list, :py:exc:`ValueError` is raised. """ callback = lambda self, i: self.nodes.pop(i) self._do_search(obj, recursive, callback, self) @@ -316,7 +306,7 @@ class Wikicode(StringMixIn): """Iterate over template nodes. This is equivalent to :py:meth:`ifilter` with *forcetype* set to - :py:class:`~mwparserfromhell.nodes.template.Template`. + :py:class:`~.Template`. """ return self.filter(recursive, matches, flags, forcetype=Template) @@ -324,7 +314,7 @@ class Wikicode(StringMixIn): """Iterate over text nodes. This is equivalent to :py:meth:`ifilter` with *forcetype* set to - :py:class:`~mwparserfromhell.nodes.text.Text`. + :py:class:`~.Text`. """ return self.filter(recursive, matches, flags, forcetype=Text) @@ -332,7 +322,7 @@ class Wikicode(StringMixIn): """Iterate over tag nodes. This is equivalent to :py:meth:`ifilter` with *forcetype* set to - :py:class:`~mwparserfromhell.nodes.tag.Tag`. + :py:class:`~.Tag`. """ return self.ifilter(recursive, matches, flags, forcetype=Tag) @@ -372,24 +362,20 @@ class Wikicode(StringMixIn): include_headings=True): """Return a list of sections within the page. - Sections are returned as - :py:class:`~mwparserfromhell.wikicode.Wikicode` objects with a shared - node list (implemented using - :py:class:`~mwparserfromhell.smart_list.SmartList`) so that changes to - sections are reflected in the parent Wikicode object. + Sections are returned as :py:class:`~.Wikicode` objects with a shared + node list (implemented using :py:class:`~.SmartList`) so that changes + to sections are reflected in the parent Wikicode object. With *flat* as ``True``, each returned section contains all of its - subsections within the :py:class:`~mwparserfromhell.wikicode.Wikicode`; - otherwise, the returned sections contain only the section up to the - next heading, regardless of its size. If *matches* is given, it should - be a regex to matched against the titles of section headings; only - sections whose headings match the regex will be included. If *levels* - is given, it should be a list of integers; only sections whose heading - levels are within the list will be returned. If *include_headings* is - ``True``, the section's literal - :py:class:`~mwparserfromhell.nodes.heading.Heading` object will be - included in returned :py:class:`~mwparserfromhell.wikicode.Wikicode` - objects; otherwise, this is skipped. + subsections within the :py:class:`~.Wikicode`; otherwise, the returned + sections contain only the section up to the next heading, regardless of + its size. If *matches* is given, it should be a regex to matched + against the titles of section headings; only sections whose headings + match the regex will be included. If *levels* is given, it should be a = + list of integers; only sections whose heading levels are within the + list will be returned. If *include_headings* is ``True``, the section's + literal :py:class:`~.Heading` object will be included in returned + :py:class:`~.Wikicode` objects; otherwise, this is skipped. """ if matches: matches = r"^(=+?)\s*" + matches + r"\s*\1$" @@ -421,16 +407,15 @@ class Wikicode(StringMixIn): """Return a rendered string without unprintable code such as templates. The way a node is stripped is handled by the - :py:meth:`~mwparserfromhell.nodes.Node.__showtree__` method of - :py:class:`~mwparserfromhell.nodes.Node` objects, which generally - return a subset of their nodes or ``None``. For example, templates and - tags are removed completely, links are stripped to just their display - part, headings are stripped to just their title. If *normalize* is - ``True``, various things may be done to strip code further, such as - converting HTML entities like ``Σ``, ``Σ``, and ``Σ`` - to ``Σ``. If *collapse* is ``True``, we will try to remove excess - whitespace as well (three or more newlines are converted to two, for - example). + :py:meth:`~.Node.__showtree__` method of :py:class:`~.Node` objects, + which generally return a subset of their nodes or ``None``. For + example, templates and tags are removed completely, links are stripped + to just their display part, headings are stripped to just their title. + If *normalize* is ``True``, various things may be done to strip code + further, such as converting HTML entities like ``Σ``, ``Σ``, + and ``Σ`` to ``Σ``. If *collapse* is ``True``, we will try to + remove excess whitespace as well (three or more newlines are converted + to two, for example). """ nodes = [] for node in self.nodes: @@ -451,8 +436,8 @@ class Wikicode(StringMixIn): The representation is a string makes the most sense printed. It is built by calling :py:meth:`_get_tree` on the - :py:class:`~mwparserfromhell.wikicode.Wikicode` object and its children - recursively. The end result may look something like the following:: + :py:class:`~.Wikicode` object and its children recursively. The end + result may look something like the following:: >>> text = "Lorem ipsum {{foo|bar|{{baz}}|spam=eggs}}" >>> print mwparserfromhell.parse(text).get_tree()