How lclc-data-team/neon_queries works
Project Type and Purpose
• This is an open-source Python library (package name: suave_sql, project documented as “neon_queries”).
• It provides two main modules:
• sql_funcs.py – utilities to construct or run SQL queries
• reporting_funcs.py – higher-level reporting workflows (e.g., build tables, run examples)
• It includes Sphinx‐based documentation, unit tests, and a CI workflow to build and publish docs.
Key Components and Directory Structure
• Code Package (suave_sql/)
• __init__.py
• sql_funcs.py
• reporting_funcs.py
• Tests (tests/)
• Python tests and Jupyter notebooks (report_examples.ipynb)
• Documentation (docs/)
• docs/source/ – Sphinx source: .rst, conf.py, helper scripts (generate_table.py)
• docs/build/ – built HTML site (to be published)
• Configuration & Tooling
• pyproject.toml & requirements.txt – define dependencies and build metadata
• .github/workflows/SphinxBuild.yml – CI pipeline to build docs on push
• README (README.md) points to the project’s published docs site
Relationships and Data Flows
• Developer commits → GitHub repo → GitHub Actions triggers →
• Runs Sphinx build → outputs static HTML → published to GitHub Pages
• (Optionally) Runs tests against suave_sql code
• pyproject.toml + source files → packaging tool (e.g., poetry or pip) → releases on PyPI
• End user installs package via pip → imports suave_sql → uses sql_funcs & reporting_funcs → (internally) connects to external database services
Architectural Patterns & Design Principles
• Modular design: clear separation of core SQL utilities vs. reporting logic
• Documentation-as-code: Sphinx sources alongside code, with CI publishing
• Test-driven components: unit tests and example notebooks
• Standard Python packaging (PEP 517/518)
Step-by-Step Composition
b. From it, branch to two CI nodes: “Docs Build” and “Test Suite.”
c. “Docs Build” → output to “GitHub Pages.”
d. “Package Build” (from repo) → “PyPI Registry” → “End User Environment.”
• suave_sql.sql_funcs
• suave_sql.reporting_funcs
g. A side area for “docs/source” feeding into Sphinx → “docs/build/html.”