pycedar 0.2.2__tar.gz → 0.3.1__tar.gz

{pycedar-0.2.2 → pycedar-0.3.1}/CHANGELOG.md

@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-09-16
+
+### Changed
+
+- Lookups, writes and traversals are faster, with no change in behaviour.
+
+  `base_trie` declared only the operations that do not depend on the key type.
+  Everything else — `exact_match_search()`, `suffix()`, `set()`, `update()`,
+  `traverse()`, `erase()` and the prefix queries — lived only on the
+  specialisations, while the shared helpers and `pycedar.dict` hold a
+  `base_trie` reference. Every one of those calls was therefore a Python method
+  lookup by name, with each C integer argument boxed into a Python `int` on the
+  way in. They are now declared on `base_trie`, so the calls dispatch through
+  the vtable instead. The key parameter is typed as `object` because the three
+  specialisations accept different types; each one still validates what it is
+  given.
+- `common_prefix_search()` no longer walks the trie twice. cedar advances one
+  position per byte of the key, so the result can never exceed `len(key)`;
+  sizing the buffer to that removes the counting pass entirely.
+  `common_prefix_predict()` has no such bound, so it starts from a speculative
+  buffer and retries once, at the exact size cedar reports, only when the
+  results do not fit.
+
+  Measured on 20000 random keys, CPython 3.13, nanoseconds per operation:
+
+  | operation | 0.3.0 | 0.3.1 |
+  | --- | --- | --- |
+  | `key in d` | 98 | 52 |
+  | `d[key]` | 107 | 61 |
+  | `d.get(key)` | 114 | 67 |
+  | `d.setdefault(key)` | 103 | 67 |
+  | `d.get_node(key)` | 145 | 99 |
+  | `d[key] = value` | 78 | 61 |
+  | `d.set(key, value)` | 85 | 70 |
+  | `d.update(key, delta)` | 90 | 75 |
+  | `common_prefix_predict()` | 3568 | 2572 |
+  | `list(d.items())` per key | 188 | 163 |
+
+  `exact_match_search()` called directly on a specialisation stayed at 82 ns,
+  as it should: that call was never the dynamic one.
+
+## [0.3.0] - 2026-09-16
+
+### Changed
+
+- **Breaking**: storing `-1` or `-2` now raises `ValueError`. They are cedar's
+  sentinels, `base_trie.NO_VALUE` and `base_trie.NO_PATH`, and accepting them
+  silently corrupted the trie: `-1` made a key invisible to `in`, `get()` and
+  `d[key]` while leaving it visible to iteration, and `-2` terminated every
+  traversal early, hiding each key stored after it. Anyone affected was already
+  unable to read those values back, so the exception replaces silent data loss
+  rather than working behaviour.
+
+  The check lives in the writers shared by both layers, so `d[key] = value`,
+  `set()`, `setdefault()` and the trie level `set()` all enforce it.
+  `update()` validates the resulting value instead of the delta, because an
+  ordinary delta can still land on a sentinel; when it does, the delta is
+  rolled back and the stored value is left untouched. A key created by such a
+  rejected `update()` is left registered with the value `0`.
+
+  As a consequence, `get()` returning `NO_VALUE` is now unambiguous: no stored
+  value can collide with it.
+
 ## [0.2.2] - 2026-09-16
 
 ### Added
@@ -166,7 +229,9 @@ records; the corresponding tags were added retroactively.
 
 - Build failure with clang on macOS.
 
-[Unreleased]: https://github.com/akivajp/pycedar/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/akivajp/pycedar/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/akivajp/pycedar/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/akivajp/pycedar/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/akivajp/pycedar/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/akivajp/pycedar/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/akivajp/pycedar/compare/v0.1.3...v0.2.0

{pycedar-0.2.2/pycedar.egg-info → pycedar-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycedar
-Version: 0.2.2
+Version: 0.3.1
 Summary: Python binding of cedar (implementation of efficiently-updatable double-array trie) using Cython
 Home-page: https://github.com/akivajp/pycedar
 Author: Akiva Miura
@@ -332,16 +332,38 @@ A ``dict``-like façade over a trie. ``pycedar.dict(key_type)`` accepts ``str``
 Values are stored as C ``int``, so they must fit in ``-2**31 .. 2**31-1``;
 anything larger raises ``OverflowError``.
 
-Two values collide with cedar's sentinels and must not be stored:
+``-1`` and ``-2`` are cedar's sentinels — ``base_trie.NO_VALUE`` and
+``base_trie.NO_PATH`` — and every writer rejects them:
 
-* **``-1`` (``NO_VALUE``)** — the key is stored and appears during iteration,
-  but ``in``, ``get()`` and ``d[key]`` all report it as absent.
-* **``-2`` (``NO_PATH``)** — this value terminates traversal, so ``items()``,
-  ``keys()``, ``values()``, ``find()`` and friends silently stop at that key and
-  never reach the rest of the trie.
+```python
+>>> limited = pycedar.dict()
+>>> limited['key'] = -1
+Traceback (most recent call last):
+    ...
+ValueError: -1 is reserved and cannot be stored: ...
+```
+
+``update()`` checks the resulting value rather than the delta, because a
+perfectly ordinary delta can still land on a sentinel. When it does, the delta
+is rolled back and the stored value is left untouched:
+
+```python
+>>> limited['counter'] = 1
+>>> limited.update('counter', -3)     # 1 + (-3) == -2
+Traceback (most recent call last):
+    ...
+ValueError: -2 is reserved and cannot be stored: ...
+>>> limited['counter']
+1
+```
+
+Every other value round trips, negative ones included.
 
-Storing non-negative values avoids both problems. Every other value, including
-other negative numbers, round trips normally.
+Before 0.3.0 these two were accepted and silently corrupted the trie: ``-1``
+made a key invisible to ``in``, ``get()`` and ``d[key]`` while leaving it
+visible to iteration, and ``-2`` ended every traversal early, hiding each key
+that came after it. If you are upgrading and were storing either, the values
+were not being read back correctly in the first place.
 
 ### The serialization format is platform-dependent and unauthenticated
 

{pycedar-0.2.2 → pycedar-0.3.1}/README.ja.md

@@ -291,16 +291,37 @@ applet 2
 値は C の ``int`` として格納されるため、``-2**31 .. 2**31-1`` に収まる必要が
 あります。これを超えると ``OverflowError`` になります。
 
-次の 2 つの値は cedar の番兵値と衝突するため、格納してはいけません。
+``-1`` と ``-2`` は cedar の番兵値（``base_trie.NO_VALUE`` と
+``base_trie.NO_PATH``）であり、すべての書き込み経路が拒否します。
 
-* **``-1``（``NO_VALUE``）** — キーは格納され走査にも現れますが、``in``、
-  ``get()``、``d[key]`` のいずれからも「存在しない」と報告されます。
-* **``-2``（``NO_PATH``）** — この値は走査の終端条件そのものであるため、
-  ``items()``、``keys()``、``values()``、``find()`` などが**そのキーで静かに停止し、
-  それ以降のトライに到達しなくなります**。
+```python
+>>> limited = pycedar.dict()
+>>> limited['key'] = -1
+Traceback (most recent call last):
+    ...
+ValueError: -1 is reserved and cannot be stored: ...
+```
+
+``update()`` はデルタではなく**加算結果**を検査します。ごく普通のデルタでも
+結果が番兵値に着地しうるためです。着地した場合はデルタを巻き戻すので、
+格納されている値は変化しません。
+
+```python
+>>> limited['counter'] = 1
+>>> limited.update('counter', -3)     # 1 + (-3) == -2
+Traceback (most recent call last):
+    ...
+ValueError: -2 is reserved and cannot be stored: ...
+>>> limited['counter']
+1
+```
+
+これ以外の値は、負数を含めて通常どおり往復します。
 
-値を非負に限れば、いずれの問題も回避できます。それ以外の値は、負数を含めて
-通常どおり往復します。
+0.3.0 より前はこの 2 つを受け付けてしまい、トライを静かに壊していました。
+``-1`` はキーを ``in`` / ``get()`` / ``d[key]`` から不可視にする一方で走査には
+現れ、``-2`` は走査をそこで打ち切って以降のキーをすべて隠していました。
+いずれかを格納していた場合、そもそも正しく読み出せていなかったことになります。
 
 ### シリアライズ形式はプラットフォーム依存であり、検証機構を持たない
 

{pycedar-0.2.2 → pycedar-0.3.1}/README.md

@@ -294,16 +294,38 @@ A ``dict``-like façade over a trie. ``pycedar.dict(key_type)`` accepts ``str``
 Values are stored as C ``int``, so they must fit in ``-2**31 .. 2**31-1``;
 anything larger raises ``OverflowError``.
 
-Two values collide with cedar's sentinels and must not be stored:
+``-1`` and ``-2`` are cedar's sentinels — ``base_trie.NO_VALUE`` and
+``base_trie.NO_PATH`` — and every writer rejects them:
 
-* **``-1`` (``NO_VALUE``)** — the key is stored and appears during iteration,
-  but ``in``, ``get()`` and ``d[key]`` all report it as absent.
-* **``-2`` (``NO_PATH``)** — this value terminates traversal, so ``items()``,
-  ``keys()``, ``values()``, ``find()`` and friends silently stop at that key and
-  never reach the rest of the trie.
+```python
+>>> limited = pycedar.dict()
+>>> limited['key'] = -1
+Traceback (most recent call last):
+    ...
+ValueError: -1 is reserved and cannot be stored: ...
+```
+
+``update()`` checks the resulting value rather than the delta, because a
+perfectly ordinary delta can still land on a sentinel. When it does, the delta
+is rolled back and the stored value is left untouched:
+
+```python
+>>> limited['counter'] = 1
+>>> limited.update('counter', -3)     # 1 + (-3) == -2
+Traceback (most recent call last):
+    ...
+ValueError: -2 is reserved and cannot be stored: ...
+>>> limited['counter']
+1
+```
+
+Every other value round trips, negative ones included.
 
-Storing non-negative values avoids both problems. Every other value, including
-other negative numbers, round trips normally.
+Before 0.3.0 these two were accepted and silently corrupted the trie: ``-1``
+made a key invisible to ``in``, ``get()`` and ``d[key]`` while leaving it
+visible to iteration, and ``-2`` ended every traversal early, hiding each key
+that came after it. If you are upgrading and were storing either, the values
+were not being read back correctly in the first place.
 
 ### The serialization format is platform-dependent and unauthenticated
 

pycedar-0.3.1/pycedar/VERSION

@@ -0,0 +1 @@
+0.3.1