A Python parser for MediaWiki wikicode https://mwparserfromhell.readthedocs.io/
選択できるのは25トピックまでです。 トピックは、先頭が英数字で、英数字とダッシュ('-')を使用した35文字以内のものにしてください。

README.rst 5.7 KiB

11年前
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154
  1. mwparserfromhell
  2. ================
  3. .. image:: https://travis-ci.org/earwig/mwparserfromhell.png?branch=develop
  4. :alt: Build Status
  5. :target: http://travis-ci.org/earwig/mwparserfromhell
  6. **mwparserfromhell** (the *MediaWiki Parser from Hell*) is a Python package
  7. that provides an easy-to-use and outrageously powerful parser for MediaWiki_
  8. wikicode. It supports Python 2 and Python 3.
  9. Developed by Earwig_ with help from `Σ`_. Full documentation is available on
  10. ReadTheDocs_.
  11. Installation
  12. ------------
  13. The easiest way to install the parser is through the `Python Package Index`_,
  14. so you can install the latest release with ``pip install mwparserfromhell``
  15. (`get pip`_). Alternatively, get the latest development version::
  16. git clone https://github.com/earwig/mwparserfromhell.git
  17. cd mwparserfromhell
  18. python setup.py install
  19. If you get ``error: Unable to find vcvarsall.bat`` while installing, this is
  20. because Windows can't find the compiler for C extensions. Consult this
  21. `StackOverflow question`_ for help. You can also set ``ext_modules`` in
  22. ``setup.py`` to an empty list to prevent the extension from building.
  23. You can run the comprehensive unit testing suite with
  24. ``python setup.py test -q``.
  25. Usage
  26. -----
  27. Normal usage is rather straightforward (where ``text`` is page text)::
  28. >>> import mwparserfromhell
  29. >>> wikicode = mwparserfromhell.parse(text)
  30. ``wikicode`` is a ``mwparserfromhell.Wikicode`` object, which acts like an
  31. ordinary ``unicode`` object (or ``str`` in Python 3) with some extra methods.
  32. For example::
  33. >>> text = "I has a template! {{foo|bar|baz|eggs=spam}} See it?"
  34. >>> wikicode = mwparserfromhell.parse(text)
  35. >>> print wikicode
  36. I has a template! {{foo|bar|baz|eggs=spam}} See it?
  37. >>> templates = wikicode.filter_templates()
  38. >>> print templates
  39. ['{{foo|bar|baz|eggs=spam}}']
  40. >>> template = templates[0]
  41. >>> print template.name
  42. foo
  43. >>> print template.params
  44. ['bar', 'baz', 'eggs=spam']
  45. >>> print template.get(1).value
  46. bar
  47. >>> print template.get("eggs").value
  48. spam
  49. Since every node you reach is also a ``Wikicode`` object, it's trivial to get
  50. nested templates::
  51. >>> code = mwparserfromhell.parse("{{foo|this {{includes a|template}}}}")
  52. >>> print code.filter_templates()
  53. ['{{foo|this {{includes a|template}}}}']
  54. >>> foo = code.filter_templates()[0]
  55. >>> print foo.get(1).value
  56. this {{includes a|template}}
  57. >>> print foo.get(1).value.filter_templates()[0]
  58. {{includes a|template}}
  59. >>> print foo.get(1).value.filter_templates()[0].get(1).value
  60. template
  61. Additionally, you can include nested templates in ``filter_templates()`` by
  62. passing ``recursive=True``::
  63. >>> text = "{{foo|{{bar}}={{baz|{{spam}}}}}}"
  64. >>> mwparserfromhell.parse(text).filter_templates(recursive=True)
  65. ['{{foo|{{bar}}={{baz|{{spam}}}}}}', '{{bar}}', '{{baz|{{spam}}}}', '{{spam}}']
  66. Templates can be easily modified to add, remove, or alter params. ``Wikicode``
  67. can also be treated like a list with ``append()``, ``insert()``, ``remove()``,
  68. ``replace()``, and more::
  69. >>> text = "{{cleanup}} '''Foo''' is a [[bar]]. {{uncategorized}}"
  70. >>> code = mwparserfromhell.parse(text)
  71. >>> for template in code.filter_templates():
  72. ... if template.name == "cleanup" and not template.has_param("date"):
  73. ... template.add("date", "July 2012")
  74. ...
  75. >>> print code
  76. {{cleanup|date=July 2012}} '''Foo''' is a [[bar]]. {{uncategorized}}
  77. >>> code.replace("{{uncategorized}}", "{{bar-stub}}")
  78. >>> print code
  79. {{cleanup|date=July 2012}} '''Foo''' is a [[bar]]. {{bar-stub}}
  80. >>> print code.filter_templates()
  81. ['{{cleanup|date=July 2012}}', '{{bar-stub}}']
  82. You can then convert ``code`` back into a regular ``unicode`` object (for
  83. saving the page!) by calling ``unicode()`` on it::
  84. >>> text = unicode(code)
  85. >>> print text
  86. {{cleanup|date=July 2012}} '''Foo''' is a [[bar]]. {{bar-stub}}
  87. >>> text == code
  88. True
  89. Likewise, use ``str(code)`` in Python 3.
  90. Integration
  91. -----------
  92. ``mwparserfromhell`` is used by and originally developed for EarwigBot_;
  93. ``Page`` objects have a ``parse`` method that essentially calls
  94. ``mwparserfromhell.parse()`` on ``page.get()``.
  95. If you're using Pywikipedia_, your code might look like this::
  96. import mwparserfromhell
  97. import wikipedia as pywikibot
  98. def parse(title):
  99. site = pywikibot.getSite()
  100. page = pywikibot.Page(site, title)
  101. text = page.get()
  102. return mwparserfromhell.parse(text)
  103. If you're not using a library, you can parse templates in any page using the
  104. following code (via the API_)::
  105. import json
  106. import urllib
  107. import mwparserfromhell
  108. API_URL = "http://en.wikipedia.org/w/api.php"
  109. def parse(title):
  110. data = {"action": "query", "prop": "revisions", "rvlimit": 1,
  111. "rvprop": "content", "format": "json", "titles": title}
  112. raw = urllib.urlopen(API_URL, urllib.urlencode(data)).read()
  113. res = json.loads(raw)
  114. text = res["query"]["pages"].values()[0]["revisions"][0]["*"]
  115. return mwparserfromhell.parse(text)
  116. .. _MediaWiki: http://mediawiki.org
  117. .. _ReadTheDocs: http://mwparserfromhell.readthedocs.org
  118. .. _Earwig: http://en.wikipedia.org/wiki/User:The_Earwig
  119. .. _Σ: http://en.wikipedia.org/wiki/User:%CE%A3
  120. .. _Python Package Index: http://pypi.python.org
  121. .. _StackOverflow question: http://stackoverflow.com/questions/2817869/error-unable-to-find-vcvarsall-bat
  122. .. _get pip: http://pypi.python.org/pypi/pip
  123. .. _EarwigBot: https://github.com/earwig/earwigbot
  124. .. _Pywikipedia: https://www.mediawiki.org/wiki/Manual:Pywikipediabot
  125. .. _API: http://mediawiki.org/wiki/API