How urbanogilson/sicar works
Project type and purpose
• Type: Open-source Python package (library + CLI/entry-points)
• Purpose: Automate the download of Brazilian land-registry (CAR) data, optionally solving CAPTCHAs via OCR drivers, and saving results as files.
Main components
A. Client / Entry Points
– Examples / CLI (examples/colab.ipynb, examples/docker.py)
– Docker Image & DevContainer
B. Core Library (package SICAR/)
1. Sicar (SICAR/sicar.py) – orchestrator, public API
2. State & Polygon (SICAR/state.py, SICAR/polygon.py) – enums for data scoping
3. URL Builder (SICAR/url.py) – constructs HTTP endpoints
4. Drivers (SICAR/drivers/*.py) – abstracted OCR interfaces:
• Tesseract driver
• PaddleOCR driver
5. Exceptions (SICAR/exceptions.py) – error handling
C. Data Layer
– File System I/O (writes downloaded ZIPs, polygons, states)
D. External Services
1. CAR Public Website REST endpoints
2. Google Tesseract OCR Engine (optional)
3. PaddleOCR Engine (optional)
4. Docker Hub (for container image)
Relationships & data flow
• The user invokes SICAR via Python code, notebook, or Docker.
• Sicar class calls URL Builder to generate request URLs.
• HTTP requests go to the CAR website.
• When a CAPTCHA is returned, Sicar delegates to the configured OCR Driver (Tesseract or Paddle).
• The chosen Driver calls into the external OCR engine, returns the recognized text.
• Sicar retries the HTTP request with CAPTCHA solution; once successful, it streams or downloads data.
• Downloaded files are written to the local file system.
• All components raise or catch custom exceptions where needed.
Architectural patterns & design principles
• Modular design: separation of concerns between orchestration (Sicar), URL generation, OCR drivers, and file I/O.
• Strategy pattern: interchangeable OCR drivers via a common interface.
• Single responsibility: each module focuses on one aspect (parsing, HTTP, OCR, FS).
• Dependency inversion for OCR: Sicar depends on abstract driver, not concrete implementations.
Essential elements
• Clear component names (e.g., “Sicar (core)”, “URL Builder”, “Tesseract Driver”).
• Annotations for protocols (HTTP, local FS, OCR engines).