How cityofaustin/knackpy works
Project Type and Purpose
• Project Type: A Python client library (SDK) for interacting with an external REST service (Knack).
• Purpose: Expose Knack’s application, record, field, and model operations through a clean, object-oriented Python API.
File Structure
• Top-level:
• knackpy/ ← main Python package
– api.py ← HTTP client wrapper
– app.py ← high-level orchestration of endpoints
– record.py, models.py, fields.py, formatters.py, utils.py ← domain objects & helpers
• tests/ ← unit tests for each module
• docs/ ← generated documentation site
• .github/workflows ← CI/CD pipelines (build, test, PyPI release)
• setup.py, requirements/ ← packaging & dependencies
README Insights
• Confirms it’s a client library (“Python client for interacting with Knack”).
• Mentions user-guide, API reference, and developer-guide—indicating extensive docs but not additional runtime components.
Main Components
a. Knackpy Package
– API Layer (api.py): constructs HTTP requests, handles authentication
– App Layer (app.py): offers high-level methods e.g., get_record, create_app
– Domain Models:
• Record (record.py)
• Model (models.py)
• Field (fields.py)
– Formatters (formatters.py): serialize/deserialize payloads
– Utilities (utils.py): shared helpers (e.g., URL builders, validation)
b. External Service
– Knack REST API (over HTTPS)
c. Development Support
– Tests (pytest suite)
– CI/CD (GitHub Actions workflows)
– Packaging (setup.py → PyPI)
Relationships and Data Flow
• The client application (your Python code that imports knackpy) calls App Layer methods.
• App Layer delegates to API Layer to send HTTP requests to Knack endpoints.
• API Layer returns raw JSON, passed through Formatters to construct Domain Models.
• Domain Models are returned to the caller; Utils may be invoked throughout.
• Tests invoke each module in isolation (unit tests).
• On merge, workflows run tests → build documentation → publish to PyPI.
Architectural Patterns & Design Principles
• Layered Architecture: clear separation between transport (API layer), business logic (App layer), and data models.
• Single Responsibility per module: each file/module focuses on one concern.
• Dependency Injection: API Layer can be mocked in tests.
• Modular & Extensible: new endpoints/formatters can be added without touching core logic.
Essential Elements
• Clear component names matching filenames (api.py, app.py, record.py, etc.).
• Annotations for external dependencies (requests library, PyPI, GitHub Actions).