wmlinksfromhell 0.1.0__tar.gz

wmlinksfromhell-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+build/
+dist/
+dist_sdist/
+.venv/
+venv/
+
+# local metadata/cache files
+*.json
+!pyproject.toml

wmlinksfromhell-0.1.0/.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+mkdocs:
+  configuration: mkdocs.yml

wmlinksfromhell-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 — 2026-09-10
+
+First public release.
+
+- Wikimedia interwiki and language/project link resolution.
+- Wikimedia wiki URL and `index.php` URL resolution.
+- Support for local and external links.
+- Prefix chains, namespaces, fragments, revisions, diffs, actions, and page IDs.
+- Link matching and conversion between URL, interwiki, and local forms.
+- SiteMatrix and interwiki metadata with local caching.
+- Pywikibot `Site` and `Page` support.

wmlinksfromhell-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wmlinksfromhell-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include MANIFEST.in
+include requirements-dev.txt
+recursive-include examples *.py
+recursive-include tests *.py *.txt
+prune build
+prune dist
+prune dist_sdist
+prune wmlinksfromhell.egg-info
+prune .venv
+prune docs

wmlinksfromhell-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: wmlinksfromhell
+Version: 0.1.0
+Summary: A library for resolving and working with Wikimedia and MediaWiki links.
+Author: Max
+Author-email: madmax.wp@proton.me
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Keywords: mediawiki,wikimedia,wikipedia,interwiki,wikitext,links,parser,resolver
+Project-URL: Documentation, https://wmlinksfromhell.readthedocs.io/en/latest/
+Project-URL: Repository, https://github.com/MadMaxWP/wmlinksfromhell
+Project-URL: Issues, https://github.com/MadMaxWP/wmlinksfromhell/issues
+Project-URL: Changelog, https://github.com/MadMaxWP/wmlinksfromhell/blob/main/CHANGELOG.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Internet
+Requires-Dist: mwparserfromhell>=0.6
+Provides-Extra: pywikibot
+Requires-Dist: pywikibot>=8.0; extra == "pywikibot"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+
+# wmlinksfromhell
+
+[![CI](https://github.com/MadMaxWP/wmlinksfromhell/actions/workflows/ci.yml/badge.svg)](https://github.com/MadMaxWP/wmlinksfromhell/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/wmlinksfromhell.svg)](https://pypi.org/project/wmlinksfromhell/)
+[![Python](https://img.shields.io/pypi/pyversions/wmlinksfromhell.svg)](https://pypi.org/project/wmlinksfromhell/)
+[![Downloads](https://img.shields.io/pypi/dm/wmlinksfromhell.svg)](https://pypi.org/project/wmlinksfromhell/)
+[![License](https://img.shields.io/github/license/MadMaxWP/wmlinksfromhell.svg)](https://github.com/MadMaxWP/wmlinksfromhell/blob/main/LICENSE)
+[![Repo Size](https://img.shields.io/github/repo-size/MadMaxWP/wmlinksfromhell.svg)](https://github.com/MadMaxWP/wmlinksfromhell)
+
+**wmlinksfromhell** is a Python package for working with links on Wikimedia and other MediaWiki sites. It is mainly focused on Wikimedia interwiki links, language and project prefixes, and Wikimedia URLs, with support for local links and external URLs too.
+
+It can resolve links to their destination wiki and page, convert them between interwiki and URL forms, and give you the details you need to work with them in your code.
+
+Developed by [Max](https://github.com/MadMaxWP).
+
+Full documentation is available on [Read the Docs](https://wmlinksfromhell.readthedocs.io/en/latest/). Development takes place on [GitHub](https://github.com/MadMaxWP/wmlinksfromhell), and bugs and feature requests can be reported in the [issue tracker](https://github.com/MadMaxWP/wmlinksfromhell/issues).
+
+## Project links
+
+- [Documentation](https://wmlinksfromhell.readthedocs.io/en/latest/)
+- [API Reference](https://wmlinksfromhell.readthedocs.io/en/latest/api-reference/)
+- [Changelog](https://github.com/MadMaxWP/wmlinksfromhell/blob/main/CHANGELOG.md)
+- [Issues](https://github.com/MadMaxWP/wmlinksfromhell/issues)
+- [Repository](https://github.com/MadMaxWP/wmlinksfromhell)
+
+## Install
+
+```bash
+python3 -m pip install wmlinksfromhell
+```
+
+Pywikibot support is optional:
+
+```bash
+python3 -m pip install 'wmlinksfromhell[pywikibot]'
+```
+
+Supports Python 3.9 and newer.
+
+## Quick start
+
+Get information about a wiki:
+
+```python
+import wmlinksfromhell
+
+wiki = wmlinksfromhell.wiki("enwiki")
+
+print(wiki.language)       # en
+print(wiki.hostname)       # en.wikipedia.org
+print(wiki.page_url("Apple"))
+print(wiki.interwiki("Apple"))
+```
+
+Resolve a Wikimedia link:
+
+```python
+result = wmlinksfromhell.resolve("w:en:Apple")
+
+print(result.dbname)        # enwiki
+print(result.title)         # Apple
+print(result.url)           # https://en.wikipedia.org/wiki/Apple
+```
+
+Parse links from MediaWiki text:
+
+```python
+import wmlinksfromhell
+
+code = wmlinksfromhell.parse(
+    "[[w:en:Apple]] https://de.wikipedia.org/wiki/Berlin https://example.org/",
+    source="metawiki",
+)
+
+for link in code.filter_links():
+    print(link.original)
+    print(link.dbname, link.title, link.url)
+```
+
+The parser keeps the original way a link was written separate from the destination it resolves to. This lets you work with the same destination whether it came from an interwiki link, a wiki URL, or another supported form.
+
+## Wikimedia links
+
+The resolver understands Wikimedia language and project prefixes, including prefix chains:
+
+```text
+w:en:Apple
+wikt:simple:uppercase
+b:de:Main Page
+:de:q:Hauptseite
+:m:en:About
+:w:it:b:Wiskunde
+```
+
+It also handles Wikimedia URL forms such as article paths and `index.php`, including fragments, revisions, diffs, actions, and page IDs.
+
+For example:
+
+```python
+result = wmlinksfromhell.resolve(
+    "https://en.wikipedia.org/w/index.php?title=Apple&oldid=123456",
+)
+
+print(result.dbname)       # enwiki
+print(result.revision)     # 123456
+print(result.interwiki)    # w:en:Special:PermanentLink/123456
+```
+
+A leading colon changes MediaWiki's special handling for some links, but it does not necessarily change the destination. For example, `[[en:Apple]]` and `[[:en:Apple]]` both point to English Wikipedia's `Apple` page; the leading-colon form is used when the link should be shown as a normal link in the page.
+
+## Local and external links
+
+Local links are resolved when a source wiki is available:
+
+```python
+result = wmlinksfromhell.resolve(
+    "[[Apple]]",
+    source="enwiki",
+)
+
+print(result.dbname)       # enwiki
+print(result.title)        # Apple
+```
+
+Ordinary external URLs are kept as external destinations:
+
+```python
+result = wmlinksfromhell.resolve("https://example.org/page")
+
+print(result.is_external)
+print(result.url)
+```
+
+## Finding links
+
+`filter_links()` can select links by the things you care about:
+
+```python
+code.filter_links(dbname="enwiki")
+code.filter_links(family="wikipedia", language="en")
+code.filter_links(namespace="MediaWiki")
+code.filter_links(hostname="en.wikipedia.org")
+
+code.filter_links(wiki_only=True)
+code.filter_links(interwiki_only=True)
+code.filter_links(local_only=True)
+code.filter_links(external_only=True)
+```
+
+Links inside HTML comments are ignored by default. Include them when needed:
+
+```python
+code.filter_links(comment_links=True)
+```
+
+## Working with a link
+
+Links expose both the original link and its resolved destination:
+
+```python
+for link in code.filter_links():
+    print(link.original)
+    print(link.dbname)
+    print(link.title)
+    print(link.interwiki)
+    print(link.url)
+    print(link.destination)
+```
+
+Links can also be matched and converted:
+
+```python
+link.matches(dbname="enwiki", title="Apple")
+
+link.set_url()
+link.set_interwiki()
+link.set_local(source="enwiki")
+```
+
+## Pywikibot
+
+When Pywikibot is installed, a `Page` can be passed directly to `parse_page()`:
+
+```python
+import pywikibot
+import wmlinksfromhell
+
+site = pywikibot.Site("en", "wikipedia")
+page = pywikibot.Page(site, "Apple")
+
+code = wmlinksfromhell.parse_page(page)
+
+for link in code.filter_links():
+    print(link.original, link.url)
+```
+
+## Metadata
+
+Wikimedia SiteMatrix and interwiki metadata can be loaded and cached locally. The lower-level `MetadataStore`, `Resolver`, and `Destination` APIs are available when you need more control.
+
+See the [API Reference](https://wmlinksfromhell.readthedocs.io/en/latest/api-reference/) for the full API.

wmlinksfromhell-0.1.0/README.md

@@ -0,0 +1,201 @@
+# wmlinksfromhell
+
+[![CI](https://github.com/MadMaxWP/wmlinksfromhell/actions/workflows/ci.yml/badge.svg)](https://github.com/MadMaxWP/wmlinksfromhell/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/wmlinksfromhell.svg)](https://pypi.org/project/wmlinksfromhell/)
+[![Python](https://img.shields.io/pypi/pyversions/wmlinksfromhell.svg)](https://pypi.org/project/wmlinksfromhell/)
+[![Downloads](https://img.shields.io/pypi/dm/wmlinksfromhell.svg)](https://pypi.org/project/wmlinksfromhell/)
+[![License](https://img.shields.io/github/license/MadMaxWP/wmlinksfromhell.svg)](https://github.com/MadMaxWP/wmlinksfromhell/blob/main/LICENSE)
+[![Repo Size](https://img.shields.io/github/repo-size/MadMaxWP/wmlinksfromhell.svg)](https://github.com/MadMaxWP/wmlinksfromhell)
+
+**wmlinksfromhell** is a Python package for working with links on Wikimedia and other MediaWiki sites. It is mainly focused on Wikimedia interwiki links, language and project prefixes, and Wikimedia URLs, with support for local links and external URLs too.
+
+It can resolve links to their destination wiki and page, convert them between interwiki and URL forms, and give you the details you need to work with them in your code.
+
+Developed by [Max](https://github.com/MadMaxWP).
+
+Full documentation is available on [Read the Docs](https://wmlinksfromhell.readthedocs.io/en/latest/). Development takes place on [GitHub](https://github.com/MadMaxWP/wmlinksfromhell), and bugs and feature requests can be reported in the [issue tracker](https://github.com/MadMaxWP/wmlinksfromhell/issues).
+
+## Project links
+
+- [Documentation](https://wmlinksfromhell.readthedocs.io/en/latest/)
+- [API Reference](https://wmlinksfromhell.readthedocs.io/en/latest/api-reference/)
+- [Changelog](https://github.com/MadMaxWP/wmlinksfromhell/blob/main/CHANGELOG.md)
+- [Issues](https://github.com/MadMaxWP/wmlinksfromhell/issues)
+- [Repository](https://github.com/MadMaxWP/wmlinksfromhell)
+
+## Install
+
+```bash
+python3 -m pip install wmlinksfromhell
+```
+
+Pywikibot support is optional:
+
+```bash
+python3 -m pip install 'wmlinksfromhell[pywikibot]'
+```
+
+Supports Python 3.9 and newer.
+
+## Quick start
+
+Get information about a wiki:
+
+```python
+import wmlinksfromhell
+
+wiki = wmlinksfromhell.wiki("enwiki")
+
+print(wiki.language)       # en
+print(wiki.hostname)       # en.wikipedia.org
+print(wiki.page_url("Apple"))
+print(wiki.interwiki("Apple"))
+```
+
+Resolve a Wikimedia link:
+
+```python
+result = wmlinksfromhell.resolve("w:en:Apple")
+
+print(result.dbname)        # enwiki
+print(result.title)         # Apple
+print(result.url)           # https://en.wikipedia.org/wiki/Apple
+```
+
+Parse links from MediaWiki text:
+
+```python
+import wmlinksfromhell
+
+code = wmlinksfromhell.parse(
+    "[[w:en:Apple]] https://de.wikipedia.org/wiki/Berlin https://example.org/",
+    source="metawiki",
+)
+
+for link in code.filter_links():
+    print(link.original)
+    print(link.dbname, link.title, link.url)
+```
+
+The parser keeps the original way a link was written separate from the destination it resolves to. This lets you work with the same destination whether it came from an interwiki link, a wiki URL, or another supported form.
+
+## Wikimedia links
+
+The resolver understands Wikimedia language and project prefixes, including prefix chains:
+
+```text
+w:en:Apple
+wikt:simple:uppercase
+b:de:Main Page
+:de:q:Hauptseite
+:m:en:About
+:w:it:b:Wiskunde
+```
+
+It also handles Wikimedia URL forms such as article paths and `index.php`, including fragments, revisions, diffs, actions, and page IDs.
+
+For example:
+
+```python
+result = wmlinksfromhell.resolve(
+    "https://en.wikipedia.org/w/index.php?title=Apple&oldid=123456",
+)
+
+print(result.dbname)       # enwiki
+print(result.revision)     # 123456
+print(result.interwiki)    # w:en:Special:PermanentLink/123456
+```
+
+A leading colon changes MediaWiki's special handling for some links, but it does not necessarily change the destination. For example, `[[en:Apple]]` and `[[:en:Apple]]` both point to English Wikipedia's `Apple` page; the leading-colon form is used when the link should be shown as a normal link in the page.
+
+## Local and external links
+
+Local links are resolved when a source wiki is available:
+
+```python
+result = wmlinksfromhell.resolve(
+    "[[Apple]]",
+    source="enwiki",
+)
+
+print(result.dbname)       # enwiki
+print(result.title)        # Apple
+```
+
+Ordinary external URLs are kept as external destinations:
+
+```python
+result = wmlinksfromhell.resolve("https://example.org/page")
+
+print(result.is_external)
+print(result.url)
+```
+
+## Finding links
+
+`filter_links()` can select links by the things you care about:
+
+```python
+code.filter_links(dbname="enwiki")
+code.filter_links(family="wikipedia", language="en")
+code.filter_links(namespace="MediaWiki")
+code.filter_links(hostname="en.wikipedia.org")
+
+code.filter_links(wiki_only=True)
+code.filter_links(interwiki_only=True)
+code.filter_links(local_only=True)
+code.filter_links(external_only=True)
+```
+
+Links inside HTML comments are ignored by default. Include them when needed:
+
+```python
+code.filter_links(comment_links=True)
+```
+
+## Working with a link
+
+Links expose both the original link and its resolved destination:
+
+```python
+for link in code.filter_links():
+    print(link.original)
+    print(link.dbname)
+    print(link.title)
+    print(link.interwiki)
+    print(link.url)
+    print(link.destination)
+```
+
+Links can also be matched and converted:
+
+```python
+link.matches(dbname="enwiki", title="Apple")
+
+link.set_url()
+link.set_interwiki()
+link.set_local(source="enwiki")
+```
+
+## Pywikibot
+
+When Pywikibot is installed, a `Page` can be passed directly to `parse_page()`:
+
+```python
+import pywikibot
+import wmlinksfromhell
+
+site = pywikibot.Site("en", "wikipedia")
+page = pywikibot.Page(site, "Apple")
+
+code = wmlinksfromhell.parse_page(page)
+
+for link in code.filter_links():
+    print(link.original, link.url)
+```
+
+## Metadata
+
+Wikimedia SiteMatrix and interwiki metadata can be loaded and cached locally. The lower-level `MetadataStore`, `Resolver`, and `Destination` APIs are available when you need more control.
+
+See the [API Reference](https://wmlinksfromhell.readthedocs.io/en/latest/api-reference/) for the full API.

wmlinksfromhell-0.1.0/examples/comments.py

@@ -0,0 +1,20 @@
+"""read normal links or links that live inside html comments."""
+
+import wmlinksfromhell
+
+
+text = """
+<!-- [[w:en:Hidden]] -->
+[[w:en:Visible]]
+"""
+
+code = wmlinksfromhell.parse(text, source="metawiki")
+
+print("normal links:")
+for link in code.filter_links():
+    print(link.original)
+
+print()
+print("comment links:")
+for link in code.filter_links(comment_links=True, in_comment=True):
+    print(link.original)

wmlinksfromhell-0.1.0/examples/convert_links.py

@@ -0,0 +1,12 @@
+"""convert only the selected Wikimedia links in a text fragment"""
+
+import wmlinksfromhell
+
+
+text = "[[w:en:Apple|this article]] https://de.wikipedia.org/wiki/Berlin https://example.com/leave-me"
+code = wmlinksfromhell.parse(text, source="enwiki")
+
+for link in code.filter_links(family="wikipedia", language="en"):
+    link.set_interwiki()
+
+print(code)

wmlinksfromhell-0.1.0/examples/pywikibot_example.py

@@ -0,0 +1,13 @@
+"""optional Pywikibot integration"""
+
+import pywikibot
+
+import wmlinksfromhell
+
+
+site = pywikibot.Site("meta", "meta")
+page = pywikibot.Page(site, "Steward requests/Miscellaneous")
+code = wmlinksfromhell.parse(page.text, source=site)
+
+for link in code.filter_links():
+    print(link.raw, link.family, link.language, link.dbname, link.title)

wmlinksfromhell-0.1.0/examples/select_links.py

@@ -0,0 +1,19 @@
+"""select links by structure, then inspect only those links."""
+
+import wmlinksfromhell
+
+
+text = """== Requests ==
+* delete [[w:en:Apple]] because of the reason [[User:Example]]
+* delete https://de.wikipedia.org/wiki/Berlin because of the reason [[User:Example]]
+{{Request|target=[[w:fr:Paris]]}}
+"""
+
+code = wmlinksfromhell.parse(text, source="metawiki")
+
+# the parser keeps its normal structure, so scope first
+# and then decide which links are interesting.
+section = next(section for section in code.get_sections() if section.wikicode.filter_headings())
+
+for link in section.filter_links(predicate=lambda item: item.is_wikimedia):
+    print(link.raw, link.family, link.language, link.dbname, link.title)

wmlinksfromhell-0.1.0/examples/simple_api.py

@@ -0,0 +1,19 @@
+"""small examples of the simple public api."""
+
+import wmlinksfromhell
+
+
+wiki = wmlinksfromhell.wiki("enwiki")
+print(wiki.language)
+print(wiki.project)
+print(wiki.interwiki("Apple"))
+print(wiki.page_url("Apple"))
+print(wiki.link("Apple", "the fruit"))
+
+info = wmlinksfromhell.interwiki("enwiki")
+print(info.prefix)
+print(info.project)
+print(info.language)
+
+print(wmlinksfromhell.url("dewiki", "Apfel"))
+print(wmlinksfromhell.link("dewiki", "Apfel", "Apfel"))

wmlinksfromhell-0.1.0/examples/sitematrix.py

@@ -0,0 +1,25 @@
+"""print the canonical interwiki target and url for every SiteMatrix wiki."""
+
+import wmlinksfromhell as wm
+
+
+TITLE = "MediaWiki:Gadget:Xtools.js"
+
+metadata = wm.Metadata()
+metadata.update_sitematrix()
+
+for wiki in sorted(metadata.all_wikis(), key=lambda item: item.dbname):
+    info = metadata.interwiki(wiki.dbname)
+
+    if info is None:
+        print(f"{wiki.dbname} → [NO PREFIX]")
+        continue
+
+    try:
+        target = info.target(TITLE)
+        url = wiki.page_url(TITLE, metadata=metadata)
+    except Exception as error:
+        print(f"{wiki.dbname} → {info.prefix}: ERROR {error}")
+        continue
+
+    print(f"{wiki.dbname} → {target} - {url}")

wmlinksfromhell-0.1.0/mkdocs.yml

@@ -0,0 +1,25 @@
+site_name: wmlinksfromhell
+site_description: Wikimedia interwiki and MediaWiki link tools for Python.
+site_url: !ENV READTHEDOCS_CANONICAL_URL
+repo_name: MadMaxWP/wmlinksfromhell
+repo_url: https://github.com/MadMaxWP/wmlinksfromhell
+
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - navigation.top
+    - navigation.indexes
+    - search.highlight
+    - content.code.copy
+
+nav:
+  - Home: index.md
+  - API Reference: api-reference.md
+  - Changelog: changelog.md
+
+markdown_extensions:
+  - toc:
+      permalink: true
+  - tables
+  - fenced_code