From 0d224e1a6309855a3c101c63bcc2b491ce732b88 Mon Sep 17 00:00:00 2001 From: Ben Kurtovic Date: Tue, 21 Aug 2012 16:00:21 -0400 Subject: [PATCH] Document mwparserfromhell.nodes, Node, Heading, and HTMLEntity. --- mwparserfromhell/nodes/__init__.py | 25 +++++++++++++++++++++++++ mwparserfromhell/nodes/heading.py | 3 +++ mwparserfromhell/nodes/html_entity.py | 16 ++++++++++++++++ 3 files changed, 44 insertions(+) diff --git a/mwparserfromhell/nodes/__init__.py b/mwparserfromhell/nodes/__init__.py index 9cbb47c..b5f45a1 100644 --- a/mwparserfromhell/nodes/__init__.py +++ b/mwparserfromhell/nodes/__init__.py @@ -20,6 +20,17 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # 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. +""" + from __future__ import unicode_literals from ..compat import str @@ -28,6 +39,20 @@ from ..string_mixin import StringMixIn __all__ = ["Node", "Text", "Heading", "HTMLEntity", "Tag", "Template"] class Node(StringMixIn): + """Represents the base Node type, demonstrating the methods to override. + + :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`. + """ def __unicode__(self): raise NotImplementedError() diff --git a/mwparserfromhell/nodes/heading.py b/mwparserfromhell/nodes/heading.py index dc98c41..9fb2562 100644 --- a/mwparserfromhell/nodes/heading.py +++ b/mwparserfromhell/nodes/heading.py @@ -28,6 +28,7 @@ from ..compat import str __all__ = ["Heading"] class Heading(Node): + """Represents a section heading in wikicode, like ``== Foo ==``.""" def __init__(self, title, level): super(Heading, self).__init__() self._title = title @@ -51,8 +52,10 @@ class Heading(Node): @property def title(self): + """The title of the heading itself, as a ``Wikicode`` object.""" return self._title @property def level(self): + """The heading level, as an integer between 1 and 6, inclusive.""" return self._level diff --git a/mwparserfromhell/nodes/html_entity.py b/mwparserfromhell/nodes/html_entity.py index ce66259..d46c3d3 100644 --- a/mwparserfromhell/nodes/html_entity.py +++ b/mwparserfromhell/nodes/html_entity.py @@ -28,6 +28,7 @@ from ..compat import htmlentities __all__ = ["HTMLEntity"] class HTMLEntity(Node): + """Represents an HTML entity, like `` ``, either named or unnamed.""" def __init__(self, value, named=None, hexadecimal=False, hex_char="x"): super(HTMLEntity, self).__init__() self._value = value @@ -86,21 +87,36 @@ class HTMLEntity(Node): @property def value(self): + """The string value of the HTML entity.""" return self._value @property def named(self): + """Whether the entity is a string name for a codepoint or an integer. + + For example, ``Σ``, ``Σ``, and ``Σ`` refer to the same + character, but only the first is "named", while the others are integer + representations of the codepoint. + """ return self._named @property def hexadecimal(self): + """If unnamed, this is whether the value is hexadecimal or decimal.""" return self._hexadecimal @property def hex_char(self): + """If the value is hexadecimal, this is the letter denoting that. + + For example, the hex_char of ``"ሴ"`` is ``"x"``, whereas the + hex_char of ``"ሴ"`` is ``"X"``. Lowercase and uppercase ``x`` + are the only values supported. + """ return self._hex_char def normalize(self): + """Return the unicode character represented by the HTML entity.""" if self.named: return unichr(htmlentities.name2codepoint[self.value]) if self.hexadecimal: