How duelitdev/ezneis works
Project type and purpose
• ezneis is an open‑source Python client library (wrapper) for the NEIS Open API, providing both synchronous and asynchronous interfaces.
• Its goal is to fetch school data (info, schedules, meals, etc.) from the NEIS REST endpoints, parse it into rich Python objects, and support lazy loading, caching, and session management.
File structure
Top‑level:
• ezneis/ # Main package
– __init__.py # Entry points (get_school, get_schools, async variants)
– data/ # Domain orchestrators for each API category (school, synchronous vs asynchronous)
– http/ # HTTP clients and common code for sync (requests) and async (aiohttp)
– parsers/ # Routines to parse JSON/XML responses into primitive dicts
– models/ # Domain model classes (SchoolInfo, Schedule, Meal, etc.)
– utils/ # Caching, region lookup, session manager (shared state, lazy loading)
– wrappers/ # High‑level facade functions for sync and async
– exceptions.py # Custom error types
• tests/ # Unit tests for wrappers
• build.sh, pyproject.toml, requirements.txt
Key insights from README
• Dual‑mode operation (sync & asyncio).
• All data parsed into appropriate types.
• Lazy loading: data attributes load only when accessed.
• Dependencies: requests (sync), aiohttp (+ aiodns optional).
a. Main components:
1. User Application
2. Sync Wrapper Layer (ezneis.wrappers.synchronous)
3. Async Wrapper Layer (ezneis.wrappers.asynchronous)
4. Data Orchestrators (ezneis.data.school, common logic for each domain)
5. HTTP Client Modules
– Sync HTTP (ezneis.http.synchronous using requests)
– Async HTTP (ezneis.http.asynchronous using aiohttp)
6. Parser Modules (ezneis.parsers.*)
7. Domain Models (ezneis.models.*)
8. Utilities
– Session Manager
– Caches
– Region Resolver
9. External NEIS Open API Endpoint
10. Exceptions (error handling path)
b. Relationships & interactions:
• The User calls get_* or get_*_async (Wrapper Layer).
• The Wrapper calls the Data Orchestrator for the requested domain (e.g., school).
• The Orchestrator uses the appropriate HTTP Client (sync vs async) to send requests to the NEIS API.
• HTTP responses flow back to the orchestrator, which invokes Parser modules to convert raw payload to Python primitives.
• Parsed data is instantiated into Domain Models.
• Lazy attributes trigger more HTTP calls via Utilities (Session Manager & Caches) as needed.
• Exceptions raised at any stage bubble up to the user.
c. Architectural patterns & principles:
• Facade Pattern: wrappers provide a simple API hiding complexity.
• Strategy Pattern: sync vs async HTTP strategies.
• Lazy Loading: models defer sub‑resource fetch until property access.
• Separation of Concerns: HTTP, parsing, modeling, caching are modular.
d. Key technologies & libraries:
• requests for synchronous HTTP
• aiohttp (plus optional aiodns) for asynchronous HTTP
• asyncio for event loop and coroutines
• pytest for testing