winregkit 0.1.0__tar.gz

winregkit-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,52 @@
+# Copilot Instructions for winregkit
+
+## Project context
+- `winregkit` is a small Python library around Windows Registry operations.
+- Main implementation lives in `src/winregkit/`.
+- Tests rely heavily on `tests/fakewinreg.py` to validate behavior on non-Windows and to compare against real `winreg` when available.
+
+## Tech and tooling
+- Python version target: **3.11+**.
+- Packaging/build: `hatchling` (`pyproject.toml`).
+- Environment/dependency workflow uses **uv**.
+- Version management should use `uv version` (e.g. `uv version --bump patch`, `uv version 0.0.1rc1`) instead of manually editing `pyproject.toml`.
+- Type checking uses **mypy strict mode** on `src/winregkit`.
+- Linting/import order uses **ruff** with import sorting (`I`).
+
+## Code style and implementation rules
+- Keep changes minimal and focused; do not refactor unrelated code.
+- Preserve existing API shape and naming unless explicitly asked.
+- Prefer explicit type annotations that satisfy strict mypy.
+- Follow existing patterns:
+  - `Key` methods raise `KeyError` for missing values/keys where the library API currently does so.
+  - Low-level backend exceptions (`FileNotFoundError`, `OSError`, `PermissionError`) are translated only where the current code already translates them.
+- Keep compatibility with both real `winreg` and `tests.fakewinreg` behavior.
+- Avoid platform-specific assumptions that would break tests on non-Windows.
+
+## Testing expectations
+- Run targeted tests first for touched behavior, then broader tests.
+- Typical commands:
+  - `uv sync --dev`
+  - `pytest`
+- If type-significant code is changed, also run:
+  - `uv run mypy src/winregkit`
+
+## File-specific guidance
+- `src/winregkit/registry.py` is the core behavior surface; changes here should preserve context-manager and handle lifecycle semantics (`open`, `close`, `opened`, `create`, `delete`).
+- `tests/fakewinreg.py` is a behavioral compatibility shim. If production behavior changes, update tests and shim only when required by the requested change.
+- CLI (`src/winregkit/cli.py`) is intentionally minimal currently; do not expand it unless requested.
+
+## When adding or changing code
+- Add/adjust tests in `tests/` for any behavior change.
+- Keep imports sorted and remove unused imports.
+- Keep docstrings concise and consistent with existing style.
+- Prefer straightforward implementations over abstractions.
+- Update `CHANGELOG.md` for release-worthy changes (including `rc`/pre-release tags).
+- Keep changelog entries concise and user-facing; avoid listing individual development bug-fix details.
+
+## Things to double-check before finishing
+- No accidental public API breaks in `winregkit.__init__` exports.
+- Tests pass locally.
+- New code passes strict typing.
+- Run `uvx ruff check` and `uvx ruff format --check` before pushing.
+- No unrelated formatting-only churn.

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

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+      - main
+    tags:
+      - "v*"
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        exclude:
+          - os: windows-latest
+            python-version: "3.11"
+          - os: windows-latest
+            python-version: "3.12"
+          - os: windows-latest
+            python-version: "3.13"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Lint (ruff)
+        run: uvx ruff check
+
+      - name: Format check (ruff)
+        run: uvx ruff format --check
+
+      - name: Sync dependencies
+        run: uv sync --locked --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Type check (mypy)
+        if: runner.os == 'Windows'
+        run: uv run mypy src/winregkit

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

@@ -0,0 +1,84 @@
+name: Publish
+
+on:
+  workflow_run:
+    workflows:
+      - CI
+    types:
+      - completed
+
+jobs:
+  detect-tag:
+    if: github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push'
+    runs-on: ubuntu-latest
+    outputs:
+      publish_tag: ${{ steps.tag.outputs.publish_tag }}
+      commit_sha: ${{ steps.sha.outputs.commit_sha }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Capture CI commit SHA
+        id: sha
+        run: echo "commit_sha=${{ github.event.workflow_run.head_sha }}" >> "$GITHUB_OUTPUT"
+
+      - name: Detect version tag at CI commit
+        id: tag
+        run: |
+          git fetch --tags --force
+          TAG=$(git tag --points-at "${{ github.event.workflow_run.head_sha }}" | grep '^v' | head -n 1 || true)
+          echo "publish_tag=$TAG" >> "$GITHUB_OUTPUT"
+
+  publish:
+    needs: detect-tag
+    if: needs.detect-tag.outputs.publish_tag != ''
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+
+    environment:
+      name: pypi
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.detect-tag.outputs.commit_sha }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Verify built artifacts
+        run: ls -la dist
+
+      - name: Publish to PyPI
+        run: uv publish
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.detect-tag.outputs.publish_tag }}
+        run: |
+          gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1 && exit 0
+
+          PRERELEASE_FLAG=""
+          case "$TAG" in
+            *a*|*b*|*rc*|*dev*) PRERELEASE_FLAG="--prerelease" ;;
+          esac
+
+          gh release create "$TAG" dist/* \
+            --repo "$GITHUB_REPOSITORY" \
+            --verify-tag \
+            --title "$TAG" \
+            --notes "See CHANGELOG.md for release details." \
+            $PRERELEASE_FLAG

winregkit-0.1.0/.gitignore

@@ -0,0 +1,65 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.pyc
+
+# Distribution / packaging
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# VS Code
+.vscode/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Other
+*.log
+*.pot
+*.mo
+*.swp
+*.swo
+
+# Mac
+.DS_Store
+
+# Windows
+Thumbs.db

winregkit-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

winregkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+No tracked entries yet.
+
+## 0.1.0 - 2026-02-21
+
+First stable 0.1 release.
+
+- Finalizes the 0.1 API surface for key traversal, typed value operations, and path-based key construction.
+- Strengthens test coverage across fake and real backends, with backend-selective test flags for CI and local runs.
+- Enforces formatting checks in CI alongside linting, tests, and Windows mypy checks.
+
+## 0.1.0rc2 - 2026-02-21
+
+Second release candidate for the 0.1 line.
+
+- Publish workflow now creates a basic GitHub Release alongside PyPI publication.
+- Release automation now avoids duplicate publish attempts from branch-triggered CI runs.
+
+## 0.1.0rc1 - 2026-02-21
+
+Initial release candidate for the 0.1 line.
+
+- API surface refined for clearer typed value access and iteration naming.
+- Cross-platform test strategy stabilized for real Windows `winreg` and fake backend coverage.
+- CI and publish workflows aligned around `uv` tooling with release-tag-driven publishing.
+- Project release/version workflow standardized on `uv version`.

winregkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kristján Valur Jónsson
+
+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.

winregkit-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: winregkit
+Version: 0.1.0
+Summary: A modern, pythonic interface to the Windows registry.
+License-File: LICENSE
+Classifier: Operating System :: Microsoft :: Windows
+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
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

winregkit-0.1.0/README.md

@@ -0,0 +1,100 @@
+# winregkit
+
+A modern, pythonic interface to the Windows registry.
+
+## Introduction
+
+Python comes with `winreg` for registry operations, but it is a thin wrapper over
+Win32 APIs and can be cumbersome for day-to-day usage.
+
+`winregkit` provides a higher-level, object-oriented interface with simple tree
+navigation, dict-like value access, and context-manager support.
+
+## Features
+- Easy-to-use API for reading and writing Windows Registry keys
+- Python 3.11+
+- Windows platform
+- MIT License
+- Managed and built with [uv](https://github.com/astral-sh/uv)
+
+
+## Installation
+
+```sh
+pip install winregkit
+```
+
+Or the equivalent command in your preferred package manager.
+
+## Usage
+
+### Library
+```python
+from winregkit import current_user
+import winreg
+
+
+# open for read
+with current_user.subkey("Software", "MyApp").open() as key:
+    print(key["name"])
+    print(key.get("missing", "default"))
+
+# open for write (subkeys can be passed directly to open as a convenience)
+with current_user.open("Software", "MyApp", write=True) as key:
+    key["name"] = "winregkit"
+    key["enabled"] = 1
+
+# create/open for write (create is shorthand for open(create=True, write=True))
+with current_user.create("Software", "MyApp") as key:
+    key["name"] = "winregkit"
+    key["enabled"] = 1
+
+# the Key object provides dict access and values can be iterated over:
+with current_user.open("Software", "MyApp") as key:
+    for name, value in key.items():
+        print(name, value)
+
+# the underlying type of a value can be retrieved, and a custom type can be
+# set, overriding default conversions:
+with current_user.open("Software", "MyApp", write=True) as key:
+    value, value_type = key.get_typed("enabled")
+    print(value, value_type)
+
+    key.set_typed("payload", b"\x00\x01\x02", winreg.REG_BINARY)
+
+# existence checks are available on keys:
+app_key = current_user.subkey("Software", "MyApp")
+print(app_key.exists())
+
+```
+
+`subkey(...)` is optional convenience for pre-building a path. You can either
+chain with `subkey(...)` first, or pass subkeys directly to `open(...)` / `create(...)`.
+
+### Preferred API style
+- Use root factories (`current_user`, `local_machine`, etc.)
+- Navigate with `subkey(...)` (optional)
+- Open with `open(...)` or `create(...)` and a context manager
+- Use dict-style value access (`key[name]`, `key[name] = value`)
+- Use `get_typed` / `set_typed` only when explicit registry types are needed
+
+## Development
+
+This project uses the [uv](https://docs.astral.sh/uv/) package manager.
+
+- Install uv, e.g. using `pip install uv`
+
+- Install dev dependencies:
+  ```sh
+  uv sync --dev
+  ```
+- Run tests:
+  ```sh
+  uv run pytest
+  ```
+
+## License
+MIT License. See `LICENSE` for details.
+
+## Changelog
+See `CHANGELOG.md` for release history and policy.

winregkit-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "winregkit"
+version = "0.1.0"
+description = "A modern, pythonic interface to the Windows registry."
+requires-python = ">=3.11"
+classifiers = [
+	"Programming Language :: Python :: 3",
+	"Programming Language :: Python :: 3.11",
+	"Programming Language :: Python :: 3.12",
+	"Programming Language :: Python :: 3.13",
+	"Programming Language :: Python :: 3.14",
+	"Operating System :: Microsoft :: Windows",
+]
+[license]
+text = "MIT"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "mypy"]
+
+[dependency-groups]
+dev = ["pytest>=8.0", "mypy"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src/winregkit"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+src = ["src", "tests"]
+lint.extend-select = ["I"] # Ensure import order is checked
+

winregkit-0.1.0/src/winregkit/__init__.py

@@ -0,0 +1,3 @@
+from .registry import Key, classes_root, current_config, current_user, local_machine, users
+
+__all__ = ["Key", "classes_root", "current_user", "local_machine", "users", "current_config"]