Essl-F22-SDK 0.1.0__tar.gz

essl_f22_sdk-0.1.0/.dockerignore

@@ -0,0 +1,17 @@
+.git
+.github
+.venv
+venv/
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+tests/
+docs/
+mkdocs.yml
+Dockerfile
+.dockerignore
+LICENSE

essl_f22_sdk-0.1.0/.github/workflows/branch-flow.yml

@@ -0,0 +1,44 @@
+name: Branch flow
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate pull request branch flow
+        env:
+          BASE_REF: ${{ github.base_ref }}
+          HEAD_REF: ${{ github.head_ref }}
+        run: |
+          echo "base=${BASE_REF} head=${HEAD_REF}"
+          case "${BASE_REF}" in
+            prod)
+              if [[ "${HEAD_REF}" != "stag" ]]; then
+                echo "prod accepts pull requests only from stag"
+                exit 1
+              fi
+              ;;
+            stag)
+              if [[ "${HEAD_REF}" != "dev" ]]; then
+                echo "stag accepts pull requests only from dev"
+                exit 1
+              fi
+              ;;
+            dev)
+              if [[ ! "${HEAD_REF}" =~ ^(feat|fix|chore|docs|test)/[0-9]+-[a-z0-9-]+$ ]]; then
+                echo "dev accepts pull requests only from <type>/<issue#>-<slug>"
+                exit 1
+              fi
+              ;;
+            *)
+              echo "unsupported base branch: ${BASE_REF}"
+              exit 1
+              ;;
+          esac
+          echo "branch flow is valid"

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

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [prod, stag, dev]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.14
+      - name: Install dependencies
+        run: uv sync
+      - name: ruff check
+        run: uv run ruff check .
+      - name: ruff format check
+        run: uv run ruff format --check .
+      - name: mypy
+        run: uv run mypy src/
+      - name: pytest
+        run: uv run pytest
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.14
+      - name: Install docs dependencies
+        run: uv sync --extra docs
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.14
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Check package metadata
+        run: uvx twine check dist/*
+      - name: Install wheel in clean environment
+        run: |
+          uv venv --python 3.14 /tmp/essl_f22-wheel
+          uv pip install --python /tmp/essl_f22-wheel/bin/python dist/*.whl
+          /tmp/essl_f22-wheel/bin/python -c "from importlib.metadata import version; import essl_f22; from essl_f22 import Device; assert essl_f22.__version__ == version('Essl_F22_SDK'); print(Device, essl_f22.__version__)"

essl_f22_sdk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/Essl_F22_SDK/
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.14
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Check package metadata
+        run: uvx twine check dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

essl_f22_sdk-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+
+# Environments
+.venv/
+venv/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Type checkers / linters
+.mypy_cache/
+.ruff_cache/
+
+# Packaging
+build/
+dist/
+*.egg-info/
+
+# Documentation build
+site/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

essl_f22_sdk-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.4.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [pytest]

essl_f22_sdk-0.1.0/AGENTS.md

@@ -0,0 +1,214 @@
+# AGENTS.md
+
+Rules every AI agent (and human contributor) must follow when working in this
+repository. Sections `Technical Stack`, `Commands`, and `Architecture & Code
+Style` are project-specific. `Guardrails & Boundaries` is generic — it must be
+carried over unchanged when this file is reused in another project, and only
+the first three sections are rewritten.
+
+---
+
+## Technical Stack
+
+<!-- PROJECT SPECIFIC — regenerate when reusing this file in another project -->
+
+- **Language/Runtime:** Python 3.12+; `pyproject.toml` requires `>=3.12`.
+- **Web framework:** None. This repository is a library, not a web service.
+- **Database:** SQLite via stdlib `sqlite3` by default, with JSON and in-memory
+  backends for block state and the offline mirror. PostgreSQL, MySQL, MongoDB,
+  and Redis are optional adapters using their direct drivers.
+- **Validation/config:** Dataclasses and explicit constructor arguments; no
+  Pydantic dependency.
+- **Telegram:** None.
+- **Outbound HTTP:** None. Device communication is TCP via stdlib `socket`.
+- **Logging:** No logging framework selected yet; avoid adding runtime
+  dependencies without an accepted requirement.
+- **Testing:** pytest + pytest-cov. External storage tests are opt-in through
+  environment values; hardware tests use the `hardware` marker and are opt-in
+  through `ESSL_F22_HOST`.
+- **Quality gates:** ruff (lint + format), mypy (strict), pytest, pre-commit.
+- **Packaging/deploy:** hatchling, uv; optional extras are `docs`, `mongo`,
+  `mysql`, `postgres`, and `redis`.
+- **License:** Apache 2.0.
+
+### Branch layout
+
+- `prod` — default/protected branch. **Can be merged only from `stag`.**
+- `stag` — staging. **Can be merged only from `dev`.**
+- `dev` — integration branch. **Can be merged only from feature/issue
+  branches** (`<type>/<issue#>-<slug>`).
+- Feature/issue branches target `dev`. Promotion through the chain happens
+  via PRs only, one hop at a time.
+- Remote `origin` is `https://github.com/mramitdas/Essl_F22_SDK`; all
+  changes land through PRs and no direct pushes to integration branches are
+  permitted.
+- Server-side branch protection is unavailable on the private free-plan
+  repository. The branch-flow workflow and PR discipline are the enforcement
+  mechanism.
+
+---
+
+## Commands
+
+<!-- PROJECT SPECIFIC — regenerate when reusing this file in another project -->
+
+Run all commands from the repository root unless stated otherwise.
+
+```bash
+# Setup
+uv sync
+
+# Test
+uv run pytest                           # all tests with coverage
+uv run pytest -k name                   # single test
+uv run pytest -m hardware               # opt-in read-only hardware test
+uv run pytest tests/test_storage_contract.py  # opt-in external storage tests
+
+# Quality gates (must be clean before every PR)
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src/
+uv run pytest
+```
+
+**Rule:** never invent commands. Use these verbatim. If a required command is
+missing, check `.github/workflows/ci.yml`; if not defined anywhere, stop and
+ask instead of guessing.
+
+---
+
+## Architecture & Code Style
+
+<!-- PROJECT SPECIFIC — regenerate when reusing this file in another project -->
+
+### Architecture (v0.1 target)
+
+- `src/essl_f22/` — importable package using a src layout. No web, API, bot, or
+  database-server layers.
+- `errors.py` — SDK exception hierarchy.
+- `protocol.py` — command constants, checksums, packet framing, and binary
+  codecs.
+- `transport.py` — TCP socket transport.
+- `session.py` — connect/auth, command request/response, buffered reads.
+- `models.py` — dataclasses for users, attendance, fingerprints, timezones,
+  groups, and device info.
+- `device.py` — high-level device read/write, blocking, mirror, and sync APIs.
+- `mirror.py` — read-only offline mirror and full/incremental sync.
+- `access.py` — non-destructive block/unblock manager.
+- `storage/` — document storage protocols, codecs, built-in backends,
+  external adapters, and the storage factory.
+- `state.py` — `SqliteBlockStateStore` compatibility shim.
+- `__init__.py` — public exports.
+- Unit tests must not require a physical device; use fake transports/sessions.
+  Hardware tests are separate, read-only by default, and skipped unless
+  `ESSL_F22_HOST` is set.
+
+### Code style
+
+- Follow the existing pattern of the file/module you touch. Read neighboring
+  code before writing anything new.
+- Formatted by ruff; type-hinted for mypy strictness over `src/`.
+- Every behavior change ships with tests in the same PR; test names describe
+  the behavior, not the implementation.
+- Documentation (`README.md`, `docs/`) is updated in the same PR whenever
+  setup, behavior, or the API contract changes.
+- No TODO markers, commented-out code, or dead files left behind.
+
+---
+
+## Guardrails & Boundaries
+
+<!-- GENERIC — do not modify when reusing this file in another project -->
+
+### 1. Anti-hallucination
+
+- **Cite, never guess.** Every file, function, command, or config an agent
+  references must exist in the repo right now — verify by reading before
+  acting. No "it should probably be in…" reasoning.
+- **No invented APIs.** Never use a library method from memory; read the
+  installed package for the pinned version in use. Versions come from the
+  manifests, not from recollection.
+- **Read before edit.** A file must be fully read (not just grepped) before it
+  is edited.
+- **Verify before claiming.** Never say "done", "passing", or "fixed" without
+  having run the actual command and seen real output.
+- **Acknowledge unknowns.** Unsure about an env value, expected behavior, or
+  secret? Stop and ask. Never invent credentials, URLs, or DB values.
+- **No silent fallbacks.** If a step fails, report the real error verbatim.
+  Do not work around it by editing unrelated files.
+- **Diff-check after edits.** After every edit, review `git diff` to confirm
+  only intended changes.
+
+### 2. Scope discipline (no overreach)
+
+- One issue = one PR = one logical change. Strictly implement only what the
+  accepted issue defines (its AC).
+- No drive-by refactors, renames, or formatting-only edits; no "while I'm in
+  here" changes. Spotted problems → create a new issue, do not fix inline.
+- No unrequested suggestions at the end of a task. Finish, report, stop.
+  Ideas belong in GitHub issues.
+- One-way decisions (schema changes, API contracts, migrations) are proposed
+  in 1–3 lines and approved before applying.
+- Never create `v2`, `copy`, `.new`, `backup`, or `-final` variants of files;
+  edit in place.
+
+### 3. Issue → branch → PR workflow
+
+- Every task/feature starts as a GitHub issue before any code.
+- Branch naming: `<type>/<issue#>-<slug>` (e.g., `feat/12-rate-limiting`).
+- One task = one commit: conventional commits (`feat:`, `fix:`, `chore:`,
+  `docs:`, `test:`), subject ≤ 50 chars, commit body ends with `refs #N`.
+- Work happens on the issue branch; the PR targets `dev`. Promotion is
+  sequential and PR-only: `dev` → `stag` → `prod`. Never skip or reorder
+  a hop; PRs into `prod` must come from `stag` only, PRs into `stag` from
+  `dev` only.
+- **PR checklist gates (all required before merge):**
+  - tests pass (real command output),
+  - black/isort/mypy/flake8 clean,
+  - no secrets and no `.env` in the diff,
+  - acceptance criteria demonstrably met,
+  - docs updated if behavior/setup changed,
+  - PR targets the correct branch in the chain (`dev` ← branch,
+    `stag` ← `dev`, `prod` ← `stag`).
+- Issue is closed **only** after its PR is merged. Never close otherwise.
+- Never commit or PR directly to protected branches (`prod`, `stag`, `main`),
+  even for docs. No skip-hooks (`--no-verify`), no force-pushing.
+- **Never head-delete integration branches.** Merging a PR with
+  `gh pr merge --delete-branch` deletes the PR's head branch, so use it
+  only for feature/issue branches. PRs whose head is `dev`, `stag`, or
+  `prod` (promotion hops) must be merged without `--delete-branch`.
+  Feature-branch cleanup is manual or guarded by GitHub branch protection.
+
+### 4. Task granularity & tracking
+
+- One task = ≤ 30 minutes of work = one commit = one checkbox in its issue.
+- A task exceeding 30 minutes is split into subtasks within the issue.
+- Every task has executable acceptance criteria (a test, a command, or a
+  demonstrable behavior). Done = AC passes — nothing more, nothing less.
+- Feature issues are parents with a task checklist; each item is its own
+  branch/PR and ≤ 30 minutes.
+- Status is communicated through issue/PR comments, not memory or chat-only.
+
+### 5. Security
+
+- Never commit secrets, tokens, API keys, or `.env`; `.env` is git-ignored.
+  Real secrets live only in the local `.env` / deployment secret store.
+- Dependencies are added/changed only through the requirement manifests
+  (`requirements/*.txt`); lockfile or pin updates are separate commits.
+- Never disable lint, typecheck, or test gates to make something pass.
+
+### 6. Destructive & irreversible operations
+
+- The following require explicit, current-session user approval before
+  running: `git push --force`, branch deletion (including of integration
+  branches `dev`, `stag`, `prod`), dropping/updating-down DB
+  migrations, deleting files beyond the current task's scope, publishing or
+  releasing, and anything modifying `main`/`prod` history.
+- Never touch files outside the workspace directory.
+
+### 7. On session start
+
+- Read this file first.
+- Check open issues and PRs to resume context; rely on issue/PR comments, not
+  memory of a previous session.
+- Confirm the target branch and issue number before the first action.

essl_f22_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Complete layperson-friendly handbook with concepts, guides, reference, help,
+  and contributing pages, plus a strict MkDocs build in CI.
+- Expanded README with requirements, installation, quickstart, common tasks,
+  storage, safety, compatibility, error handling, and development guidance.
+
+### Changed
+
+- Renamed the PyPI distribution from `essl_f22` to `Essl_F22_SDK`; the Python
+  import remains `essl_f22`.
+
+## [0.1.0] - 2026-10-24
+
+### Added
+
+- Synchronous TCP SDK for eSSL/ZKTeco F22 terminals.
+- Device information, user, fingerprint metadata, attendance, group, and
+  timezone reads.
+- User create, update, and delete APIs.
+- Non-destructive user blocking and unblocking.
+- Read-only offline mirror with full and incremental sync.
+- SQLite, JSON, memory, PostgreSQL, MySQL, MongoDB, and Redis storage backends.
+- Optional dependency extras for external storage drivers.
+- Hardware, storage-contract, and unit test suites.
+- PyPI packaging with Trusted Publishing.

essl_f22_sdk-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,26 @@
+# Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and maintainers of the Essl F22 SDK
+pledge to make participation in this project a harassment-free experience for
+everyone, regardless of age, body size, visible or invisible disability, ethnicity,
+sex characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Expected behavior
+
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community and the project
+
+Unacceptable behavior includes harassment, personal attacks, trolling, and
+publishing others' private information without permission.
+
+## Enforcement
+
+Report unacceptable behavior to the project maintainer at
+[mramitdas99@gmail.com](mailto:mramitdas99@gmail.com). All complaints
+will be reviewed and investigated promptly and fairly. Maintainers are
+obligated to respect the privacy of the reporter.

essl_f22_sdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Thanks for your interest in contributing to the Essl F22 SDK.
+
+## Workflow
+
+1. Fork and create a feature branch from `dev`.
+2. Install dev dependencies: `uv sync`.
+3. Make your change with tests.
+4. Run the quality gates:
+
+   ```bash
+   uv run ruff check .
+   uv run ruff format --check .
+   uv run mypy src/
+   uv run pytest
+   ```
+
+5. Open a pull request targeting `dev`.
+
+## Release
+
+Releases are published to PyPI from `prod` with Trusted Publishing.
+
+One-time setup: add a PyPI pending trusted publisher for this repository,
+workflow `release.yml`, and environment `pypi`, then create the matching
+GitHub environment.
+
+1. Update `CHANGELOG.md` and `__version__` in `src/essl_f22/__init__.py`.
+2. Merge the release change through `dev` → `stag` → `prod`.
+3. Tag `prod` with `vX.Y.Z` and push the tag.
+4. The `release.yml` workflow builds and publishes the sdist and wheel.
+5. Verify `pip install Essl_F22_SDK==X.Y.Z` in a clean environment.
+
+## Code of Conduct
+
+Please read and follow the [Code of Conduct](CODE_OF_CONDUCT.md).

essl_f22_sdk-0.1.0/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.14-slim
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy
+
+COPY pyproject.toml uv.lock ./
+RUN uv sync --no-dev --frozen
+
+COPY src/ src/
+
+USER 1000:1000
+
+CMD ["uv", "run", "--no-sync", "python", "-c", "from essl_f22.core import add; print(add(1, 2))"]