diff --git a/mwparserfromhell/__init__.py b/mwparserfromhell/__init__.py index 27d0931..1e1e0f0 100644 --- a/mwparserfromhell/__init__.py +++ b/mwparserfromhell/__init__.py @@ -37,3 +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().""" diff --git a/mwparserfromhell/compat.py b/mwparserfromhell/compat.py index aa5a007..38b5a7f 100755 --- a/mwparserfromhell/compat.py +++ b/mwparserfromhell/compat.py @@ -1,7 +1,11 @@ # -*- coding: utf-8 -*- """ -Implements support for both Python 2 and Python 3. +Implements support for both Python 2 and Python 3 by defining common types in +terms of their Python 2/3 variants. For example, :py:class:`str` is set to +:py:class:`unicode` on Python 2 but :py:class:`str` on Python 3; likewise, +:py;class:`bytes` is :py:class:`str` on 2 but :py:class:`bytes` on 3. These +types are meant to be imported directly from within the parser's modules. """ import sys diff --git a/mwparserfromhell/nodes/extras/__init__.py b/mwparserfromhell/nodes/extras/__init__.py index 825d1af..2f165d1 100644 --- a/mwparserfromhell/nodes/extras/__init__.py +++ b/mwparserfromhell/nodes/extras/__init__.py @@ -20,5 +20,11 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. +""" +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. +""" + from .attribute import Attribute from .parameter import Parameter diff --git a/mwparserfromhell/nodes/extras/attribute.py b/mwparserfromhell/nodes/extras/attribute.py index 92a7dff..002eec7 100644 --- a/mwparserfromhell/nodes/extras/attribute.py +++ b/mwparserfromhell/nodes/extras/attribute.py @@ -28,6 +28,13 @@ from ...string_mixin import StringMixIn __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"``. + """ + def __init__(self, name, value=None, quoted=True): super(Attribute, self).__init__() self._name = name @@ -43,12 +50,15 @@ class Attribute(StringMixIn): @property def name(self): + """The name of the attribute as a ``Wikicode`` object.""" return self._name @property def value(self): + """The value of the attribute as a ``Wikicode`` object.""" return self._value @property def quoted(self): + """Whether the attribute's value is quoted with double quotes.""" return self._quoted diff --git a/mwparserfromhell/nodes/extras/parameter.py b/mwparserfromhell/nodes/extras/parameter.py index 7038783..37a7b32 100644 --- a/mwparserfromhell/nodes/extras/parameter.py +++ b/mwparserfromhell/nodes/extras/parameter.py @@ -29,6 +29,14 @@ from ...utils import parse_anything __all__ = ["Parameter"] class Parameter(StringMixIn): + """Represents a paramater of a template. + + For example, the template ``{{foo|bar|spam=eggs}}`` contains two + Parameters: one whose name is ``"1"``, value is ``"bar"``, and ``showkey`` + is ``False``, and one whose name is ``"spam"``, value is ``"eggs"``, and + ``showkey`` is ``True``. + """ + def __init__(self, name, value, showkey=True): super(Parameter, self).__init__() self._name = name @@ -42,14 +50,17 @@ class Parameter(StringMixIn): @property def name(self): + """The name of the parameter as a ``Wikicode`` object.""" return self._name @property def value(self): + """The value of the parameter as a ``Wikicode`` object.""" return self._value @property def showkey(self): + """Whether to show the parameter's key (i.e., its "name").""" return self._showkey @name.setter diff --git a/mwparserfromhell/smart_list.py b/mwparserfromhell/smart_list.py index de86750..4346132 100644 --- a/mwparserfromhell/smart_list.py +++ b/mwparserfromhell/smart_list.py @@ -68,6 +68,7 @@ class SmartList(list): >>> parent [0, 1, 2, 3, 4] """ + def __init__(self, iterable=None): if iterable: super(SmartList, self).__init__(iterable) @@ -187,6 +188,7 @@ class _ListProxy(list): instead, whenever the list is needed, it builds it dynamically using the :py:meth:`_render` method. """ + def __init__(self, parent, sliceinfo): super(_ListProxy, self).__init__() self._parent = parent diff --git a/mwparserfromhell/string_mixin.py b/mwparserfromhell/string_mixin.py index 578d010..70d88af 100644 --- a/mwparserfromhell/string_mixin.py +++ b/mwparserfromhell/string_mixin.py @@ -52,6 +52,7 @@ class StringMixIn(object): :py:meth:`__unicode__` instead of the immutable ``self`` like the regular ``str`` type. """ + if py3k: def __str__(self): return self.__unicode__()