Metadata-Version: 2.5
Name: wiktionary-api
Version: 0.1.0
Summary: Synchronous Python client for the Wikimedia Wiktionary REST API
Project-URL: Homepage, https://github.com/NebilI/WiktionaryPythonAPI
Project-URL: Repository, https://github.com/NebilI/WiktionaryPythonAPI
Project-URL: Issues, https://github.com/NebilI/WiktionaryPythonAPI/issues
Project-URL: Documentation, https://github.com/NebilI/WiktionaryPythonAPI#readme
Author: Nebil Ibrahim
License-Expression: MIT
License-File: LICENSE
Keywords: dictionary,requests,rest-api,wikimedia,wiktionary
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pypdf2<4,>=3.0.1
Requires-Dist: requests<3,>=2.32
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

# WiktionaryPythonAPI

Synchronous Python client for the [Wiktionary REST API](https://en.wiktionary.org/api/rest_v1/#/) and related [Commons Core](https://api.wikimedia.org/wiki/Core_REST_API) media downloads.

**PyPI:** `wiktionary-api` · **Import:** `wikt`

Covers **all 41** path patterns in the live OpenAPI spec (`?spec`), plus PDF rendering and Commons helpers. See [docs/ENDPOINTS.md](docs/ENDPOINTS.md) for the full path → method map.

## Install

Works with any PEP 517 installer:

```bash
pip install wiktionary-api
```

```bash
uv add wiktionary-api
```

```bash
poetry add wiktionary-api
```

Requires **Python 3.10+**.

## Quick start

Wikimedia requires a descriptive [User-Agent](https://foundation.wikimedia.org/wiki/Policy:Wikimedia_Foundation_User-Agent_Policy) with your application name and a contact email or URL.

```python
from wikt import Wiktionary

wiki = Wiktionary("MyApp", "you@example.com")

# Definitions (Wiktionary-specific)
print(wiki.get_definition("hello"))

# HTML / revision metadata
print(wiki.get_html("hello")[:200])
print(wiki.get_revision("hello"))

# Math (check → render)
checked = wiki.check_math("tex", "E=mc^2")
svg = wiki.render_math("svg", checked["resource_location"])
```

## API surface (summary)

| Area | Examples |
|------|----------|
| Page content | `page`, `get_definition`, `get_html`, `get_lint`, `get_mobile_html`, `get_revision`, `get_media_file_list`, `get_pdf` |
| Data / mobile | `get_citation`, `get_mobile_css`, `get_mobile_javascript`, `get_i18n` |
| Reading lists | `get_lists`, `create_list`, `update_list`, `delete_list`, entry CRUD, setup/teardown |
| Transforms | `transform_wikitext_to_html`, `transform_html_to_wikitext`, `transform_wikitext_to_lint`, `transform_wikitext_to_mobile_html` |
| Math | `check_math`, `get_math_formula`, `render_math` |
| Commons helpers | `get_media_files`, `download_media_files` |

Method docstrings document parameters, return types, and REST paths. Official sandbox: https://en.wiktionary.org/api/rest_v1/#/

## Development

```bash
pip install -e ".[dev]"
# or: uv sync --all-extras
ruff check src tests
ruff format src tests
pytest tests/ -v
```

### Publishing

Releases publish to PyPI on `v*` tags via trusted publishing. See [.github/PYPI_PUBLISHING.md](.github/PYPI_PUBLISHING.md).

## License

MIT — see [LICENSE](LICENSE).
