Skip to content

Commit 7baf185

Browse files
martin-majlisclaude
martin-majlis
and
claude
authored
Rewrite SKILLS/ as flat Markdown reference files and extend examples (#552)
* Update skills * Add CLI example script Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Remove obsolete verify-skills make targets and scripts Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Remove verify-skills step from CI workflow Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 987a256 commit 7baf185

35 files changed

Lines changed: 1425 additions & 1497 deletions

‎.github/workflows/code-quality.yml‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -169,9 +169,6 @@ jobs:
169169
- name: Install dependencies
170170
run: |
171171
make requirements-all
172-
- name: Verify skills
173-
run: |
174-
make verify-skills
175172
- name: Validate attributes mapping
176173
run: |
177174
make run-validate-attributes-mappping

‎Makefile‎

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ BUILDDIR = _build
1212
help:
1313
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
1414

15-
.PHONY: help Makefile verify-skills verify-skills-sh run-type-check run-tests extract-vcr-json
15+
.PHONY: help Makefile run-type-check run-tests extract-vcr-json
1616

1717
process-readme:
1818
awk '/^.. PYPI-BEGIN$$/,/^.. PYPI-END$$/ {next} {print}' README.rst > README_processed.rst
@@ -42,14 +42,6 @@ run-test-cli-record:
4242
run-tests-cli-unit:
4343
uv run pytest tests/cli_test.py -v
4444

45-
verify-skills:
46-
@echo "Verifying all SKILLS code samples..."
47-
uv run scripts/verify_skills.py
48-
49-
verify-skills-sh:
50-
@echo "Verifying all SKILLS code samples..."
51-
./scripts/verify-skills.sh
52-
5345
extract-vcr-json:
5446
@echo "Extracting JSON responses from VCR cassettes..."
5547
uv run python scripts/extract_vcr_json.py --overwrite
@@ -107,7 +99,7 @@ update-pre-commit:
10799
uv run pre-commit autoupdate --repo "$${repo}"; \
108100
done;
109101

110-
pre-release-check: run-pre-commit run-type-check run-ruff run-coverage run-tox run-example-sync run-example-async run-validate-attributes-mappping verify-skills
102+
pre-release-check: run-pre-commit run-type-check run-ruff run-coverage run-tox run-example-sync run-example-async run-validate-attributes-mappping
111103
echo "Pre-release check was successful"
112104

113105
release: requirements-build process-readme pre-release-check

‎SKILLS/README.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Wikipedia-API
2+
3+
Python wrapper for the [MediaWiki API](https://www.mediawiki.org/wiki/API:Main_page).
4+
Provides both synchronous (`Wikipedia`) and asynchronous (`AsyncWikipedia`) clients.
5+
6+
## Installation
7+
8+
```bash
9+
pip install wikipedia-api
10+
```
11+
12+
## Client Initialization
13+
14+
```python
15+
import wikipediaapi
16+
17+
# Basic client — English Wikipedia, plain-text extract format
18+
wiki = wikipediaapi.Wikipedia(
19+
user_agent="MyProject/1.0 (contact@example.com)",
20+
language="en"
21+
)
22+
23+
# HTML extract format (summary and section text returned as HTML fragments)
24+
wiki_html = wikipediaapi.Wikipedia(
25+
user_agent="MyProject/1.0 (contact@example.com)",
26+
language="cs",
27+
extract_format=wikipediaapi.ExtractFormat.HTML,
28+
)
29+
30+
# Forward extra parameters to every API request (e.g. auto-follow redirects)
31+
wiki_extra = wikipediaapi.Wikipedia(
32+
user_agent="MyProject/1.0 (contact@example.com)",
33+
language="en",
34+
extra_api_params={"redirects": "1"},
35+
)
36+
37+
# Async client — same options, use AsyncWikipedia instead
38+
wiki_async = wikipediaapi.AsyncWikipedia(
39+
user_agent="MyProject/1.0 (contact@example.com)",
40+
language="en"
41+
)
42+
```
43+
44+
> **User-Agent is required.** MediaWiki blocks requests without a descriptive
45+
> `User-Agent`. Use the format `AppName/Version (contact)`.
46+
47+
## Quick Start
48+
49+
```python
50+
import wikipediaapi
51+
52+
wiki = wikipediaapi.Wikipedia(
53+
user_agent="MyProject/1.0 (contact@example.com)",
54+
language="en"
55+
)
56+
57+
page = wiki.page("Python (programming language)")
58+
if page.exists():
59+
print(page.title)
60+
print(page.summary[:200])
61+
```
62+
63+
---
64+
65+
## Further Reading
66+
67+
- [python-sync.md](python-sync.md) — Full synchronous API reference with examples
68+
- [python-async.md](python-async.md) — Full asynchronous API reference with examples
69+
- [bash.md](bash.md) — CLI command reference with examples

‎SKILLS/bash.md‎

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
# Wikipedia-API — CLI (Bash)
2+
3+
The `wikipedia-api` CLI is installed automatically with the package.
4+
5+
Full working example: [`examples/example_cli.sh`](../examples/example_cli.sh)
6+
7+
---
8+
9+
## Installation
10+
11+
```bash
12+
pip install wikipedia-api
13+
wikipedia-api --version
14+
```
15+
16+
---
17+
18+
## Global Options
19+
20+
Every command accepts these options:
21+
22+
| Option | Description | Default |
23+
| ---------------------- | ----------------------------------------------- | ------- |
24+
| `-l, --language` | Wikipedia language edition | `en` |
25+
| `-u, --user-agent` | HTTP User-Agent string | — |
26+
| `-v, --variant` | Language variant (e.g. `zh-cn`, `zh-tw`) | — |
27+
| `-f, --extract-format` | Extract format: `wiki` or `html` | `wiki` |
28+
| `-n, --namespace` | Wikipedia namespace number | `0` |
29+
| `--max-retries` | Max retry attempts (0 to disable) | `3` |
30+
| `--retry-wait` | Base wait between retries (exponential backoff) | `1.0` |
31+
| `--json` | Output as JSON | — |
32+
| `-h, --help` | Show help | — |
33+
34+
```bash
35+
# Show all available commands
36+
wikipedia-api --help
37+
38+
# Show help for a specific command
39+
wikipedia-api summary --help
40+
```
41+
42+
---
43+
44+
## Page Metadata
45+
46+
```bash
47+
# Show page info (pageid, fullurl, editurl, length, lastrevid, etc.)
48+
wikipedia-api page "Python (programming language)"
49+
50+
# JSON output — includes all info attributes
51+
wikipedia-api page "Python (programming language)" --json
52+
53+
# Missing page — pageid will be -1 in JSON output
54+
wikipedia-api page "Wikipedia-API-FooBar-DoesNotExist" --json
55+
```
56+
57+
---
58+
59+
## Summary
60+
61+
```bash
62+
wikipedia-api summary "Python (programming language)"
63+
64+
# Summary in Czech
65+
wikipedia-api summary "Ostrava" --language cs
66+
67+
# Summary in Chinese with variant
68+
wikipedia-api summary "Python" --language zh --variant zh-cn
69+
70+
# Summary as HTML
71+
wikipedia-api summary "Ostrava" --language cs --extract-format html
72+
```
73+
74+
---
75+
76+
## Full Text
77+
78+
```bash
79+
wikipedia-api text "Python (programming language)"
80+
81+
# Full text as HTML
82+
wikipedia-api text "Ostrava" --language cs --extract-format html
83+
```
84+
85+
---
86+
87+
## Sections
88+
89+
```bash
90+
# List the full section hierarchy
91+
wikipedia-api sections "Python (programming language)"
92+
93+
wikipedia-api sections "Python (programming language)" --json
94+
95+
# Print the text of a specific section
96+
wikipedia-api section "Python (programming language)" "Features and philosophy"
97+
```
98+
99+
---
100+
101+
## Language Links
102+
103+
```bash
104+
wikipedia-api langlinks "Python (programming language)"
105+
106+
wikipedia-api langlinks "Python (programming language)" --json
107+
```
108+
109+
---
110+
111+
## Links and Backlinks
112+
113+
```bash
114+
wikipedia-api links "Python (programming language)"
115+
116+
wikipedia-api links "Python (programming language)" --json
117+
118+
wikipedia-api backlinks "Python (programming language)"
119+
120+
wikipedia-api backlinks "Python (programming language)" --json
121+
```
122+
123+
---
124+
125+
## Categories and Category Members
126+
127+
```bash
128+
wikipedia-api categories "Python (programming language)"
129+
130+
wikipedia-api categories "Python (programming language)" --json
131+
132+
# List pages in a category
133+
wikipedia-api categorymembers "Category:Physics"
134+
135+
# Recursively include subcategory members (depth 1)
136+
wikipedia-api categorymembers "Category:Physics" --max-level 1
137+
138+
wikipedia-api categorymembers "Category:Physics" --json
139+
```
140+
141+
---
142+
143+
## Language Variants
144+
145+
```bash
146+
# Default script
147+
wikipedia-api summary "Python" --language zh
148+
149+
# Simplified Chinese
150+
wikipedia-api summary "Python" --language zh --variant zh-cn
151+
152+
# Traditional Chinese
153+
wikipedia-api summary "Python" --language zh --variant zh-tw
154+
155+
# Singapore Simplified Chinese
156+
wikipedia-api summary "Python" --language zh --variant zh-sg
157+
```
158+
159+
---
160+
161+
## Coordinates
162+
163+
```bash
164+
# Primary coordinate only (default)
165+
wikipedia-api coordinates "London"
166+
167+
# All coordinates (primary + secondary)
168+
wikipedia-api coordinates "London" --primary all
169+
170+
wikipedia-api coordinates "London" --json
171+
172+
wikipedia-api coordinates "Mount Everest"
173+
```
174+
175+
---
176+
177+
## Images and Image Metadata
178+
179+
```bash
180+
# List image titles used on a page
181+
wikipedia-api images "Python (programming language)"
182+
183+
wikipedia-api images "Python (programming language)" --json
184+
185+
# Fetch metadata (URL, dimensions, MIME type, uploader, timestamp, etc.)
186+
wikipedia-api images "Mount Everest" --imageinfo
187+
188+
wikipedia-api images "Mount Everest" --imageinfo --json
189+
190+
# Limit number of images
191+
wikipedia-api images "Earth" --limit 20 --imageinfo
192+
```
193+
194+
---
195+
196+
## Geosearch
197+
198+
```bash
199+
# Search near a coordinate (London city centre)
200+
wikipedia-api geosearch --coord "51.5074|-0.1278"
201+
202+
# Limit radius and result count
203+
wikipedia-api geosearch --coord "51.5074|-0.1278" --radius 1000 --limit 5
204+
205+
# Search near a named page
206+
wikipedia-api geosearch --page "Big Ben" --radius 1000
207+
208+
wikipedia-api geosearch --coord "48.8566|2.3522" --json
209+
```
210+
211+
---
212+
213+
## Random Pages
214+
215+
```bash
216+
wikipedia-api random
217+
218+
wikipedia-api random --limit 3
219+
220+
wikipedia-api random --limit 3 --json
221+
```
222+
223+
---
224+
225+
## Search
226+
227+
```bash
228+
wikipedia-api search "Python programming"
229+
230+
wikipedia-api search "Python programming" --limit 5
231+
232+
wikipedia-api search "Python programming" --json
233+
234+
# Search in another language
235+
wikipedia-api search "машинное обучение" --language ru
236+
```
237+
238+
---
239+
240+
## Retry Configuration
241+
242+
```bash
243+
# Custom retry settings
244+
wikipedia-api summary "Python (programming language)" --max-retries 5 --retry-wait 2.0
245+
246+
# Disable retries entirely (fail fast on first error)
247+
wikipedia-api search "Python" --max-retries 0
248+
249+
# Aggressive retrying for unreliable connections
250+
wikipedia-api geosearch --coord "27.9881|86.9250" --max-retries 10 --retry-wait 3.0
251+
```
252+
253+
---
254+
255+
## Complete Workflow Example
256+
257+
```bash
258+
UA="MyProject/1.0 (contact@example.com)"
259+
260+
# Explore a page from multiple angles
261+
wikipedia-api summary "Python (programming language)" --user-agent "$UA"
262+
wikipedia-api sections "Python (programming language)" --user-agent "$UA"
263+
wikipedia-api section "Python (programming language)" "History" --user-agent "$UA"
264+
wikipedia-api categories "Python (programming language)" --user-agent "$UA"
265+
wikipedia-api langlinks "Python (programming language)" --user-agent "$UA"
266+
267+
# Follow a language link to German Wikipedia
268+
wikipedia-api summary "Python (Programmiersprache)" --language de --user-agent "$UA"
269+
270+
# Geographic pages
271+
wikipedia-api coordinates "Mount Everest" --user-agent "$UA"
272+
wikipedia-api geosearch --coord "27.9881|86.9250" --radius 5000 --user-agent "$UA"
273+
wikipedia-api images "Mount Everest" --imageinfo --user-agent "$UA"
274+
275+
# Discovery
276+
wikipedia-api random --limit 3 --user-agent "$UA"
277+
wikipedia-api search "Mount Everest" --limit 5 --user-agent "$UA"
278+
```

0 commit comments

Comments
 (0)