Add API for coordinates, random, search, and geosearch

[martin-majlis]

Summary

This major update introduces strongly-typed enum parameters throughout the Wikipedia-API library, providing enhanced type safety while maintaining full backward compatibility. The implementation adds comprehensive enum support for all API string parameters, new query submodules (coordinates, geosearch, random, search), and extensive documentation improvements.

Key Features Added

🎯 Type-Safe Enum Parameters

• 11 new enum classes covering all API string parameters:
  • SearchProp, SearchInfo, SearchWhat, SearchQiProfile, SearchSort
  • GeoSearchSort, Globe, CoordinateType, CoordinatesProp
  • RedirectFilter, Direction
• Wiki type aliases* for backward compatibility (accept both enums and strings)
• Converter functions for seamless enum-to-string conversion
• Perfect sync/async symmetry maintained across all APIs

🚀 New Query Submodules

• Coordinates API: Fetch geographic coordinates with filtering options
• GeoSearch API: Search for pages by geographic location with radius filtering
• Random API: Fetch random Wikipedia pages with redirect filtering
• Search API: Enhanced search with sorting, result properties, and metadata
• Batch operations: Efficient multi-page data fetching

📚 Comprehensive Documentation

• API.rst: Complete enum parameter documentation with usage examples
• DESIGN.rst: Updated architecture diagrams and implementation patterns
• README.rst: New enum usage section and batch operation examples
• CLI.rst: Updated command-line interface documentation

🔧 Enhanced Type System

• Strong typing for all API parameters with proper type hints
• Frozen dataclasses for structured data (GeoPoint, Coordinate, SearchResults)
• Parameter validation and conversion in dedicated parameter classes
• Per-parameter caching for improved performance

Benefits

✅ Type Safety & Developer Experience

• IDE autocomplete and compile-time type checking
• No more typos in API parameter strings
• Self-documenting code with meaningful enum names
• Comprehensive type annotations throughout

✅ Backward Compatibility

• All existing string-based code continues to work unchanged
• Gradual migration path available
• Mixed enum/string usage supported
• Zero breaking changes for existing users

✅ Performance & Reliability

• Efficient batch operations for multiple pages
• Per-parameter caching reduces redundant API calls
• Proper error handling and validation
• Extensive test coverage (479 tests passing)

Usage Examples

Type-Safe Enum Usage (Recommended)

import wikipediaapi
from wikipediaapi import SearchSort, GeoSearchSort, Globe, CoordinateType

wiki = wikipediaapi.Wikipedia('MyApp/1.0', 'en')

# Search with type-safe enums
results = wiki.search("python", sort=SearchSort.RELEVANCE)

# Geographic search with enums
geo_results = wiki.geosearch(
    coord=wikipediaapi.GeoPoint(lat=51.5, lon=-0.1),
    sort=GeoSearchSort.DISTANCE,
    globe=Globe.EARTH
)

# Coordinate filtering
coords = wiki.coordinates(page, primary=CoordinateType.ALL)

Backward-Compatible String Usage (Still Works)

# All existing code continues to work
results = wiki.search("python", sort="relevance")
geo_results = wiki.geosearch(coord=point, sort="distance", globe="earth")
coords = wiki.coordinates(page, prop=["globe", "type"], primary="all")

Batch Operations

# Efficient batch fetching
pages = wiki.pages(["London", "Paris", "Berlin"])
batch_coords = pages.coordinates()
batch_images = pages.images()

Technical Implementation

🏗️ Architecture Updates

• New dispatch pattern: _dispatch_standalone_list for page-independent queries
• Parameter classes: Structured parameter handling with validation
• Type system: Comprehensive frozen dataclasses for API responses
• Caching strategy: Per-parameter caching with intelligent cache keys

📦 New Modules

• wikipediaapi/_enums.py: All enum definitions and converters
• wikipediaapi/_params.py: Parameter dataclasses and validation
• wikipediaapi/_types.py: Typed data structures
• wikipediaapi/_pages_dict.py: Batch operation support

🧪 Testing & Quality

• 479 tests passing with 94% coverage
• 20 new test files for enum functionality and edge cases
• Comprehensive CLI tests with 58/65 passing
• All pre-commit hooks passing (mypy, flake8, black, isort)

Migration Guide

For Library Users

• No immediate action required - all existing code works
• Optional migration: Replace string parameters with enums for type safety
• Gradual adoption: Mix enums and strings during transition

For Library Developers

• Use Wiki* type aliases in function signatures
• Leverage converter functions for custom API calls
• Follow established enum patterns for new parameters

Files Changed

• Core library: 15 files modified, 4 new files added
• Documentation: 4 major documentation files updated
• Tests: 25 test files updated, 5 new test files added
• CLI: 35 new expected output files for new commands
• Examples: Updated with enum usage demonstrations

[codecov]

Codecov Report

❌ Patch coverage is 91.79104% with 110 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.21%. Comparing base (f525c56) to head (60051cc).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
wikipediaapi/cli.py	77.25%	63 Missing ⚠️
wikipediaapi/_resources.py	89.31%	39 Missing ⚠️
wikipediaapi/_params.py	98.44%	3 Missing ⚠️
wikipediaapi/wikipedia_page.py	92.85%	3 Missing ⚠️
wikipediaapi/async_wikipedia_page.py	95.34%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #504      +/-   ##
==========================================
- Coverage   97.16%   94.21%   -2.96%     
==========================================
  Files          14       17       +3     
  Lines        1201     2421    +1220     
==========================================
+ Hits         1167     2281    +1114     
- Misses         34      140     +106     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.