{"id":49569977,"url":"https://github.com/pfei/hubeau-py","last_synced_at":"2026-05-03T13:13:53.429Z","repository":{"id":295065900,"uuid":"986843439","full_name":"pfei/hubeau-py","owner":"pfei","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-10T15:34:40.000Z","size":102,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-10T17:32:20.378Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pfei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-20T07:50:10.000Z","updated_at":"2025-06-10T15:39:43.000Z","dependencies_parsed_at":"2025-06-10T17:36:52.391Z","dependency_job_id":null,"html_url":"https://github.com/pfei/hubeau-py","commit_stats":null,"previous_names":["pfei/hubeau-py"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pfei/hubeau-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfei%2Fhubeau-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfei%2Fhubeau-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfei%2Fhubeau-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfei%2Fhubeau-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pfei","download_url":"https://codeload.github.com/pfei/hubeau-py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfei%2Fhubeau-py/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32570015,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-03T13:13:37.939Z","updated_at":"2026-05-03T13:13:53.417Z","avatar_url":"https://github.com/pfei.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e ⚠️ **Pre-Alpha Notice**\n\u003e\n\u003e This project is in a **very early, pre-alpha state**.  \n\u003e The goal is to become a solid, typed, and reference Python client for the Hubeau APIs.\n\u003e Expect rapid changes, breaking updates, and incomplete coverage.\n\u003e Contributions, feedback, and issue reports are very welcome!\n\n# hubeau-py\n\nPythonic, typed, and modern client for the Hubeau water data APIs.\n\n## API Coverage and Status\n\n| API Name              | Status             | Notes                                                                                                                                                                                               |\n| --------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Qualité Rivières**  | ⚠️ Limited Support | Initial implementation with known limitations. API has pagination issues and high error rates (~60%) when querying large datasets. Best used for targeted queries rather than bulk data extraction. |\n| **Hydrologie**        | 🚧 In Progress     | Currently being implemented.                                                                                                                                                                        |\n| **Other Hubeau APIs** | 📅 Planned         | Will be added in future releases.                                                                                                                                                                   |\n\n\u003e **Note on Qualité Rivières API:**  \n\u003e Our exploration revealed significant rate limiting and stability issues when attempting exhaustive data extraction. The API works well for targeted queries but may not be suitable for comprehensive data analysis across all stations. See the `scripts/qualite_rivieres/` directory for exploration tools and findings.\n\n## Features\n\n- Typed, Pythonic client for the Hubeau water data APIs\n- Easy querying of water quality and station data\n- Returns results as Pydantic models for type safety\n- Ready for use in data science workflows (e.g., with pandas)\n\n## Development Model\n\n- Modern Python (**3.13+**)\n- Strict typing throughout the codebase\n- [Poetry](https://python-poetry.org/) for dependency and environment management\n- Linting, formatting, and type checking enforced (ruff, black, mypy)\n- Follows the [src-layout](https://realpython.com/python-application-layouts/) for package structure\n\n## Quickstart\n\n```python\nfrom hubeau_py.client import HubeauClient\nclient = HubeauClient()\nstations = client.get_stations(\"Paris\") # Example: get stations by name for the Qualité Rivières API\nprint(stations)\n```\n\n## Example Notebook\n\nA continuously updated example notebook is available in [`examples/demo.ipynb`](examples/demo.ipynb).\n\n- This notebook demonstrates the main features of `hubeau-py` and provides practical usage examples.\n- You can run it locally using Jupyter Notebook or JupyterLab:\n\n```\n$ poetry run jupyter notebook examples/demo.ipynb\n```\n\nor, after activating the virtual environment:\n\n```\n$ jupyter notebook examples/demo.ipynb\n```\n\n- The notebook should be expanded as new functionalities are added to the package.\n\nFor more about Jupyter, see the [official documentation](https://jupyter.org/documentation).\n\n## Development\n\n- Install dependencies:\n\n```\n$ poetry install\n```\n\n- Run tests:\n\n```\n$ poetry run pytest\n```\n\n- Lint code:\n\n```\n$ poetry run ruff check src/\n```\n\n- Format code:\n\n```\n$ poetry run black src/\n```\n\n- Type check:\n\n```\n$ poetry run mypy src/\n```\n\n## How Imports Work\n\nThis project uses the [src-layout](https://realpython.com/python-application-layouts/) and [Poetry](https://python-poetry.org/) for dependency and environment management.\n\nWhen you run:\n\n```\n$ poetry install\n```\n\nPoetry installs your package in **editable mode** (like `pip install -e .`).  \nThis means you can import your code from anywhere in the project, including notebooks and tests, using:\n\n```python\nfrom hubeau_py.client import HubeauClient\n```\n\n**You must always run code (scripts, notebooks, tests) in the Poetry environment** so that imports work correctly:\n\n### Recommended: Poetry Commands\n\n- For notebooks:\n  - Launch with `poetry run jupyter notebook` or select the `.venv` interpreter in VS Code.\n- For tests:\n  - Run with `poetry run pytest`\n- For scripts:\n  - Run with `poetry run python your_script.py`\n- Or enter a Poetry-managed shell: `poetry shell`\n  and now run: python, pytest, etc.\n\n### Alternative: Activate the Virtual Environment Manually\n\nIf you prefer, you can activate the `.venv` directly (for example, in a terminal or before launching Jupyter/VS Code):\n\n```\n$ source .venv/bin/activate\n```\n\nOnce activated, any Python or pip command will use the project environment.\n\n\u003e **Note:**  \n\u003e Whether you use `poetry run ...`, `poetry shell`, or activate `.venv` directly, you’re using the same environment managed by Poetry.  \n\u003e This ensures all imports (like `from hubeau_py.client import HubeauClient`) work as expected in scripts, tests, and notebooks.\n\n\u003e **Windows users:**  \n\u003e It is recommended to use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/) for a smoother Unix-like experience.  \n\u003e If you prefer native Windows, you will need to adapt the commands and environment activation steps to your setup.\n\nFor more, see the [Poetry documentation](https://python-poetry.org/docs/basic-usage/).\n\n## VS Code Users\n\nA `.vscode/settings.json` is included to provide a consistent development environment for VS Code users:\n\n- Automatically uses the Poetry-managed virtual environment\n- Formats code on save with Black\n- Organizes imports on save\n- Runs mypy type checking with the correct interpreter\n\nFeel free to adjust these settings for your personal workflow if needed.\n\n\u003e **Customizing VS Code settings**\n\u003e\n\u003e The `.vscode/settings.json` file in this repository provides recommended project settings for all contributors.\n\u003e\n\u003e If you want to adjust these settings for your personal workflow **without affecting version control**, you can:\n\u003e\n\u003e - **Override settings in your personal (user) settings:**  \n\u003e   Open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`), type `Preferences: Open User Settings (JSON)`, and add your overrides there.  \n\u003e   User settings take precedence over workspace settings for most editor preferences.\n\u003e\n\u003e - **Avoid committing unintended changes:**  \n\u003e   If you do change `.vscode/settings.json`, double-check with `git status` before committing, and use `git restore .vscode/settings.json` to undo accidental edits.\n\u003e\n\u003e For more details, see the [VS Code documentation on settings](https://code.visualstudio.com/docs/configure/settings).\n\n## Inspect Scripts\n\nScripts for exploring and inspecting the Hubeau APIs are organized by API in the `scripts/` directory. For example:\n\n- **qualite_rivieres/**: Scripts for the \"Qualité Rivières\" API.\n  - `explore.py`: Interactive exploration of the API.\n  - `inspect_*.py`: Inspection scripts for specific endpoints and models.\n  - `check_undocumented_fields.py`: Checks for undocumented fields in API responses.\n\n**Usage:**\n\n```python\n$ poetry run python scripts/qualite_rivieres/inspect_station_pc.py\n$ poetry run python scripts/qualite_rivieres/inspect_operation_pc.py\n```\n\nYou can adjust the `n` parameter in each script (edit the script and change `n=10`, for example) to control how many records are fetched and inspected.\n\n\u003e **Note:**  \n\u003e As support for more Hubeau APIs is added, new subdirectories will be created under `scripts/` for each API.\n\n## License\n\nMIT License © Pierre Feilles\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfei%2Fhubeau-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpfei%2Fhubeau-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfei%2Fhubeau-py/lists"}