shelfdb 3.1.0__tar.gz → 3.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. {shelfdb-3.1.0 → shelfdb-3.2.0}/PKG-INFO +1 -1
  2. {shelfdb-3.1.0 → shelfdb-3.2.0}/pyproject.toml +1 -1
  3. {shelfdb-3.1.0 → shelfdb-3.2.0}/pyproject.toml.orig +1 -1
  4. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/client/client.py +4 -0
  5. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/protocol/session.py +1 -0
  6. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/shelf/db.py +4 -1
  7. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/shelf/query.py +13 -3
  8. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/shelf/storage.py +45 -6
  9. {shelfdb-3.1.0 → shelfdb-3.2.0}/LICENSE +0 -0
  10. {shelfdb-3.1.0 → shelfdb-3.2.0}/README.md +0 -0
  11. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/__init__.py +0 -0
  12. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/__main__.py +0 -0
  13. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/cli.py +0 -0
  14. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/client/__init__.py +0 -0
  15. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/protocol/__init__.py +0 -0
  16. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/protocol/demo_poc.py +0 -0
  17. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/protocol/protocol.py +0 -0
  18. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/protocol/query_result.py +0 -0
  19. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/protocol/server.py +0 -0
  20. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/protocol/write_admission.py +0 -0
  21. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/shelf/__init__.py +0 -0
  22. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/shelf/schema.py +0 -0
  23. {shelfdb-3.1.0 → shelfdb-3.2.0}/src/shelfdb/target.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: shelfdb
3
- Version: 3.1.0
3
+ Version: 3.2.0
4
4
  Summary: A tiny database for Python
5
5
  Author: Nitipit Nontasuwan
6
6
  Author-email: Nitipit Nontasuwan <nitipit@gmail.com>
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "shelfdb"
7
- version = "3.1.0"
7
+ version = "3.2.0"
8
8
  description = "A tiny database for Python"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.12,<3.15"
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "shelfdb"
7
- version = "3.1.0"
7
+ version = "3.2.0"
8
8
  description = "A tiny database for Python"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.12,<3.15"
@@ -179,6 +179,10 @@ class RemoteShelfQuery:
179
179
  def keys_range(self, start: str, stop: str | None = None) -> RemoteShelfQuery:
180
180
  return self._new("keys_range", start, stop)
181
181
 
182
+ def keys_prefix(self, prefix: str) -> RemoteShelfQuery:
183
+ """Build literal prefix selection; the server validates it at execution."""
184
+ return self._new("keys_prefix", prefix)
185
+
182
186
  def keys(self) -> RemoteShelfQuery:
183
187
  return self._new("keys")
184
188
 
@@ -155,6 +155,7 @@ class Session:
155
155
  "desc",
156
156
  "key",
157
157
  "keys_range",
158
+ "keys_prefix",
158
159
  "keys",
159
160
  "items",
160
161
  "filter",
@@ -214,4 +214,7 @@ class Transaction:
214
214
  """
215
215
 
216
216
  shelf = self._lmdb_env.open_db(name.encode(), txn=self.tx)
217
- return ShelfQuery(ShelfCursor(self.tx, shelf), ShelfStore(self.tx, shelf))
217
+ return ShelfQuery(
218
+ ShelfCursor(self.tx, shelf, max_key_size=self._lmdb_env.max_key_size()),
219
+ ShelfStore(self.tx, shelf),
220
+ )
@@ -2,8 +2,8 @@
2
2
 
3
3
  `ShelfQuery` combines two layers cleanly:
4
4
 
5
- - selector methods (`key()`, `keys_range()`, `asc()`, `desc()`) copy the wrapped
6
- cursor scan state
5
+ - selector methods (`key()`, `keys_range()`, `keys_prefix()`, `asc()`, `desc()`)
6
+ copy the wrapped cursor scan state
7
7
  - transform methods (`keys()`, `items()`, `filter()`, `slice()`, `sort()`) wrap
8
8
  the selected stream without mutating cursor state
9
9
  - read/write helpers delegate to the internal store helper
@@ -80,7 +80,7 @@ class ShelfQuery:
80
80
  def _load_items(self, items: Iterator[Item]) -> Iterator[Item]:
81
81
  for item in items:
82
82
  if item.value is UNDEF:
83
- if (value := self._store.get(item.key)) is not None:
83
+ if (value := self._store.get(item.key, UNDEF)) is not UNDEF:
84
84
  yield Item(item.key, value)
85
85
  else:
86
86
  yield item
@@ -101,6 +101,16 @@ class ShelfQuery:
101
101
  """Return the query narrowed to keys in ``[start, stop)``."""
102
102
  return self._new(cursor=self._cursor.select_keys_range(start, stop))
103
103
 
104
+ def keys_prefix(self, prefix: str) -> ShelfQuery:
105
+ """Select keys starting with ``prefix``, replacing the previous selector.
106
+
107
+ Matching is literal and case-sensitive. Empty prefix selects all keys;
108
+ a prefix exceeding the environment's key byte limit selects none.
109
+ Direction and transforms are preserved. Invalid types raise ``TypeError``;
110
+ unpaired Unicode surrogates raise ``UnicodeEncodeError``.
111
+ """
112
+ return self._new(cursor=self._cursor.select_keys_prefix(prefix))
113
+
104
114
  def keys(self) -> ShelfQuery:
105
115
  """Project the current query to key-only items."""
106
116
 
@@ -23,6 +23,14 @@ LmdbTransaction = Any
23
23
  LmdbCursor = Any
24
24
 
25
25
 
26
+ def _prefix_upper_bound(prefix: bytes) -> bytes | None:
27
+ """Return the exclusive bytewise bound, without requiring valid UTF-8."""
28
+ for index in range(len(prefix) - 1, -1, -1):
29
+ if prefix[index] < 0xFF:
30
+ return prefix[:index] + bytes([prefix[index] + 1])
31
+ return None
32
+
33
+
26
34
  def packb(value: Any) -> bytes:
27
35
  """Serialize a Python object to MessagePack bytes."""
28
36
  return msgpack.packb(value, use_bin_type=True)
@@ -44,7 +52,7 @@ class ShelfCursor:
44
52
  """Internal copied scan state plus cursor-backed iteration.
45
53
 
46
54
  A `ShelfCursor` instance captures one LMDB named database together with one
47
- scan configuration (`exact_key`, range bounds, and direction). Selector
55
+ scan configuration (exact key, range or prefix, and direction). Selector
48
56
  methods do not mutate in place; they return copied `ShelfCursor` instances
49
57
  with updated scan state. Iteration always opens a fresh cursor and replays
50
58
  the configured scan.
@@ -55,15 +63,19 @@ class ShelfCursor:
55
63
  tx: LmdbTransaction,
56
64
  db: Any,
57
65
  *,
66
+ max_key_size: int,
58
67
  exact_key: str | None = None,
59
68
  start: str | None = None,
60
69
  stop: str | None = None,
70
+ prefix: bytes | None = None,
61
71
  descending: bool = False,
62
72
  ):
63
73
  self._handle = _ShelfHandle(tx, db)
74
+ self._max_key_size = max_key_size
64
75
  self._exact_key = exact_key
65
76
  self._start = start
66
77
  self._stop = stop
78
+ self._prefix = prefix
67
79
  self._descending = descending
68
80
 
69
81
  def _copy(
@@ -72,13 +84,16 @@ class ShelfCursor:
72
84
  exact_key: str | None | object = _KEEP,
73
85
  start: str | None | object = _KEEP,
74
86
  stop: str | None | object = _KEEP,
87
+ prefix: bytes | None | object = _KEEP,
75
88
  descending: bool | object = _KEEP,
76
89
  ) -> ShelfCursor:
77
90
  shelf = object.__new__(ShelfCursor)
78
91
  shelf._handle = self._handle
92
+ shelf._max_key_size = self._max_key_size
79
93
  shelf._exact_key = self._exact_key if exact_key is _KEEP else exact_key
80
94
  shelf._start = self._start if start is _KEEP else start
81
95
  shelf._stop = self._stop if stop is _KEEP else stop
96
+ shelf._prefix = self._prefix if prefix is _KEEP else cast(bytes | None, prefix)
82
97
  shelf._descending = (
83
98
  self._descending if descending is _KEEP else cast(bool, descending)
84
99
  )
@@ -94,11 +109,17 @@ class ShelfCursor:
94
109
 
95
110
  def select_key(self, key: str) -> ShelfCursor:
96
111
  """Return a copied shelf scan narrowed to one key."""
97
- return self._copy(exact_key=key, start=None, stop=None)
112
+ return self._copy(exact_key=key, start=None, stop=None, prefix=None)
98
113
 
99
114
  def select_keys_range(self, start: str, stop: str | None = None) -> ShelfCursor:
100
115
  """Return a copied shelf scan narrowed to ``[start, stop)``."""
101
- return self._copy(exact_key=None, start=start, stop=stop)
116
+ return self._copy(exact_key=None, start=start, stop=stop, prefix=None)
117
+
118
+ def select_keys_prefix(self, prefix: str) -> ShelfCursor:
119
+ """Replace the selection with literal UTF-8 prefix matching."""
120
+ if not isinstance(prefix, str):
121
+ raise TypeError("prefix must be a str")
122
+ return self._copy(exact_key=None, start=None, stop=None, prefix=prefix.encode())
102
123
 
103
124
  def _cursor(self) -> LmdbCursor:
104
125
  """Create an LMDB cursor for this shelf."""
@@ -106,6 +127,18 @@ class ShelfCursor:
106
127
 
107
128
  def _position_cursor(self, cur: LmdbCursor) -> bool:
108
129
  """Position ``cur`` at the first key for the current scan."""
130
+ if self._prefix is not None:
131
+ if len(self._prefix) > self._max_key_size:
132
+ return False
133
+ if not self._prefix:
134
+ return cur.last() if self._descending else cur.first()
135
+ if not self._descending:
136
+ return cur.set_range(self._prefix)
137
+ stop = _prefix_upper_bound(self._prefix)
138
+ if stop is None or not cur.set_range(stop):
139
+ return cur.last()
140
+ return cur.prev()
141
+
109
142
  if self._exact_key is not None:
110
143
  return cur.set_key(self._exact_key.encode())
111
144
 
@@ -126,6 +159,8 @@ class ShelfCursor:
126
159
 
127
160
  def _key_in_bounds(self, key: bytes) -> bool:
128
161
  """Return ``True`` when ``key`` still belongs to the current scan."""
162
+ if self._prefix is not None:
163
+ return key.startswith(self._prefix)
129
164
  if self._exact_key is not None:
130
165
  return key == self._exact_key.encode()
131
166
  if self._descending:
@@ -166,11 +201,15 @@ class ShelfStore:
166
201
  ):
167
202
  self._handle = _ShelfHandle(tx, db)
168
203
 
169
- def get(self, key: str) -> Any | None:
170
- """Return the unpacked value for ``key`` when present."""
204
+ def get(self, key: str, default: Any = None) -> Any:
205
+ """Return the unpacked value, or ``default`` only when the key is absent.
206
+
207
+ A stored MessagePack null is a present value and always returns ``None``.
208
+ Callers needing to distinguish it from absence can supply a sentinel.
209
+ """
171
210
  value = self._handle.tx.get(key.encode(), db=self._handle.db)
172
211
  if value is None:
173
- return None
212
+ return default
174
213
  return unpackb(value)
175
214
 
176
215
  def put(self, key: str, value: Any) -> MutationResult:
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes