jsonology 0.1.0__tar.gz

jsonology-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+.hypothesis/
+uv.lock

jsonology-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The jsonology authors
+
+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.

jsonology-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.5
+Name: jsonology
+Version: 0.1.0
+Summary: Evaluate a strict, tiny JSON DSL (comparisons, if, and/or/not) against a $-rooted context object
+Author: The jsonology authors
+License: MIT
+License-File: LICENSE
+Keywords: dsl,evaluator,expression,json,jsonlogic,rules
+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.10
+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 :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# jsonology
+
+Evaluate a strict, tiny JSON DSL against a context object.
+
+```python
+>>> from jsonology import evaluate
+>>> evaluate({"==": ["$.operation", "edit"]}, {"operation": "edit"})
+True
+>>> evaluate({"if": [{"==": ["$.operation", "edit"]}, "an edit!", "not an edit"]},
+...         {"operation": "delete"})
+'not an edit'
+```
+
+Expressions are JSON values, authored by trusted teammates, stored in rules or
+config. `jsonology` interprets them strictly and errors loudly. Zero runtime
+dependencies. Python ≥ 3.10, fully typed.
+
+## Install
+
+```bash
+pip install jsonology
+```
+
+## The language
+
+An **expression** is one of:
+
+- a JSON scalar — a literal (`5`, `5.5`, `"edit"`, `true`, `false`, `null`)
+- a string starting with `$.` — a path into the context
+- an operator object `{op: [args...]}` — where every argument is itself an expression
+
+### Operators
+
+| Operator | Arity | Semantics |
+| --- | --- | --- |
+| `==`, `!=` | exactly 2 | strict equality, no coercion |
+| `<`, `<=`, `>`, `>=` | exactly 2 | ordering: two numbers or two strings only |
+| `if` | exactly 3 | `[condition, if_true, if_false]`, **lazy** |
+| `and`, `or` | 1 or more | short-circuit, return strict booleans |
+| `not` | exactly 1 | negation of truthiness |
+
+Operator objects must have exactly one key. Bare lists are not expressions.
+Unknown operators are rejected with an error naming them.
+
+### Paths
+
+- `$.user.address.city` — dot-nested object access
+- `$.items.0` — numeric segments index lists (no negative indices)
+- a missing path evaluates to `null`, so `{"==": ["$.nickname", null]}` is the "is unset" idiom
+- `$` alone is the entire context (which may itself be a list)
+
+### Truthiness
+
+`if` conditions and `and`/`or`/`not` operands are interpreted Python-style:
+
+| Value | Truthy? |
+| --- | --- |
+| `false`, `null` | no |
+| `0` | no |
+| `""` | no |
+| `[]`, `{}` | no |
+| everything else | yes |
+
+### Strict typing
+
+- No coercion: `{"==": ["5", 5]}` is `false`.
+- `int` and `float` unify: `5 == 5.0` is `true`.
+- `bool` is its own type: `true == 1` is `false`, and ordering booleans is an error.
+- Cross-type equality is always decided, never an error: `{"==": [1, "1"]}` → `false`.
+- Ordering is only defined for two numbers or two strings; anything else —
+  cross-type, `null` on either side, booleans, lists — raises `EvaluationError`.
+  Note `{"<": ["$.missing", 5]}` raises, because a missing path is `null`.
+- Strings order lexicographically: `{"<": ["10", "9"]}` is `true`.
+- Equality is deep and structural over arrays and objects.
+
+### Laziness and short-circuiting
+
+`if` evaluates only the taken branch. `and` stops at the first falsy operand,
+`or` at the first truthy one — later operands are never evaluated (or errored):
+
+```python
+evaluate({"and": [False, {"<": [None, 1]}]}, {})   # False — the broken branch never runs
+```
+
+Because of this laziness, syntax errors inside dead branches stay silent —
+`evaluate({"if": [True, 1, {"frobnicate": [1]}]}, {})` is `1`.
+
+## API
+
+```python
+evaluate(expression, data) -> Any
+```
+
+- `expression`: an already-parsed Python object **or** a raw JSON string.
+  A string that is `"$"` or starts with `"$."` is treated as a path, not JSON
+  text; any other string is parsed as JSON and failures raise
+  `ExpressionSyntaxError`. There is **no escape hatch** for literal strings
+  that start with `$.` — they are always paths.
+- `data`: the context object (a mapping, or a list if your paths start `$.0` …).
+- Pure, stateless, thread-safe: neither `expression` nor `data` is mutated.
+
+Two exceptions, and only two:
+
+| Exception | Raised for |
+| --- | --- |
+| `ExpressionSyntaxError` | malformed DSL: structure, arity, unknown operator, invalid JSON text, nesting too deep |
+| `EvaluationError` | undefined operation during evaluation (ordering rules above) |
+
+Error messages name the offending operator and locate the failing
+subexpression within the expression tree, e.g. `$.if[0].==[1]` — "argument 1
+of the `==` at argument 0 of the `if`".
+
+```python
+>>> from jsonology import evaluate, ExpressionSyntaxError
+>>> try:
+...     evaluate('{"if": [{"==": ["$.a", {"x": 1, "y": 2}]}, 1, 2]}', {})
+... except ExpressionSyntaxError as e:
+...     print(e)
+operator object must have exactly one key, got 2: {"x": 1, "y": 2} (at $.if[0].==[1])
+```
+
+## Limitations (deliberate, v1)
+
+- No literal escape hatch for strings starting with `$.`.
+- No array or object literals: every operand is a scalar, a path, or a nested
+  operator. `{"==": ["$.tags", ["a", "b"]]}` is a syntax error (compare two
+  paths instead: `{"==": ["$.tags", "$.want"]}`), and an object literal like
+  `{"x": 1}` in operand position fails as an unknown operator `'x'`.
+- Dead `if` branches and short-circuited `and`/`or` operands are never
+  evaluated, so their syntax is not validated.
+- Context keys containing dots cannot be addressed by paths.
+- The contract is JSON types. Non-JSON Python values in `data` (datetime,
+  Decimal, …) are out of contract — same-type pairs fall through to Python
+  semantics, everything else is unspecified. For time comparisons store
+  ISO-8601 strings (lexicographic `<` does the right thing) or epoch integers.
+- No custom operators, no depth or size limits (trusted-input model).
+- No `compile()` step — expressions are interpreted directly; reach for one
+  only if profiling demands it.
+
+## Development
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+python -m pytest          # 149 cases: table-driven goldens + property-based invariants
+python -m ruff check .
+python -m mypy
+```
+
+The property suite (Hypothesis) checks the contract as invariants: only the
+two documented exceptions ever escape, `==`/ordering obey the algebraic laws
+(reflexivity, symmetry, transitivity, connexity), truthiness matches the
+reference table, path resolution matches an independent reference walk, dead
+branches never evaluate, inputs are never mutated, and JSON-text input agrees
+with object input.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

jsonology-0.1.0/README.md

@@ -0,0 +1,158 @@
+# jsonology
+
+Evaluate a strict, tiny JSON DSL against a context object.
+
+```python
+>>> from jsonology import evaluate
+>>> evaluate({"==": ["$.operation", "edit"]}, {"operation": "edit"})
+True
+>>> evaluate({"if": [{"==": ["$.operation", "edit"]}, "an edit!", "not an edit"]},
+...         {"operation": "delete"})
+'not an edit'
+```
+
+Expressions are JSON values, authored by trusted teammates, stored in rules or
+config. `jsonology` interprets them strictly and errors loudly. Zero runtime
+dependencies. Python ≥ 3.10, fully typed.
+
+## Install
+
+```bash
+pip install jsonology
+```
+
+## The language
+
+An **expression** is one of:
+
+- a JSON scalar — a literal (`5`, `5.5`, `"edit"`, `true`, `false`, `null`)
+- a string starting with `$.` — a path into the context
+- an operator object `{op: [args...]}` — where every argument is itself an expression
+
+### Operators
+
+| Operator | Arity | Semantics |
+| --- | --- | --- |
+| `==`, `!=` | exactly 2 | strict equality, no coercion |
+| `<`, `<=`, `>`, `>=` | exactly 2 | ordering: two numbers or two strings only |
+| `if` | exactly 3 | `[condition, if_true, if_false]`, **lazy** |
+| `and`, `or` | 1 or more | short-circuit, return strict booleans |
+| `not` | exactly 1 | negation of truthiness |
+
+Operator objects must have exactly one key. Bare lists are not expressions.
+Unknown operators are rejected with an error naming them.
+
+### Paths
+
+- `$.user.address.city` — dot-nested object access
+- `$.items.0` — numeric segments index lists (no negative indices)
+- a missing path evaluates to `null`, so `{"==": ["$.nickname", null]}` is the "is unset" idiom
+- `$` alone is the entire context (which may itself be a list)
+
+### Truthiness
+
+`if` conditions and `and`/`or`/`not` operands are interpreted Python-style:
+
+| Value | Truthy? |
+| --- | --- |
+| `false`, `null` | no |
+| `0` | no |
+| `""` | no |
+| `[]`, `{}` | no |
+| everything else | yes |
+
+### Strict typing
+
+- No coercion: `{"==": ["5", 5]}` is `false`.
+- `int` and `float` unify: `5 == 5.0` is `true`.
+- `bool` is its own type: `true == 1` is `false`, and ordering booleans is an error.
+- Cross-type equality is always decided, never an error: `{"==": [1, "1"]}` → `false`.
+- Ordering is only defined for two numbers or two strings; anything else —
+  cross-type, `null` on either side, booleans, lists — raises `EvaluationError`.
+  Note `{"<": ["$.missing", 5]}` raises, because a missing path is `null`.
+- Strings order lexicographically: `{"<": ["10", "9"]}` is `true`.
+- Equality is deep and structural over arrays and objects.
+
+### Laziness and short-circuiting
+
+`if` evaluates only the taken branch. `and` stops at the first falsy operand,
+`or` at the first truthy one — later operands are never evaluated (or errored):
+
+```python
+evaluate({"and": [False, {"<": [None, 1]}]}, {})   # False — the broken branch never runs
+```
+
+Because of this laziness, syntax errors inside dead branches stay silent —
+`evaluate({"if": [True, 1, {"frobnicate": [1]}]}, {})` is `1`.
+
+## API
+
+```python
+evaluate(expression, data) -> Any
+```
+
+- `expression`: an already-parsed Python object **or** a raw JSON string.
+  A string that is `"$"` or starts with `"$."` is treated as a path, not JSON
+  text; any other string is parsed as JSON and failures raise
+  `ExpressionSyntaxError`. There is **no escape hatch** for literal strings
+  that start with `$.` — they are always paths.
+- `data`: the context object (a mapping, or a list if your paths start `$.0` …).
+- Pure, stateless, thread-safe: neither `expression` nor `data` is mutated.
+
+Two exceptions, and only two:
+
+| Exception | Raised for |
+| --- | --- |
+| `ExpressionSyntaxError` | malformed DSL: structure, arity, unknown operator, invalid JSON text, nesting too deep |
+| `EvaluationError` | undefined operation during evaluation (ordering rules above) |
+
+Error messages name the offending operator and locate the failing
+subexpression within the expression tree, e.g. `$.if[0].==[1]` — "argument 1
+of the `==` at argument 0 of the `if`".
+
+```python
+>>> from jsonology import evaluate, ExpressionSyntaxError
+>>> try:
+...     evaluate('{"if": [{"==": ["$.a", {"x": 1, "y": 2}]}, 1, 2]}', {})
+... except ExpressionSyntaxError as e:
+...     print(e)
+operator object must have exactly one key, got 2: {"x": 1, "y": 2} (at $.if[0].==[1])
+```
+
+## Limitations (deliberate, v1)
+
+- No literal escape hatch for strings starting with `$.`.
+- No array or object literals: every operand is a scalar, a path, or a nested
+  operator. `{"==": ["$.tags", ["a", "b"]]}` is a syntax error (compare two
+  paths instead: `{"==": ["$.tags", "$.want"]}`), and an object literal like
+  `{"x": 1}` in operand position fails as an unknown operator `'x'`.
+- Dead `if` branches and short-circuited `and`/`or` operands are never
+  evaluated, so their syntax is not validated.
+- Context keys containing dots cannot be addressed by paths.
+- The contract is JSON types. Non-JSON Python values in `data` (datetime,
+  Decimal, …) are out of contract — same-type pairs fall through to Python
+  semantics, everything else is unspecified. For time comparisons store
+  ISO-8601 strings (lexicographic `<` does the right thing) or epoch integers.
+- No custom operators, no depth or size limits (trusted-input model).
+- No `compile()` step — expressions are interpreted directly; reach for one
+  only if profiling demands it.
+
+## Development
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+python -m pytest          # 149 cases: table-driven goldens + property-based invariants
+python -m ruff check .
+python -m mypy
+```
+
+The property suite (Hypothesis) checks the contract as invariants: only the
+two documented exceptions ever escape, `==`/ordering obey the algebraic laws
+(reflexivity, symmetry, transitivity, connexity), truthiness matches the
+reference table, path resolution matches an independent reference walk, dead
+branches never evaluate, inputs are never mutated, and JSON-text input agrees
+with object input.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

jsonology-0.1.0/SPEC.md

@@ -0,0 +1,151 @@
+# jsonology — Specification (v1)
+
+Status: confirmed by owner after design review (3 grilling rounds, 2026).
+
+## Purpose
+
+A from-scratch, zero-dependency Python library that evaluates a JSON DSL
+against a context object. Expressions are authored by trusted teammates and
+stored in rules/config; the library errors loudly and applies no artificial
+input limits.
+
+Package name `jsonology` (verified free on PyPI). Originally `jsonlogi`,
+renamed before first release: the old name was one typo away from
+`jsonlogic` / `jsonlogic-py`, which are different tools.
+
+## Grammar
+
+An **expression** is one of:
+
+- a JSON scalar (number, string, `true`, `false`, `null`) — a literal
+- a string starting with `$.` — a path into the context
+- an operator object: `{op: [args...]}` where every arg is itself an expression
+- any of the above nested recursively
+
+Rules:
+
+- Operator objects have **exactly one key**; otherwise `ExpressionSyntaxError`.
+- Bare lists are not expressions → `ExpressionSyntaxError`.
+- Consequently there are **no array or object literals**: a bare list operand
+  is a syntax error, and a single-key dict in operand position is always an
+  operator object (`{"x": 1}` there fails as an unknown operator). Values of
+  any shape enter expressions only through paths.
+- Unknown operator → `ExpressionSyntaxError` naming the operator.
+- **Strict arity**: comparisons exactly 2 args · `if` exactly 3 · `and`/`or`
+  ≥ 1 · `not` exactly 1.
+- No escape hatch for literal strings that start with `$.` (documented
+  limitation). Context keys containing dots are unsupported (documented
+  limitation).
+- No custom-operator registration in v1.
+
+## Paths
+
+- `$.user.address.city` — dot-nested object access.
+- `$.items.0` — numeric segments index lists.
+- Missing path evaluates to `null`, so `{"==": ["$.nickname", null]}` is the
+  "is unset" idiom.
+- Bare `$` evaluates to the entire context; the context may itself be a list
+  (`evaluate("$.0", ["a", "b"])` → `"a"`).
+
+## Operators (10)
+
+`==` `!=` `>` `<` `>=` `<=` `if` `and` `or` `not`
+
+### Comparisons — strict, no coercion
+
+- `"5" == 5` → `false` (and `!=` → `true`); cross-type equality is always
+  `false`/`true`, never raises.
+- `5 == 5.0` → `true` (int/float unify).
+- `null == null` → `true`.
+- `true == 1` → `false`: `bool` is a **distinct type** from numbers.
+- Ordering (`>` `<` `>=` `<=`):
+  - numbers with numbers, strings with strings (lexicographic) — defined.
+  - any cross-type pair, or any operand `null`, or two booleans →
+    `EvaluationError`.
+- `!=` is exactly the negation of `==` in every case.
+
+### `if` — `[condition, if_true, if_false]`
+
+Lazy: only the taken branch is evaluated. Strict 3-arity. Corollary: dead
+branches (and short-circuited `and`/`or` operands) are never validated, so
+syntax errors inside them stay silent.
+
+### `and` / `or` / `not`
+
+- `and`/`or`: n-ary (≥ 1), **short-circuit** (evaluation stops at the first
+  decisive operand), return strict `true`/`false`.
+- `not`: unary, returns strict `true`/`false`.
+
+### Truthiness (Python-style)
+
+Applies to `if` conditions and `and`/`or`/`not` operands:
+
+| value            | truthy? |
+| ---------------- | ------- |
+| `false`, `null`  | no      |
+| `0`              | no      |
+| `""`             | no      |
+| `[]`, `{}`       | no      |
+| everything else  | yes     |
+
+## Errors
+
+Exactly two exception types:
+
+- `ExpressionSyntaxError` — malformed DSL (structure, arity, unknown operator,
+  unparseable JSON string input, nesting too deep).
+- `EvaluationError` — type trouble during evaluation (undefined ordering).
+
+Error messages carry the offending operator, a snippet of its arguments, and
+the path of the failing subexpression within the expression tree
+(e.g. `$.if[0].==[1]`). Python `RecursionError` is wrapped as
+`ExpressionSyntaxError("expression too deeply nested")`.
+
+## API
+
+```python
+evaluate(expression, data: Mapping) -> Any
+```
+
+- Accepts an already-parsed Python object **or** a raw JSON string; string
+  parse failures raise `ExpressionSyntaxError`.
+- Pure, stateless, thread-safe; never mutates `expression` or `data`.
+- Returns any JSON value.
+
+Non-JSON Python types in `data` (datetime, Decimal, …) are out of contract.
+README recommends ISO-8601 strings for time comparisons (lexicographic `<`
+works); NaN and other non-JSON floats are likewise out of contract.
+
+## Build
+
+- Direct interpretation — walk the JSON each call; no compile step. Add
+  `compile()` only if profiling demands.
+- MIT · Python ≥ 3.10 · `src/jsonology/` layout · `py.typed` · hatchling ·
+  zero runtime dependencies · publish to PyPI once tests + README exist.
+
+## Tests & docs
+
+- pytest, table-driven golden tests (~90 cases): every operator × every edge
+  (missing paths, cross-type, nesting, laziness, short-circuit) plus
+  error-message assertions.
+- Property-based tests (Hypothesis): totality of the two-exception contract
+  over fuzzed expressions; equality and ordering algebraic laws; truthiness
+  against a reference table; differential path resolution; laziness; purity
+  and determinism; JSON-text vs object input agreement.
+- Docs: a thorough README only (operator table, truthiness table, missing-path
+  rules, the `$.` literal caveat). No doc site until a second consumer exists.
+
+## Decision log (rejections worth remembering)
+
+- **Reuse**: rejected — JsonLogic's Python ecosystem is alpha-grade and the
+  syntax differs (`$.x` vs `{"var": "x"}`).
+- **No coercion anywhere**: `"5" != 5`; strict typing chosen over JS-style
+  coercion.
+- **No variadic `if`**: else-chains expressed by nesting; strict arity
+  throughout.
+- **`and`/`or` return strict booleans**, not the decisive operand — the
+  default-value idiom gets a dedicated `coalesce` operator someday, if wanted.
+- **Python-style truthiness** (`[]`/`{}` falsy), not JS-style.
+- **`bool` distinct from `int`**: guards against `$.count` matching `true`.
+- **No operator extensibility, no depth limits, no input size limits** in v1
+  (trusted-input model).

jsonology-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jsonology"
+version = "0.1.0"
+description = "Evaluate a strict, tiny JSON DSL (comparisons, if, and/or/not) against a $-rooted context object"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "The jsonology authors" }]
+requires-python = ">=3.10"
+keywords = ["json", "dsl", "expression", "rules", "evaluator", "jsonlogic"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.11", "hypothesis>=6.100"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jsonology"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]

jsonology-0.1.0/src/jsonology/__init__.py

@@ -0,0 +1,6 @@
+"""jsonology — evaluate a strict, tiny JSON DSL against a ``$``-rooted context object."""
+
+from jsonology.core import EvaluationError, ExpressionSyntaxError, evaluate
+
+__all__ = ["EvaluationError", "ExpressionSyntaxError", "evaluate"]
+__version__ = "0.1.0"