regkit 0.3.0__tar.gz

regkit-0.3.0/.github/copilot-instructions.md

@@ -0,0 +1,53 @@
+# Copilot Instructions for regkit
+
+## Project context
+- `regkit` is a small Python library around Windows Registry operations.
+- Main implementation lives in `src/regkit/`.
+- 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/regkit`.
+- 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/regkit`
+
+## File-specific guidance
+- `src/regkit/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/regkit/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 `regkit.__init__` exports.
+- Tests pass locally.
+- New code passes strict typing.
+- Run `uvx ruff check` and `uvx ruff format --check` before pushing.
+- For any version bump via `uv version`, ensure `uv.lock` is updated, committed, and pushed with the release changes.
+- No unrelated formatting-only churn.

regkit-0.3.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/regkit

regkit-0.3.0/.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - master
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Sync docs dependencies
+        run: uv sync --group docs
+
+      - name: Build docs
+        run: uv run mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

regkit-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,85 @@
+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" \
+            --generate-notes \
+            --notes "See CHANGELOG.md for curated release details." \
+            $PRERELEASE_FLAG

regkit-0.3.0/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.pyc
+
+# Distribution / packaging
+.Python
+build/
+dist/
+site/
+*.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

regkit-0.3.0/.python-version

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

regkit-0.3.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+No tracked entries yet.
+
+## 0.3.0 - 2026-02-24
+
+Minor release for package and project rename.
+
+- Renamed package distribution from `winregkit` to `regkit`.
+- Renamed source package path from `src/winregkit` to `src/regkit`.
+- Updated docs, CI, tests, and project metadata references to `regkit`.
+- Updated repository/docs URLs to `kristjanvalur/regkit`.
+
+## 0.2.1 - 2026-02-22
+
+Patch release refining canonical path identity semantics.
+
+- Canonical comparison/hashing now always derives the root label from the root handle.
+- Root-node lexical labels are normalized away for canonical identity (for example, `Key(100, "foo")` and `Key(100, "bar")` now compare/hash the same at root level).
+
+## 0.2.0 - 2026-02-22
+
+Minor release extending pathlib-style key path ergonomics.
+
+- Added `Key.parent` and `Key.parents()` for lexical ancestor navigation.
+- Added `Key.parts` plus `Key.from_parts(...)` / `Key.from_path(...)` for path round-tripping.
+- Simplified rooted-key construction internals (`from_parts(...)` now uses direct rooted construction).
+- **Breaking:** `Key.name` now returns only the final lexical segment; internal full relative path storage is kept private.
+- Added `Key.iterdir()`, `Key.joinpath(...)`, `/` operator composition, and `Key.walk(...)` traversal (`os.walk`-like).
+
+## 0.1.3 - 2026-02-22
+
+Patch release adding traversal and pathlib-style path ergonomics.
+
+- Added `Key.walk(...)` with `os.walk`-like semantics for key-tree traversal.
+- Added `Key.iterdir()` as a pathlib-style alias for subkey iteration.
+- Added `Key.joinpath(...)` and `/` operator support for key path composition.
+- Expanded README method reference and examples for new traversal/path APIs.
+
+## 0.1.2 - 2026-02-21
+
+Patch release adding typing metadata for downstream type checkers.
+
+- Added `py.typed` marker to declare inline typing support in `regkit` (PEP 561).
+
+## 0.1.1 - 2026-02-21
+
+Patch release to validate automated GitHub Release notes.
+
+- Publish workflow now uses GitHub-generated release notes for tag releases.
+
+## 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`.

regkit-0.3.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.

regkit-0.3.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: regkit
+Version: 0.3.0
+Summary: A modern, pythonic interface to the Windows registry.
+Project-URL: Homepage, https://github.com/kristjanvalur/regkit
+Project-URL: Repository, https://github.com/kristjanvalur/regkit
+Project-URL: Documentation, https://kristjanvalur.github.io/regkit/
+Project-URL: Changelog, https://github.com/kristjanvalur/regkit/blob/main/CHANGELOG.md
+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
+Description-Content-Type: text/markdown
+
+# regkit
+
+[![CI](https://github.com/kristjanvalur/regkit/actions/workflows/ci.yml/badge.svg)](https://github.com/kristjanvalur/regkit/actions/workflows/ci.yml)
+
+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.
+
+`regkit` 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 regkit
+```
+
+Or the equivalent command in your preferred package manager.
+
+## Usage
+
+### Library
+```python
+from regkit 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"] = "regkit"
+    key["enabled"] = 1
+
+# pathlib-style path concatenation is also supported via "/"
+with (current_user / "Software" / "MyApp").open(write=True) as key:
+    key["theme"] = "dark"
+
+# create/open for write (create is shorthand for open(create=True, write=True))
+with current_user.create("Software", "MyApp") as key:
+    key["name"] = "regkit"
+    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(...)`.
+
+### Typical workflow
+- 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
+
+### Using registry paths
+`Key` supports constructing and round-tripping full registry paths.
+
+```python
+from regkit import Key
+
+# Construct from explicit path parts
+key = Key.from_parts(("HKCU", "Software", "MyApp"))
+
+# Construct from a full path string (either HKCU or HKEY_CURRENT_USER style)
+same_key = Key.from_path(r"HKEY_CURRENT_USER\Software\MyApp")
+
+# Read parts back (root token + subkey parts)
+assert key.parts == ("HKCU", "Software", "MyApp")
+
+# name is the final lexical segment
+assert key.name == "MyApp"
+
+# parents() returns lexical ancestors from nearest parent upward
+assert [ancestor.name for ancestor in key.parents()] == ["Software", "HKCU"]
+```
+
+Use `from_parts(...)` when you already have tokenized components, and
+`from_path(...)` when parsing user-provided registry path strings.
+
+### `Key` methods at a glance
+- `subkey(*parts)`: build a child key path without opening it
+- `open(...)`: return a new opened key for read/write access
+- `create(*parts)`: shorthand for creating/opening a key for writing
+- `exists()`: check whether a key exists
+- `walk(...)`: traverse a key tree, yielding `(key, subkey_names, value_names)` (similar to `os.walk()`)
+- `keys()`, `values()`, `items()`: iterate value names, values, or `(name, value)` pairs
+- `name`: final lexical path segment for this key
+- `parts`: tuple of key path components, including root token when present
+- `parent`: lexical parent key (or `None` at registry root)
+- `parents()`: tuple of lexical ancestors from immediate parent up to root
+- `get(name, ...)`: read a value with fallback default
+- `get_typed(...)` / `set_typed(...)`: read/write values with explicit registry type
+- `value_del(name)` or `del key[name]`: delete a value
+- `delete(...)`: delete a key (optionally recursively)
+- `as_dict()` / `from_dict(data)`: export/import a subtree structure
+
+### Default value name
+The registry's default (unnamed) value is represented by the empty string (`""`).
+
+- Iteration methods (`items()`, `items_typed()`, `keys()`) return `""` for the default value name.
+- Set/delete helpers also accept `None` as an equivalent.
+
+## 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
+  ```
+
+- Build docs:
+    ```sh
+    uv sync --group docs
+    uv run mkdocs build --strict
+    ```
+
+## License
+MIT License. See `LICENSE` for details.
+
+## Changelog
+See `CHANGELOG.md` for release history and policy.