ttlock-ble 0.1.1__tar.gz

ttlock_ble-0.1.1/.github/workflows/codeql.yml

@@ -0,0 +1,41 @@
+name: CodeQL
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: "0 0 * * 0"
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        language:
+          - python
+
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@0daab03d71ff584ef619d027a3fd9146679c5d84 # v3
+        with:
+          languages: ${{ matrix.language }}
+          queries: security-extended
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@0daab03d71ff584ef619d027a3fd9146679c5d84 # v3
+        with:
+          category: "/language:${{ matrix.language }}"

ttlock_ble-0.1.1/.github/workflows/lint.yml

@@ -0,0 +1,57 @@
+name: Lint
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+    branches:
+      - "main"
+
+permissions: {}
+
+jobs:
+  ruff:
+    name: "Ruff"
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format
+        run: uv run ruff format . --check
+
+  mypy:
+    name: "Mypy"
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Type check
+        run: uv run mypy src

ttlock_ble-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to (re)publish to PyPI, e.g. v1.1.0. Skips release-please."
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    name: Release Please
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - name: Run release-please
+        id: release
+        uses: googleapis/release-please-action@v5
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: release-please
+    if: |
+      always() && (
+        (github.event_name == 'push' && needs.release-please.outputs.release_created == 'true') ||
+        github.event_name == 'workflow_dispatch'
+      )
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ttlock-ble
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout the released tag
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || needs.release-please.outputs.tag_name }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ttlock_ble-0.1.1/.github/workflows/tests.yml

@@ -0,0 +1,33 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+    branches:
+      - "main"
+
+permissions: {}
+
+jobs:
+  pytest:
+    name: "Pytest"
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest

ttlock_ble-0.1.1/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+decompiled/
+DLock-XP_*.xapk
+/tmp/
+*.log
+.DS_Store
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/

ttlock_ble-0.1.1/.idea/.gitignore

@@ -0,0 +1,3 @@
+# Default ignored files
+/shelf/
+/workspace.xml

ttlock_ble-0.1.1/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

ttlock_ble-0.1.1/.idea/misc.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="uv (ttlock-ble)" />
+  </component>
+</project>

ttlock_ble-0.1.1/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/ttlock-ble.iml" filepath="$PROJECT_DIR$/.idea/ttlock-ble.iml" />
+    </modules>
+  </component>
+</project>

ttlock_ble-0.1.1/.idea/pyProjectModel.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="PyProjectModelSettings">
+    <option name="showConfigurationNotification" value="false" />
+  </component>
+</project>

ttlock_ble-0.1.1/.idea/ttlock-ble.iml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+      <excludeFolder url="file://$MODULE_DIR$/decompiled" />
+    </content>
+    <orderEntry type="jdk" jdkName="uv (ttlock-ble)" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+  <component name="PyDocumentationSettings">
+    <option name="format" value="PLAIN" />
+    <option name="myDocStringFormat" value="Plain" />
+  </component>
+  <component name="TestRunnerService">
+    <option name="PROJECT_TEST_RUNNER" value="py.test" />
+  </component>
+</module>

ttlock_ble-0.1.1/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

ttlock_ble-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+
+      - id: mypy
+        name: mypy
+        entry: uv run mypy src
+        language: system
+        pass_filenames: false
+        types: [python]

ttlock_ble-0.1.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.1"
+}

ttlock_ble-0.1.1/.ruff.toml

@@ -0,0 +1,61 @@
+# The contents of this file is based on https://github.com/home-assistant/core/blob/dev/pyproject.toml
+
+target-version = "py311"
+line-length = 100
+
+[lint]
+select = [
+    "ALL",
+]
+
+ignore = [
+    "ANN401", # typing.Any disallowed — not always avoidable at framework boundaries
+    "D203",   # no-blank-line-before-class (incompatible with formatter)
+    "D212",   # multi-line-summary-first-line (incompatible with formatter)
+    "D213",   # mutually exclusive with D212; we pick D212-style summaries
+    "D107",   # __init__ docstring covered by class docstring
+    "COM812", # incompatible with formatter
+    "ISC001", # incompatible with formatter
+    "EM101",  # raise(str) is fine — format helps grep, no string variable needed
+    "EM102",  # same for f-strings inside raise
+    "TRY003", # long exception messages are OK when the message carries diagnostics
+    "TID252", # relative imports between same-package siblings are intentional
+    "PLR2004", # magic byte values are the protocol — extracting them all hurts readability
+    "PLC0415", # lazy imports break a couple of circular deps; intentional
+    "FBT003",  # boolean positional in typer.Option calls is the framework idiom
+    "S101",    # we keep asserts as type-narrowing aids for mypy; cheap in CPython
+]
+
+[lint.per-file-ignores]
+"tests/**" = [
+    "S101",     # asserts are the point of tests
+    "S105",     # tests carry expected passcode/secret values inline
+    "SLF001",   # tests intentionally exercise private members
+    "ARG001",   # unused fixtures are normal
+    "PLR2004",  # magic numbers in tests are fine
+    "D",        # docstrings not required in tests
+    "ANN",      # type annotations not required in tests
+    "ERA001",   # protocol-byte-layout comments are valuable in payload tests
+    "PT011",    # pytest.raises bare ValueError is fine when message isn't tested
+    "PT018",    # composite assertion is normal in tests
+    "PLC0415",  # local imports inside test methods are normal
+    "PYI034",   # Self return type isn't relevant in test fixtures
+]
+"src/ttlock_ble/cli.py" = [
+    "D",        # typer commands self-document via help=
+    "BLE001",   # CLI handlers convert any error into typer.Exit
+    "FBT001",   # boolean-positional in typer commands is the framework idiom
+    "FBT002",
+]
+"src/ttlock_ble/models/*.py" = [
+    "N815",     # cloud-facing dataclass fields keep upstream camelCase
+]
+
+[lint.flake8-pytest-style]
+fixture-parentheses = false
+
+[lint.pyupgrade]
+keep-runtime-typing = true
+
+[lint.mccabe]
+max-complexity = 25

ttlock_ble-0.1.1/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.1](https://github.com/roquerodrigo/ttlock-ble/compare/v0.1.0...v0.1.1) (2026-05-11)
+
+
+### Features
+
+* initial release of ttlock-ble Python SDK ([408a778](https://github.com/roquerodrigo/ttlock-ble/commit/408a778cd3dd067a09f892373b852ad87e418e68))

ttlock_ble-0.1.1/CLAUDE.md

@@ -0,0 +1,28 @@
+# ttlock-ble
+
+Python SDK for controlling **DLock-XP / TTLock** Bluetooth smart locks
+without depending on the TTLock cloud at unlock time. The session AES key
+is downloaded once from the TTLock cloud and cached locally; from then on
+all lock/unlock/state operations run fully offline over BLE.
+
+## Always read `CODE_STYLE.md` first
+
+Before creating, renaming or restructuring any file/class/function, **read
+[`CODE_STYLE.md`](./CODE_STYLE.md)**. It is the single source of truth for
+conventions: language, file organisation, naming, typing, imports,
+docstrings, comments, logging, error messages, public API surface,
+pre-commit hooks, conventional commits, packaging, releasing, testing,
+lint workflow.
+
+## Verification workflow
+
+After every code change, always run lint then tests, in that order, before
+declaring the task done:
+
+```bash
+uv run ruff format . && uv run ruff check . --fix && uv run mypy src
+uv run pytest
+```
+
+Both gates mirror CI. Skip this only when the change literally cannot
+affect lint or tests (e.g., README-only edits).

ttlock_ble-0.1.1/CODE_STYLE.md

@@ -0,0 +1,209 @@
+# Code Style Guide
+
+Style conventions for the `ttlock-ble` Python SDK. Run
+`uv run ruff format . && uv run ruff check . --fix && uv run mypy src` before
+committing — all three must exit cleanly. `uv run pytest` follows.
+
+**Always read this file before adding or restructuring code.**
+
+## Language
+
+- Code is written in **English**: file names, class names, function names,
+  variable names, dictionary keys, identifier strings.
+- The conversation language with the user can be Portuguese or anything else;
+  what is committed to disk stays English.
+
+## File organization
+
+- **Source layout is `src/ttlock_ble/`.** Tests in `tests/`, packaging in
+  `pyproject.toml`. Hatchling is the build backend.
+- **One top-level class per file.** Multiple semantically related classes get
+  grouped into a package directory with one class per submodule and an
+  `__init__.py` re-exporting the public symbols.
+  - Example: `protocol/` could contain `frame.py`, `reassembler.py`,
+    plus `__init__.py`.
+  - Example: `models/` could contain `virtual_key.py`, `lock_version.py`,
+    `site_info.py`, plus `__init__.py`.
+- **Public surface goes through the package `__init__.py`.** Anything not
+  re-exported there is internal — prefix with `_` if intended to stay private.
+- **TypedDicts and `type` aliases do not count as "classes"** for this rule —
+  they live alongside related code.
+- **Helper functions** may live in the same file as the single class that
+  uses them. Module-level private helpers are prefixed `_`.
+
+## Naming
+
+- Public classes are `CapWords`: `TTLockClient`, `TTLockCloud`, `VirtualKey`,
+  `LockVersion`, `Frame`, `FrameReassembler`.
+- Exception classes end with `Error`: `TTLockError`, `CloudError`.
+- Module names are `snake_case`. Subpackages are organized by concern
+  (`protocol`, `cloud`, `commands`).
+- Private attributes / functions are prefixed with `_`.
+
+## Typing
+
+**Strict typing. No `Any`, no bare collection generics.** Mypy enforces this.
+
+Banned: `typing.Any`, `object` as a value type, bare `dict` / `list` /
+`tuple` / `set`, `dict[str, Any]`.
+
+Required:
+
+- `@dataclass` for structured records (`VirtualKey`, `LockVersion`,
+  `SiteInfo`, `CloudCredentials`).
+- Named `type` aliases for shared shapes.
+- `frozenset[str]` / `tuple[str, ...]` for fixed string collections.
+- Always type return values explicitly. Never rely on type inference for
+  public APIs.
+- Type-hinted module-level loggers: `log: logging.Logger = logging.getLogger(...)`.
+
+The SDK ships a `py.typed` marker so downstream consumers get type info.
+
+## Imports
+
+- Always start every module with `from __future__ import annotations` so type
+  hints become lazy strings.
+- Same-package relative imports (`from .module import …`) are the default.
+- Move type-only imports into a `TYPE_CHECKING` block:
+
+  ```python
+  from __future__ import annotations
+  from typing import TYPE_CHECKING
+
+  if TYPE_CHECKING:
+      from collections.abc import Iterable
+      from .models import VirtualKey
+  ```
+
+- `noqa` comments require a written justification inline. Never silence to
+  "make ruff happy" — fix the underlying code.
+
+## Docstrings
+
+- Every public class, function, method (including `@property`) has a docstring.
+- A single sentence is usually enough. Describe the *contract* or the *why*,
+  not the obvious implementation.
+- Module-level docstring at the top of every `.py` file.
+- Avoid restating the type — the signature already does that.
+
+## Comments
+
+- Default to **no comments**. Add one only when the *why* is not obvious from
+  the code: a hidden constraint, a workaround, a subtle invariant, a protocol
+  reference.
+- Never describe *what* the code does — well-named identifiers handle that.
+- **No section dividers** like `# --- Frame helpers ---` to group related
+  declarations. If a file has so many sections that you feel the need for
+  visual separators, split it into multiple files instead.
+
+## Logging
+
+- Module-level logger: `log: logging.Logger = logging.getLogger("ttlock_ble.<area>")`
+  (e.g. `"ttlock_ble.client"`, `"ttlock_ble.cloud"`). Don't use `__name__`
+  directly — the explicit dotted name lets users scope log levels precisely.
+- Use **lazy `%`-formatting**, never f-strings:
+
+  ```python
+  log.debug("Lock found: %s rssi=%d", name, rssi)             # ✓
+  log.debug(f"Lock found: {name} rssi={rssi}")                # ✗
+  ```
+
+- Levels:
+  - `debug` — TX/RX bytes, GATT discovery, frame payload values.
+  - `info` — connection established, handshake completed, unlock success.
+  - `warning` — recoverable failures (one-off connect retry, weak signal).
+  - `error` / `exception` — unrecoverable. `exception` inside `except` blocks
+    captures the traceback.
+- Never log raw `aesKeyStr`, `unlockKey`, `adminPs`, or decrypted payloads.
+  Truncate / hash if diagnostics need correlation.
+
+## Error messages
+
+- Format: `"Failed to <verb> <object>: <cause>"`. Keep them short and
+  grep-able.
+- Custom exceptions form a hierarchy: `TTLockError` (BLE / protocol failures)
+  and `CloudError` (HTTP / signature / verification failures) are the public
+  errors. Wrap raw `bleak`, `httpx`, `OSError` errors at the transport
+  boundary so callers only catch this hierarchy.
+- Pre-validate inputs before opening a connection so user-facing errors point
+  at the bad input, not a downstream traceback.
+
+## Public API surface
+
+- Anything imported in the package `__init__.py` is the public contract
+  (`TTLockClient`, `TTLockCloud`, `VirtualKey`, `LockVersion`, `SiteInfo`).
+  Renaming or removing those symbols is a `BREAKING CHANGE:`.
+- Internal modules can change shape freely as long as the public re-exports
+  keep working.
+
+## Pre-commit hooks
+
+`pre-commit` is recommended. Add `.pre-commit-config.yaml` mirroring the
+lint commands (ruff format, ruff check, mypy) and install once per clone:
+
+```bash
+pre-commit install
+```
+
+The hook runs the same gates as CI on every commit. Skip it only on
+emergency `git commit --no-verify` and immediately re-run the lint commands.
+
+## Conventional commits
+
+All commits follow [Conventional Commits](https://www.conventionalcommits.org/),
+in **English**, which `release-please` parses to bump `pyproject.toml` `version`
+and generate `CHANGELOG.md`:
+
+| Type | Meaning | Bump |
+|---|---|---|
+| `feat` | New feature | minor |
+| `fix` | Bug fix | patch |
+| `perf` | Performance improvement | patch |
+| `deps` | Dependency bump | patch |
+| `docs` | Documentation only | none |
+| `refactor` | Refactor without behavior change | none |
+| `test` | Test-only change | none |
+| `ci` | CI / tooling change | none |
+| `chore` | Anything else (rarely) | none |
+
+- Subject line: imperative mood, lowercase, no trailing period.
+- Use scopes when useful: `feat(ble): retry connect on first attempt`.
+- A `BREAKING CHANGE:` footer (or `!` after type) bumps the major version.
+
+## Packaging
+
+- Build backend: `hatchling`. Wheel and sdist contain `src/ttlock_ble`.
+- `requires-python = ">=3.11"`. Don't bump this without a `BREAKING CHANGE:`
+  footer.
+- Public dependencies: keep them minimal and use `>=` lower bounds, not
+  pins.
+- The `[dependency-groups] dev` group carries test-only deps.
+- A `py.typed` marker ships in the wheel so consumers see type info.
+
+## Releasing
+
+- `release-please` runs on `main` and opens a release-PR with the next
+  version + `CHANGELOG.md`. Merging that PR triggers the publish job
+  (sdist + wheel via `python -m build`, published to PyPI via the
+  `pypi` GitHub Environment + Trusted Publisher — no token in repo secrets).
+- Don't manually edit `pyproject.toml` `version` — release-please owns it.
+
+## Testing
+
+- Tests live in `tests/`. `uv run pytest` runs the suite. Aim for high
+  coverage on protocol/crypto/cloud layers since they're the byte-level
+  surface most likely to regress silently.
+- Hardware-dependent tests (real BLE lock) are gated behind an env var and
+  skipped in CI; pure unit tests use captured byte fixtures.
+
+## Linting and verification
+
+- Ruff configuration lives in `.ruff.toml` with `select = ["ALL"]` and a
+  short list of justified ignores.
+- Mypy configuration lives in `mypy.ini` (strict).
+- Pytest configuration lives in `pytest.ini`, including a 50 % coverage
+  gate (BLE/HTTP code paths still need mocked tests; raise the gate as
+  coverage grows).
+- `scripts/lint` runs `ruff format`, `ruff check --fix`, `mypy src` and
+  `pytest` in order. CI mirrors this via `.github/workflows/lint.yml`,
+  `tests.yml`, `codeql.yml`.

ttlock_ble-0.1.1/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: ttlock-ble
+Version: 0.1.1
+Summary: Python SDK for controlling DLock-XP / TTLock smart locks over Bluetooth
+Project-URL: Homepage, https://github.com/roquerodrigo/ttlock-ble
+Project-URL: Repository, https://github.com/roquerodrigo/ttlock-ble
+Project-URL: Issues, https://github.com/roquerodrigo/ttlock-ble/issues
+Author-email: Rodrigo Roque <rodrigogoncalvesroque@gmail.com>
+License: MIT
+Keywords: ble,bluetooth,home-automation,sdk,smart-lock,ttlock
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.11
+Requires-Dist: bleak-retry-connector>=4.6.0
+Requires-Dist: bleak>=0.22
+Requires-Dist: cryptography>=43
+Requires-Dist: httpx>=0.27
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: typer>=0.12

ttlock_ble-0.1.1/mypy.ini

@@ -0,0 +1,22 @@
+[mypy]
+python_version = 3.11
+explicit_package_bases = True
+ignore_missing_imports = True
+follow_imports = silent
+strict_optional = True
+warn_redundant_casts = True
+warn_unused_ignores = True
+warn_unreachable = True
+no_implicit_optional = True
+check_untyped_defs = True
+disallow_untyped_defs = True
+disallow_any_generics = True
+
+[mypy-tests.*]
+disallow_untyped_defs = False
+check_untyped_defs = False
+
+[mypy-ttlock_ble.client]
+# bleak callback signatures resolve to `Any` without bundled stubs;
+# silence the explicit-any complaints they trigger here.
+disable_error_code = explicit-any