dictwalk 0.1.0__tar.gz

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

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tox:
+    name: ${{ matrix.tox_env }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - tox_env: py310
+            python_version: "3.10"
+          - tox_env: py311
+            python_version: "3.11"
+          - tox_env: py312
+            python_version: "3.12"
+          - tox_env: py313
+            python_version: "3.13"
+          - tox_env: py314
+            python_version: "3.14"
+          - tox_env: lint
+            python_version: "3.13"
+          - tox_env: type
+            python_version: "3.13"
+          - tox_env: deptry
+            python_version: "3.13"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python_version }}
+          allow-prereleases: true
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Run tox
+        run: uv run tox -e ${{ matrix.tox_env }}

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

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Resolve version
+        run: echo "VERSION=$(uv version --short)" >> "$GITHUB_ENV"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          test -n "$UV_PUBLISH_TOKEN"
+          uv publish --token "$UV_PUBLISH_TOKEN"
+
+      - name: Tag release
+        run: |
+          test -n "$VERSION"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag "v$VERSION"
+          git push origin "v$VERSION"

dictwalk-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+target/
+
+# Virtual environments
+.venv
+
+.tox/
+.pytest_cache/
+.ruff_cache/

dictwalk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

dictwalk-0.1.0/.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+    "python.analysis.typeCheckingMode": "off",
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

dictwalk-0.1.0/Makefile

@@ -0,0 +1,23 @@
+.PHONY: test lint type deptry build release ci
+
+test:
+	uv run tox -e py310,py311,py312,py313,py314
+
+lint:
+	uv run tox -e lint
+
+type:
+	uv run tox -e type
+
+deptry:
+	uv run tox -e deptry
+
+build:
+	uv build
+
+release:
+	@test -n "$$PYPI_TOKEN" || (echo "PYPI_TOKEN is not set"; exit 1)
+	uv publish --token "$$PYPI_TOKEN"
+
+ci:
+	uv run tox -e py310,py311,py312,py313,py314,lint,type,deptry

dictwalk-0.1.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: dictwalk
+Version: 0.1.0
+Summary: Dict path traversal and mutation utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# dictwalk
+
+> This library is basically overengineered and ridiculous.  
+> It mostly exists because I kept asking an AI to add one more feature, then one more, then one more.
+> Then I asked the AI to come up with features and I said screw it add them all.
+> Please do not use this instead of just writing normal code.  
+> This is bored-developer scope creep in library form.
+> The original idea was basically “jq/yq, but for Python dicts, and here we are”.
+> I hope you get some use out of it, because I didn't.
+
+`dictwalk` is a small utility for traversing and mutating nested Python dict/list data using path expressions.
+
+It supports:
+- Deep reads (`get`)
+- Existence checks (`exists`)
+- In-place writes (`set`)
+- In-place removals (`unset`)
+- Predicate filtering for lists
+- Wildcards (`*`, `**`)
+- Transform/filter pipelines (`|$filter`)
+
+## Requirements
+
+- Python `>=3.10`
+
+## Installation
+
+From source:
+
+```bash
+pip install .
+```
+
+For local development:
+
+```bash
+uv sync
+```
+
+## Quick Start
+
+```python
+from dictwalk import dictwalk
+
+data = {
+    "a": {
+        "users": [
+            {"id": 1, "name": "Ada", "active": True},
+            {"id": 2, "name": "Lin", "active": False},
+        ]
+    }
+}
+
+# Read
+names = dictwalk.get(data, "a.users[].name")
+# ["Ada", "Lin"]
+
+# Filter and map
+active_names = dictwalk.get(data, "a.users[?active==True].name[]")
+# ["Ada"]
+
+# Write
+dictwalk.set(data, "a.users[?id==2].active", True)
+
+# Unset
+dictwalk.unset(data, "a.users[?id==1].name")
+```
+
+## Path Syntax
+
+### Dot traversal
+
+```text
+a.b.c
+```
+
+Read nested object keys.
+
+### List map
+
+```text
+a.items[].id
+```
+
+Apply the next token to every item in a list.
+
+### List index and slice
+
+```text
+a.items[0]
+a.items[-1]
+a.items[1:3]
+```
+
+### Predicates
+
+```text
+a.items[?id==1]
+a.items[?score>=10]
+```
+
+List predicates support:
+- `==`, `!=`, `>`, `<`, `>=`, `<=`
+
+### Predicate filters
+
+Use registered filters on predicate values:
+
+```text
+a.items[?id==$even]
+a.items[?id==$gt(5)&&$lt(10)]
+a.items[?id==!$odd]
+```
+
+Boolean operators in predicate filters:
+- `&&` (and)
+- `||` (or)
+- `!` (not)
+- parentheses for grouping
+
+### Wildcards
+
+```text
+a.*.id
+a.**.id
+```
+
+- `*`: one level
+- `**`: deep descendant traversal
+
+### Output transforms
+
+Apply filters to the final read value:
+
+```text
+a.value|$double|$string
+a.list|$max
+a.list|$double[]|$max
+```
+
+## API
+
+## `dictwalk.get(data, path, default=None, strict=False)`
+
+- Returns resolved value.
+- If `strict=False`: resolution failures return `default`.
+- If `strict=True`: raises `DictWalkResolutionError`.
+
+Special root token support in read paths:
+
+```text
+$$root.x
+a.b.$$root.x
+```
+
+## `dictwalk.exists(data, path, strict=False) -> bool`
+
+- Returns `True` if path resolves, else `False`.
+- If `strict=True`, raises `DictWalkResolutionError` on resolution failures.
+
+## `dictwalk.set(data, path, value, *, strict=False, create_missing=True, create_filter_match=True, overwrite_incompatible=True) -> dict`
+
+Mutates and returns the same `data` object.
+
+`value` can be:
+- A direct value (`42`, `"x"`, `{"k": 1}`)
+- A filter string (`"$double"`, `"$add(2)|$string"`)
+- A root reference expression:
+  - `$$root`
+  - `$$root.some.path`
+  - `$$root.some.path|$filter`
+
+Notes:
+- `$$root` is valid in `value`, not in write `path`.
+- With `strict=True`, parent path must already resolve.
+
+## `dictwalk.unset(data, path, *, strict=False) -> dict`
+
+Removes targeted values in-place and returns the same object.
+
+At terminal paths this can:
+- Remove dict keys
+- Remove list indexes/slices
+- Remove list items matching a filter
+
+## Filters
+
+Built-in filters include arithmetic, string, collection, predicate, and datetime utilities.
+
+Examples:
+- Arithmetic: `$inc`, `$double`, `$add(2)`, `$round(1)`
+- Collection: `$len`, `$max`, `$min`, `$sum`, `$avg`, `$unique`
+- String: `$lower`, `$upper`, `$replace("a","b")`, `$split(",")`
+- Predicates: `$even`, `$odd`, `$gt(10)`, `$contains("x")`
+- Datetime: `$to_datetime`, `$timestamp`, `$age_seconds`, `$before(...)`, `$after(...)`
+
+Register custom filters:
+
+```python
+from dictwalk import dictwalk
+
+dictwalk.register_path_filter("triple", lambda x: x * 3)
+
+value = dictwalk.get({"a": {"b": 2}}, "a.b|$triple")
+# 6
+```
+
+## Errors
+
+From `dictwalk.errors`:
+- `DictWalkError` (base)
+- `DictWalkParseError`
+- `DictWalkOperatorError`
+- `DictWalkResolutionError`
+
+Use `strict=True` when you want explicit failures instead of fallback defaults.
+
+## Development
+
+Run tests:
+
+```bash
+make test
+```
+
+Run lint/type/dependency checks:
+
+```bash
+make lint
+make type
+make deptry
+```
+
+Run everything:
+
+```bash
+make ci
+```
+
+Direct tox usage:
+
+```bash
+uv run tox -e py310,py311,py312,py313,py314,lint,type,deptry
+```

dictwalk-0.1.0/README.md

@@ -0,0 +1,244 @@
+# dictwalk
+
+> This library is basically overengineered and ridiculous.  
+> It mostly exists because I kept asking an AI to add one more feature, then one more, then one more.
+> Then I asked the AI to come up with features and I said screw it add them all.
+> Please do not use this instead of just writing normal code.  
+> This is bored-developer scope creep in library form.
+> The original idea was basically “jq/yq, but for Python dicts, and here we are”.
+> I hope you get some use out of it, because I didn't.
+
+`dictwalk` is a small utility for traversing and mutating nested Python dict/list data using path expressions.
+
+It supports:
+- Deep reads (`get`)
+- Existence checks (`exists`)
+- In-place writes (`set`)
+- In-place removals (`unset`)
+- Predicate filtering for lists
+- Wildcards (`*`, `**`)
+- Transform/filter pipelines (`|$filter`)
+
+## Requirements
+
+- Python `>=3.10`
+
+## Installation
+
+From source:
+
+```bash
+pip install .
+```
+
+For local development:
+
+```bash
+uv sync
+```
+
+## Quick Start
+
+```python
+from dictwalk import dictwalk
+
+data = {
+    "a": {
+        "users": [
+            {"id": 1, "name": "Ada", "active": True},
+            {"id": 2, "name": "Lin", "active": False},
+        ]
+    }
+}
+
+# Read
+names = dictwalk.get(data, "a.users[].name")
+# ["Ada", "Lin"]
+
+# Filter and map
+active_names = dictwalk.get(data, "a.users[?active==True].name[]")
+# ["Ada"]
+
+# Write
+dictwalk.set(data, "a.users[?id==2].active", True)
+
+# Unset
+dictwalk.unset(data, "a.users[?id==1].name")
+```
+
+## Path Syntax
+
+### Dot traversal
+
+```text
+a.b.c
+```
+
+Read nested object keys.
+
+### List map
+
+```text
+a.items[].id
+```
+
+Apply the next token to every item in a list.
+
+### List index and slice
+
+```text
+a.items[0]
+a.items[-1]
+a.items[1:3]
+```
+
+### Predicates
+
+```text
+a.items[?id==1]
+a.items[?score>=10]
+```
+
+List predicates support:
+- `==`, `!=`, `>`, `<`, `>=`, `<=`
+
+### Predicate filters
+
+Use registered filters on predicate values:
+
+```text
+a.items[?id==$even]
+a.items[?id==$gt(5)&&$lt(10)]
+a.items[?id==!$odd]
+```
+
+Boolean operators in predicate filters:
+- `&&` (and)
+- `||` (or)
+- `!` (not)
+- parentheses for grouping
+
+### Wildcards
+
+```text
+a.*.id
+a.**.id
+```
+
+- `*`: one level
+- `**`: deep descendant traversal
+
+### Output transforms
+
+Apply filters to the final read value:
+
+```text
+a.value|$double|$string
+a.list|$max
+a.list|$double[]|$max
+```
+
+## API
+
+## `dictwalk.get(data, path, default=None, strict=False)`
+
+- Returns resolved value.
+- If `strict=False`: resolution failures return `default`.
+- If `strict=True`: raises `DictWalkResolutionError`.
+
+Special root token support in read paths:
+
+```text
+$$root.x
+a.b.$$root.x
+```
+
+## `dictwalk.exists(data, path, strict=False) -> bool`
+
+- Returns `True` if path resolves, else `False`.
+- If `strict=True`, raises `DictWalkResolutionError` on resolution failures.
+
+## `dictwalk.set(data, path, value, *, strict=False, create_missing=True, create_filter_match=True, overwrite_incompatible=True) -> dict`
+
+Mutates and returns the same `data` object.
+
+`value` can be:
+- A direct value (`42`, `"x"`, `{"k": 1}`)
+- A filter string (`"$double"`, `"$add(2)|$string"`)
+- A root reference expression:
+  - `$$root`
+  - `$$root.some.path`
+  - `$$root.some.path|$filter`
+
+Notes:
+- `$$root` is valid in `value`, not in write `path`.
+- With `strict=True`, parent path must already resolve.
+
+## `dictwalk.unset(data, path, *, strict=False) -> dict`
+
+Removes targeted values in-place and returns the same object.
+
+At terminal paths this can:
+- Remove dict keys
+- Remove list indexes/slices
+- Remove list items matching a filter
+
+## Filters
+
+Built-in filters include arithmetic, string, collection, predicate, and datetime utilities.
+
+Examples:
+- Arithmetic: `$inc`, `$double`, `$add(2)`, `$round(1)`
+- Collection: `$len`, `$max`, `$min`, `$sum`, `$avg`, `$unique`
+- String: `$lower`, `$upper`, `$replace("a","b")`, `$split(",")`
+- Predicates: `$even`, `$odd`, `$gt(10)`, `$contains("x")`
+- Datetime: `$to_datetime`, `$timestamp`, `$age_seconds`, `$before(...)`, `$after(...)`
+
+Register custom filters:
+
+```python
+from dictwalk import dictwalk
+
+dictwalk.register_path_filter("triple", lambda x: x * 3)
+
+value = dictwalk.get({"a": {"b": 2}}, "a.b|$triple")
+# 6
+```
+
+## Errors
+
+From `dictwalk.errors`:
+- `DictWalkError` (base)
+- `DictWalkParseError`
+- `DictWalkOperatorError`
+- `DictWalkResolutionError`
+
+Use `strict=True` when you want explicit failures instead of fallback defaults.
+
+## Development
+
+Run tests:
+
+```bash
+make test
+```
+
+Run lint/type/dependency checks:
+
+```bash
+make lint
+make type
+make deptry
+```
+
+Run everything:
+
+```bash
+make ci
+```
+
+Direct tox usage:
+
+```bash
+uv run tox -e py310,py311,py312,py313,py314,lint,type,deptry
+```

dictwalk-0.1.0/dictwalk/__init__.py

@@ -0,0 +1,4 @@
+from .dictwalk import dictwalk, DictWalk
+
+
+__all__ = ["dictwalk", "DictWalk"]