pydmvl 0.1.0__tar.gz

pydmvl-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+## Summary
+
+<!-- What does this PR change? Link the feature spec: specs/NNNN-slug.md -->
+
+## Spec-driven checklist
+
+- [ ] Feature spec exists (`specs/NNNN-slug.md`) and has status `approved`
+- [ ] Tests written before implementation (TDD), failing first
+- [ ] API responses covered by synthetic fixtures (no live API in unit tests)
+- [ ] Live tests stay behind the `live` marker
+- [ ] `ruff check .`, `ruff format --check .`, `mypy`, `pytest -m "not live"` pass
+- [ ] Skeptic review completed: verdict `APPROVED` (or `NITS` only)
+- [ ] No secrets committed (credentials, password hashes); placeholders only
+- [ ] Logs never contain credentials or the password hash
+
+## Commit style
+
+Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `chore:`, `refactor:`).

pydmvl-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Ruff lint
+        run: ruff check .
+      - name: Ruff format
+        run: ruff format --check .
+      - name: Mypy
+        run: mypy
+      - name: Tests
+        run: pytest -m "not live"
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[release]"
+      - name: Build
+        run: python -m build
+      - name: Twine check
+        run: twine check dist/*

pydmvl-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+# Publishes to PyPI via Trusted Publishing (OIDC) when a GitHub Release is published.
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -U "build>=1.2" "twine>=5"
+      - name: Build
+        run: python -m build
+      - name: Twine check
+        run: twine check dist/*
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pydmvl-0.1.0/.github/workflows/testpypi.yml

@@ -0,0 +1,47 @@
+# Publishes to TestPyPI via Trusted Publishing (OIDC); manual dry run before a release.
+name: TestPyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -U "build>=1.2" "twine>=5"
+      - name: Build
+        run: python -m build
+      - name: Twine check
+        run: twine check dist/*
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

pydmvl-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Environments
+.venv/
+venv/
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Local secrets (never commit)
+*.local.json
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/

pydmvl-0.1.0/AGENTS.md

@@ -0,0 +1,147 @@
+# AGENTS.md — pydmvl
+
+Working agreement for humans and AI agents contributing to this repository.
+
+## 1. Role in the group
+
+This repository is part of a group of projects that build a self-hosted
+control stack for a residential utility account ("Domovladelets" / homeowner):
+
+| Repository | Role | Visibility | Language |
+|---|---|---|---|
+| `pydmvl` (this repo) | Python client for a homeowner account API | public | English |
+| `dmvl-ha-integration` | Home Assistant custom integration, consumes `pydmvl` from PyPI | public | English |
+
+`pydmvl` is the producer: it encapsulates authentication and the account data
+models. The Home Assistant integration depends on `pydmvl` as an external
+package, does not duplicate client logic, and performs no authentication of its
+own. Group identity: code name `dmvl`, package/import `pydmvl`, Home Assistant
+domain `dmvl`.
+
+## 2. Language
+
+All repository text is English: code, comments, docstrings, documentation,
+commit messages, and review notes. The only exceptions are a short bilingual
+intro and disclaimer in this repository's `README.md` (the app audience is
+Russian-speaking) and runtime translation of user-facing strings (e.g.
+`translations/ru.json`) in the consumer integration, not in this library.
+
+## 3. Stack and commands
+
+- Python >= 3.11, hatchling, src-layout (`src/pydmvl/`), plain top-level
+  package (no PEP 420 namespace).
+- Runtime dependency: `httpx>=0.27`; dev tools: pytest, pytest-asyncio, ruff,
+  mypy (strict for `src/`).
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
+.venv/bin/mypy
+.venv/bin/pytest -m "not live"
+```
+
+Live tests (real account, real credentials) carry the `live` marker and are run
+manually only: `.venv/bin/pytest -m live`. Credentials come from the
+environment: `DMVL_USERNAME`, `DMVL_PASSWORD`.
+
+## 4. Spec-driven development (SDD)
+
+- Every feature starts with a spec in `specs/NNNN-slug.md` (zero-padded number,
+  short slug). Status lifecycle: `draft → approved → implemented →
+  superseded`.
+- Implementation without an `approved` spec is forbidden. Specs marked
+  "implementation pending research" must not be implemented until they move to
+  `approved`.
+- Spec template: Summary / Motivation / Requirements (MUST/SHOULD) / Design /
+  API / Test plan / Acceptance criteria / Out of scope / Status.
+- Moving a spec from `draft` to `approved` is a reviewable change (PR or a
+  recorded decision in the conversation).
+
+## 5. Test-driven development (TDD)
+
+- Tests are written first and must fail before the implementation exists.
+- API responses are covered by synthetic fixtures via an httpx mock transport;
+  unit tests never touch the real API.
+- A merge requires a fully green run of all gate commands (§3).
+
+## 6. Git process
+
+- Default branch: `master`. Direct commits to `master` are forbidden (the
+  initial scaffold import is the only exception).
+- One feature = one branch `feat/NNNN-slug` containing the spec, the tests, and
+  the implementation together.
+- Commit messages follow Conventional Commits (`feat:`, `fix:`, `docs:`,
+  `test:`, `chore:`, `refactor:`).
+- Merge into `master` only after the review gate (§7), squash-merge, then delete
+  the feature branch.
+
+## 7. Review gate (mandatory)
+
+A feature branch may merge into `master` only when both hold:
+
+1. A full local run is green (§3/§5).
+2. A skeptic review returns no `BLOCKING` findings. Invoke the skeptic agent
+   (Task tool, definition in `.kilo/agent/skeptic.md`) with a prompt such as:
+
+   > Review branch `feat/NNNN-slug` against its spec `specs/NNNN-slug.md`
+   > (diff base: `master`). Follow the checklist in `.kilo/agent/skeptic.md`
+   > and answer in the verdict format (`BLOCKING: ...` / `NITS: ...` /
+   > `APPROVED`).
+
+`BLOCKING` findings forbid the merge; fix and re-review.
+
+## 8. Secrets and safety
+
+- Account credentials and account data are confidential: never include them in
+  this public repository — in code, docs, examples, fixtures, or commit
+  history. This covers logins, passwords, tokens (including the password hash
+  sent by the API), full names, addresses, personal account numbers, object and
+  payment identifiers, and receipt links. Use synthetic placeholders
+  (`<account>`, `<password>`); real values live only in environment variables
+  or gitignored `*.local.json` files.
+- Authentication material is sent as request query parameters (an observed
+  property of the API). Never log request URLs, credentials, or the password
+  hash. The library installs a redaction filter on the `httpx` logger so
+  dependency-emitted request-URL records have `login` and `hash` replaced; do
+  not remove it.
+- TLS verification defaults to `False` (`DEFAULT_VERIFY`) because the service
+  serves an incomplete certificate chain; the `verify` argument stays
+  overridable and the rationale is documented in the README and spec 0004 R8.
+  Do not remove the argument or change the default without updating both.
+
+## 9. Publication policy (public repository)
+
+- Do not copy text or material from non-public sources into this repo.
+- Public documentation is an English description of observed API behavior.
+  Cite only this repository's own specs; do not name non-public or third-party
+  sources, and do not state or claim how the API was determined.
+- Keep the disclaimers in place (unofficial, not affiliated with the service
+  operator, own account only).
+
+## 10. Release runbook (new versions)
+
+Ship a release only from a green `master`:
+
+1. Bump the version in one change: `pyproject.toml` `[project].version` and
+   `src/pydmvl/__init__.py` `__version__`. A test enforces that they match; no
+   other source or test file pins the version. SemVer; `0.x` while the API is
+   unstable.
+2. Feature branch `feat/NNNN-slug` (spec + tests + code **and the version
+   bump**), gate (§3), skeptic (§7), squash-merge into `master`.
+3. Push `master`.
+4. Create a GitHub Release with tag `vX.Y.Z` equal to the version. Publishing
+   the release triggers `publish.yml`, which builds and uploads to PyPI via
+   Trusted Publishing. A plain tag push does **not** publish.
+5. Run the `testpypi.yml` dry run for every packaging/metadata change, and
+   always before the first production release.
+6. Never reuse a published version; if a release is wrong, bump the patch
+   version and repeat. Verify with `pip install pydmvl==X.Y.Z`.
+7. Keep the runtime dependency floor compatible with Home Assistant's pinned
+   `httpx`.
+
+## 11. References
+
+- Specs: `specs/` (0001 authentication is the first deliverable).
+- Public API surface catalogue: `specs/0005-api-surface.md`.
+- Versioning: SemVer, `0.x` while the API is unstable.

pydmvl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The pydmvl contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pydmvl-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: pydmvl
+Version: 0.1.0
+Summary: Unofficial Python client for the Domovladelets (homeowner) account API
+Project-URL: Homepage, https://github.com/buggy-shep/pydmvl
+Project-URL: Repository, https://github.com/buggy-shep/pydmvl
+Project-URL: Issues, https://github.com/buggy-shep/pydmvl/issues
+Project-URL: Changelog, https://github.com/buggy-shep/pydmvl/releases
+Author: The pydmvl contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: domovladelets,home-automation,homeowner,utility-billing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == 'release'
+Requires-Dist: twine>=5; extra == 'release'
+Description-Content-Type: text/markdown
+
+# pydmvl
+
+[![PyPI version](https://img.shields.io/pypi/v/pydmvl.svg)](https://pypi.org/project/pydmvl/)
+[![CI](https://github.com/buggy-shep/pydmvl/actions/workflows/ci.yml/badge.svg)](https://github.com/buggy-shep/pydmvl/actions/workflows/ci.yml)
+
+Unofficial Python client for the **"Domovladelets+"** ("Домовладелец+",
+homeowner) account API. It implements the protocol used by the app
+([Google Play](https://play.google.com/store/apps/details?id=com.homeowner)):
+it authenticates with an account login and password and exposes the account
+snapshot the service returns for its home screen: account aggregates,
+per-period charges (documents), receipt links, and payment history.
+
+Неофициальный Python-клиент API лицевого счёта приложения **«Домовладелец+»**.
+Реализует протокол этого приложения
+([Google Play](https://play.google.com/store/apps/details?id=com.homeowner)):
+аутентифицируется по логину и паролю лицевого счёта и предоставляет снимок
+счёта, который сервис возвращает для главного экрана: агрегаты по счёту,
+начисления за период (документы), ссылки на квитанции и историю платежей.
+
+> **Disclaimer.** This project is unofficial and is not affiliated with,
+> endorsed by, or sponsored by the "Domovladelets+" application or its
+> operators. It is built for interoperability with your own account. Use it at
+> your own risk; only access accounts you are authorized to access.
+
+> **Отказ от ответственности.** Проект неофициальный и не связан с
+> приложением «Домовладелец+» или его операторами, не одобрен и не
+> спонсируется ими. Он создан для взаимодействия с вашим собственным лицевым
+> счётом. Используйте его на свой риск; получайте доступ только к тем счетам,
+> на которые у вас есть разрешение.
+
+## Install
+
+```bash
+pip install pydmvl
+```
+
+## Usage
+
+```python
+from pydmvl import DmvlClient
+
+with DmvlClient() as client:
+    session = client.login("user", "secret")
+    print(session.personal_account.amount_due)
+```
+
+## TLS verification (disabled by default)
+
+The service presents an **incomplete certificate chain** (it does not serve the
+intermediate CA), so standard verification fails against the real endpoint with
+`certificate verify failed: unable to get local issuer certificate`. The
+official client disables verification for this reason, and `pydmvl` matches
+that observed behavior: `verify` defaults to `False`.
+
+This is a deliberate, documented default, not a silent downgrade. Whenever you
+can, turn verification back on — pass a CA bundle that includes the missing
+intermediate, or `verify=True` if your trust store already chains the
+certificate:
+
+```python
+DmvlClient(verify="/path/to/ca-bundle.pem")
+```
+
+Consumers that expose TLS settings to end users should present this as an
+explicit opt-in control. See [spec 0004](specs/0004-client-api.md) R8.
+
+## Status
+
+Authentication, the account snapshot, documents (charges, receipts, unpaid
+detection), and payment history are implemented (specs 0001–0004); `0.x` — the
+API may still change. See [`specs/`](specs/) for the specifications and their
+status.
+
+Capabilities:
+
+- Login with `login` + `hash` (MD5 of the password); stateless session, no
+  bearer token — [spec 0001](specs/0001-auth.md)
+- Account snapshot with debt/charge/payment aggregates —
+  [spec 0002](specs/0002-documents.md)
+- Per-period charges and receipt links — [spec 0002](specs/0002-documents.md)
+- Payment history and the latest payment — [spec 0003](specs/0003-payments.md)
+- Public sync + async client API — [spec 0004](specs/0004-client-api.md)
+- Configurable TLS verification (default off; see below) — [spec 0004](specs/0004-client-api.md) R8
+
+### Known API surface
+
+The service exposes a single PHP `action` router. The catalogue of known
+actions is [spec 0005](specs/0005-api-surface.md); only the read-only subset
+needed for the account snapshot is implemented here — writing actions
+(submitting meter readings, creating payments, opening doors, sending
+messages, and similar) are out of scope.
+
+## Requirements
+
+- Python >= 3.11
+- [httpx](https://pypi.org/project/httpx/) >= 0.27
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
+.venv/bin/mypy
+.venv/bin/pytest -m "not live"
+```
+
+Live tests against the real API stay behind the `live` marker and are run
+manually only, with credentials from the environment (`DMVL_USERNAME`,
+`DMVL_PASSWORD`). Account credentials are sent as request query parameters, so
+do not enable request-URL logging while a live client is in use.
+
+## License
+
+[MIT](LICENSE)

pydmvl-0.1.0/README.md

@@ -0,0 +1,116 @@
+# pydmvl
+
+[![PyPI version](https://img.shields.io/pypi/v/pydmvl.svg)](https://pypi.org/project/pydmvl/)
+[![CI](https://github.com/buggy-shep/pydmvl/actions/workflows/ci.yml/badge.svg)](https://github.com/buggy-shep/pydmvl/actions/workflows/ci.yml)
+
+Unofficial Python client for the **"Domovladelets+"** ("Домовладелец+",
+homeowner) account API. It implements the protocol used by the app
+([Google Play](https://play.google.com/store/apps/details?id=com.homeowner)):
+it authenticates with an account login and password and exposes the account
+snapshot the service returns for its home screen: account aggregates,
+per-period charges (documents), receipt links, and payment history.
+
+Неофициальный Python-клиент API лицевого счёта приложения **«Домовладелец+»**.
+Реализует протокол этого приложения
+([Google Play](https://play.google.com/store/apps/details?id=com.homeowner)):
+аутентифицируется по логину и паролю лицевого счёта и предоставляет снимок
+счёта, который сервис возвращает для главного экрана: агрегаты по счёту,
+начисления за период (документы), ссылки на квитанции и историю платежей.
+
+> **Disclaimer.** This project is unofficial and is not affiliated with,
+> endorsed by, or sponsored by the "Domovladelets+" application or its
+> operators. It is built for interoperability with your own account. Use it at
+> your own risk; only access accounts you are authorized to access.
+
+> **Отказ от ответственности.** Проект неофициальный и не связан с
+> приложением «Домовладелец+» или его операторами, не одобрен и не
+> спонсируется ими. Он создан для взаимодействия с вашим собственным лицевым
+> счётом. Используйте его на свой риск; получайте доступ только к тем счетам,
+> на которые у вас есть разрешение.
+
+## Install
+
+```bash
+pip install pydmvl
+```
+
+## Usage
+
+```python
+from pydmvl import DmvlClient
+
+with DmvlClient() as client:
+    session = client.login("user", "secret")
+    print(session.personal_account.amount_due)
+```
+
+## TLS verification (disabled by default)
+
+The service presents an **incomplete certificate chain** (it does not serve the
+intermediate CA), so standard verification fails against the real endpoint with
+`certificate verify failed: unable to get local issuer certificate`. The
+official client disables verification for this reason, and `pydmvl` matches
+that observed behavior: `verify` defaults to `False`.
+
+This is a deliberate, documented default, not a silent downgrade. Whenever you
+can, turn verification back on — pass a CA bundle that includes the missing
+intermediate, or `verify=True` if your trust store already chains the
+certificate:
+
+```python
+DmvlClient(verify="/path/to/ca-bundle.pem")
+```
+
+Consumers that expose TLS settings to end users should present this as an
+explicit opt-in control. See [spec 0004](specs/0004-client-api.md) R8.
+
+## Status
+
+Authentication, the account snapshot, documents (charges, receipts, unpaid
+detection), and payment history are implemented (specs 0001–0004); `0.x` — the
+API may still change. See [`specs/`](specs/) for the specifications and their
+status.
+
+Capabilities:
+
+- Login with `login` + `hash` (MD5 of the password); stateless session, no
+  bearer token — [spec 0001](specs/0001-auth.md)
+- Account snapshot with debt/charge/payment aggregates —
+  [spec 0002](specs/0002-documents.md)
+- Per-period charges and receipt links — [spec 0002](specs/0002-documents.md)
+- Payment history and the latest payment — [spec 0003](specs/0003-payments.md)
+- Public sync + async client API — [spec 0004](specs/0004-client-api.md)
+- Configurable TLS verification (default off; see below) — [spec 0004](specs/0004-client-api.md) R8
+
+### Known API surface
+
+The service exposes a single PHP `action` router. The catalogue of known
+actions is [spec 0005](specs/0005-api-surface.md); only the read-only subset
+needed for the account snapshot is implemented here — writing actions
+(submitting meter readings, creating payments, opening doors, sending
+messages, and similar) are out of scope.
+
+## Requirements
+
+- Python >= 3.11
+- [httpx](https://pypi.org/project/httpx/) >= 0.27
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
+.venv/bin/mypy
+.venv/bin/pytest -m "not live"
+```
+
+Live tests against the real API stay behind the `live` marker and are run
+manually only, with credentials from the environment (`DMVL_USERNAME`,
+`DMVL_PASSWORD`). Account credentials are sent as request query parameters, so
+do not enable request-URL logging while a live client is in use.
+
+## License
+
+[MIT](LICENSE)