Scripts and Examples Reorganization (#542)

* Move scripts into separate folder

* Include examples to the package

Author: martin-majlis

.github/workflows/validate-attributes-mapping.yml

@@ -45,4 +45,4 @@ jobs:
 
       - name: Validate Attributes Mapping
         run: |
-          uv run python validate_attributes_mapping.py
+          uv run python scripts/validate_attributes_mapping.py

.gitignore

@@ -18,6 +18,13 @@ eggs/
 lib/
 lib64/
 parts/
+
+# IDE and editor files
+.DS_Store
+.claude/
+CLAUDE.md
+PR_DESCRIPTION.md
+wikipedia-api-specification
 sdist/
 var/
 *.egg-info/

ADDING_SUBMODULES.md

@@ -751,10 +751,10 @@ After implementing, update these files:
 2. **`DESIGN.rst`** — Update class diagram, dispatch helpers mapping,
    invariants section.
 
-3. **`example_sync.py`** — Add a usage example section (numbered, with
+3. **`examples/example_sync.py`** — Add a usage example section (numbered, with
    comments).
 
-4. **`example_async.py`** — Mirror the sync example with `await`.
+4. **`examples/example_async.py`** — Mirror the sync example with `await`.
 
 5. **`index.rst`** — Add a "How To" section with sync and async code blocks.
 
@@ -794,8 +794,8 @@ Fix any issues and re-run until everything passes.
 | `tests/query_submodules_test.py`       | Sync + async tests                                         |
 | `API.rst`                              | Public API reference                                       |
 | `DESIGN.rst`                           | Architecture docs                                          |
-| `example_sync.py`                      | Sync usage example                                         |
-| `example_async.py`                     | Async usage example                                        |
+| `examples/example_sync.py`             | Sync usage example                                         |
+| `examples/example_async.py`            | Async usage example                                        |
 | `index.rst`                            | User-facing docs                                           |
 
 ---

Makefile

@@ -44,15 +44,15 @@ run-tests-cli-unit:
 
 verify-skills:
 	@echo "Verifying all SKILLS code samples..."
-	uv run verify_skills.py
+	uv run scripts/verify_skills.py
 
 verify-skills-sh:
 	@echo "Verifying all SKILLS code samples..."
-	./verify-skills.sh
+	./scripts/verify-skills.sh
 
 extract-vcr-json:
 	@echo "Extracting JSON responses from VCR cassettes..."
-	uv run python extract_vcr_json.py --overwrite
+	uv run python scripts/extract_vcr_json.py --overwrite
 
 run-type-check: run-type-check-library run-type-check-tests
 
@@ -78,13 +78,13 @@ run-coverage:
 	uv run pytest --cov=wikipediaapi --cov-report=term-missing --cov-report=xml tests/
 
 run-validate-attributes-mappping:
-	uv run python ./validate_attributes_mapping.py
+	uv run python scripts/validate_attributes_mapping.py
 
 run-example-sync:
-	uv run python ./example_sync.py
+	uv run python examples/example_sync.py
 
 run-example-async:
-	uv run python ./example_async.py
+	uv run python examples/example_async.py
 
 requirements-all: process-readme
 	uv sync -v --group dev --group build --group doc

example_async.py examples/example_async.pyexample_async.py renamed to examples/example_async.py

@@ -93,8 +93,7 @@ include = [
     "API.rst",
     "CLI.rst",
     "pyproject.toml",
-    "example_sync.py",
-    "example_async.py",
+    "examples/**",
     "SKILLS/**/*.py",
     "SKILLS/**/*.sh",
     "SKILLS/**/*.md",

example_sync.py examples/example_sync.pyexample_sync.py renamed to examples/example_sync.py

@@ -9,10 +9,10 @@ This directory contains example code samples demonstrating various Wikipedia-API
 make verify-skills-sh
 
 # Or run directly
-./verify-skills.sh
+./scripts/verify-skills.sh
 
 # Or run Python script directly
-uv run verify_skills.py
+uv run scripts/verify_skills.py
 ```
 
 ## What Gets Verified

pyproject.toml

@@ -12,16 +12,16 @@ VCR cassettes store HTTP responses as escaped JSON strings in `interactions[].re
 
 ```bash
 # Use default directories (tests/cassettes -> tests/cassettes-json)
-python extract_vcr_json.py
+python scripts/extract_vcr_json.py
 
 # Custom directories
-python extract_vcr_json.py --input-dir my-cassettes --output-dir json-output
+python scripts/extract_vcr_json.py --input-dir my-cassettes --output-dir json-output
 
 # Verbose output
-python extract_vcr_json.py --verbose
+python scripts/extract_vcr_json.py --verbose
 
 # Overwrite existing files
-python extract_vcr_json.py --overwrite
+python scripts/extract_vcr_json.py --overwrite
 ```
 
 ### Makefile Target