nfs-db 1.0.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.
nfs_db-1.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Carson O'Ffill
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,2 @@
1
+ include LICENSE
2
+ include requirements.txt
nfs_db-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,82 @@
1
+ Metadata-Version: 2.4
2
+ Name: nfs-db
3
+ Version: 1.0.0
4
+ Summary: A database-like interface for your NFS
5
+ Home-page: https://github.com/karzunn/nfs-db
6
+ Author: Carson O'Ffill
7
+ Author-email: offillcarson@gmail.com
8
+ License: MIT
9
+ Classifier: Programming Language :: Python :: 3.9
10
+ Classifier: Programming Language :: Python :: 3.10
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Classifier: Operating System :: OS Independent
15
+ Requires-Python: >=3.9
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Dynamic: author
19
+ Dynamic: author-email
20
+ Dynamic: classifier
21
+ Dynamic: description
22
+ Dynamic: description-content-type
23
+ Dynamic: home-page
24
+ Dynamic: license
25
+ Dynamic: license-file
26
+ Dynamic: requires-python
27
+ Dynamic: summary
28
+
29
+ ![Logo](logo.png)
30
+
31
+ # nfs-db
32
+
33
+ nfs-db is *not* a database engine. It is a lightweight Python interface that lets you interact with an existing NFS server through familiar database-style operations.
34
+
35
+ ### Why nfs-db?
36
+
37
+ For small projects already utilizing a NFS server, using nfs-db avoids the infrastructure complexity and operational requirements that traditional databases bring.
38
+
39
+ ### What to expect
40
+
41
+ nfs-db is not intended to compete with traditional database engines. Filesystem operations introduce overhead, and performance will not be comparable to purpose-built database systems.
42
+
43
+ nfs-db is best suited for:
44
+
45
+ - Small applications and utilities.
46
+ - Shared application state across multiple machines.
47
+ - Data processing pipelines operating on shared NFS storage.
48
+ - Workloads where atomic operations matter more than raw throughput.
49
+
50
+ It is not intended for large datasets, high-throughput workloads, or applications requiring the advanced capabilities of a traditional database.
51
+
52
+ ## Quickstart
53
+
54
+ Create a users table:
55
+
56
+ ```python
57
+ from nfs_db import database, table_spec
58
+
59
+ db = database("/mnt/nfs")
60
+ spec = table_spec("users", name=str, number=int, is_active=bool)
61
+ users = db.table(spec)
62
+ ```
63
+
64
+ Insert, retrieve, update, query, and delete rows:
65
+
66
+ ```python
67
+ row_id = users.insert({
68
+ "name": "John",
69
+ "number": 7,
70
+ "is_active": True,
71
+ })
72
+
73
+ row = users.get(row_id)
74
+ active_users = users.get_where("is_active", True)
75
+
76
+ users.update(row_id, lambda row: {**row, "number": row["number"] + 1})
77
+ users.delete(row_id)
78
+ ```
79
+
80
+ The update callback must return a row dictionary with the table's existing
81
+ fields, and it must not change `id`. If another update wins a race, the callback
82
+ may run again against the latest row, so avoid external side effects in it.
nfs_db-1.0.0/README.md ADDED
@@ -0,0 +1,54 @@
1
+ ![Logo](logo.png)
2
+
3
+ # nfs-db
4
+
5
+ nfs-db is *not* a database engine. It is a lightweight Python interface that lets you interact with an existing NFS server through familiar database-style operations.
6
+
7
+ ### Why nfs-db?
8
+
9
+ For small projects already utilizing a NFS server, using nfs-db avoids the infrastructure complexity and operational requirements that traditional databases bring.
10
+
11
+ ### What to expect
12
+
13
+ nfs-db is not intended to compete with traditional database engines. Filesystem operations introduce overhead, and performance will not be comparable to purpose-built database systems.
14
+
15
+ nfs-db is best suited for:
16
+
17
+ - Small applications and utilities.
18
+ - Shared application state across multiple machines.
19
+ - Data processing pipelines operating on shared NFS storage.
20
+ - Workloads where atomic operations matter more than raw throughput.
21
+
22
+ It is not intended for large datasets, high-throughput workloads, or applications requiring the advanced capabilities of a traditional database.
23
+
24
+ ## Quickstart
25
+
26
+ Create a users table:
27
+
28
+ ```python
29
+ from nfs_db import database, table_spec
30
+
31
+ db = database("/mnt/nfs")
32
+ spec = table_spec("users", name=str, number=int, is_active=bool)
33
+ users = db.table(spec)
34
+ ```
35
+
36
+ Insert, retrieve, update, query, and delete rows:
37
+
38
+ ```python
39
+ row_id = users.insert({
40
+ "name": "John",
41
+ "number": 7,
42
+ "is_active": True,
43
+ })
44
+
45
+ row = users.get(row_id)
46
+ active_users = users.get_where("is_active", True)
47
+
48
+ users.update(row_id, lambda row: {**row, "number": row["number"] + 1})
49
+ users.delete(row_id)
50
+ ```
51
+
52
+ The update callback must return a row dictionary with the table's existing
53
+ fields, and it must not change `id`. If another update wins a race, the callback
54
+ may run again against the latest row, so avoid external side effects in it.
@@ -0,0 +1,3 @@
1
+ from ._version import __version__
2
+ from .database import database
3
+ from .table.table_spec import table_spec
@@ -0,0 +1 @@
1
+ __version__ = "1.0.0"
@@ -0,0 +1,7 @@
1
+ NFS_DB_PATH = "nfs-db"
2
+ STAGING_PATH = "staging"
3
+ INDEXES_PATH = "indexes"
4
+ ROWS_PATH = "rows"
5
+ ID_COLUMN_NAME = "id"
6
+ CURRENT_TRANSACTION_EXTENSION = ".current_transaction"
7
+ FIELDS_PATH = "fields"
@@ -0,0 +1,15 @@
1
+ from pathlib import Path
2
+
3
+ from .constants import NFS_DB_PATH
4
+ from .table.table import table
5
+ from .table.table_spec import table_spec
6
+
7
+
8
+ class database:
9
+
10
+ def __init__(self, path: str):
11
+ self.path = Path(path) / Path(NFS_DB_PATH)
12
+ self.path.mkdir(parents=True, exist_ok=True)
13
+
14
+ def table(self, table_spec: table_spec):
15
+ return table(self.path, table_spec)
File without changes
@@ -0,0 +1,176 @@
1
+ from collections.abc import Callable
2
+ from uuid import uuid4
3
+ from pathlib import Path
4
+
5
+ from ..constants import (
6
+ STAGING_PATH,
7
+ INDEXES_PATH,
8
+ ROWS_PATH,
9
+ ID_COLUMN_NAME,
10
+ CURRENT_TRANSACTION_EXTENSION,
11
+ FIELDS_PATH
12
+ )
13
+ from .table_spec import table_spec
14
+ from .transactions import insert_transaction, update_transaction, delete_transaction
15
+ from ..utils import exec
16
+
17
+
18
+ class table:
19
+
20
+ def __init__(self, db_path: Path, table_spec: table_spec):
21
+ self.spec = table_spec
22
+ self.path = db_path / table_spec.identifier
23
+
24
+ self.staging_path = self.path / STAGING_PATH
25
+ self.staging_path.mkdir(parents=True, exist_ok=True)
26
+
27
+ self.indexes_path = self.path / INDEXES_PATH
28
+ self.indexes_path.mkdir(parents=True, exist_ok=True)
29
+
30
+ self.rows_path = self.path / ROWS_PATH
31
+ self.rows_path.mkdir(parents=True, exist_ok=True)
32
+
33
+
34
+ def _validate(self, data: dict):
35
+ if ID_COLUMN_NAME not in data:
36
+ data[ID_COLUMN_NAME] = str(uuid4())
37
+
38
+ for col in self.spec.columns.values():
39
+ if col.name not in data:
40
+ raise ValueError(f"Missing value for column '{col.name}'")
41
+ if type(data[col.name]) is not col.data_type:
42
+ raise TypeError(
43
+ f"Incorrect type for column '{col.name}'. "
44
+ f"Expected {col.data_type.__name__}, got {type(data[col.name]).__name__}"
45
+ )
46
+
47
+
48
+ def insert(self, data: dict) -> str:
49
+ self._validate(data)
50
+ insert_trans = insert_transaction(self.path, data)
51
+ try:
52
+ insert_trans.stage()
53
+ insert_trans.execute()
54
+ return data[ID_COLUMN_NAME]
55
+ except FileExistsError:
56
+ raise FileExistsError(
57
+ f"Row with ID {data[ID_COLUMN_NAME]} already exists in table {self.spec.name}"
58
+ ) from None
59
+ finally:
60
+ insert_trans.cleanup()
61
+
62
+
63
+ def update(self, row_id: str, edit: Callable[[dict], dict]) -> dict:
64
+ if not callable(edit):
65
+ raise TypeError("edit must be a callable that accepts and returns a row")
66
+
67
+ while True:
68
+ existing_transaction_id, row = self._get_row_snapshot(row_id)
69
+ updated_row = edit(row.copy())
70
+ if not isinstance(updated_row, dict):
71
+ raise TypeError("edit must return a row dictionary")
72
+ if updated_row.get(ID_COLUMN_NAME) != row_id:
73
+ raise ValueError(f"Row ID '{ID_COLUMN_NAME}' cannot be modified")
74
+ if set(updated_row) != set(self.spec.columns):
75
+ raise ValueError("Updated row must contain exactly the table's columns")
76
+ self._validate(updated_row)
77
+
78
+ update_trans = update_transaction(
79
+ self.path,
80
+ row_id,
81
+ existing_transaction_id,
82
+ updated_row,
83
+ )
84
+ try:
85
+ update_trans.stage()
86
+ try:
87
+ update_trans.execute()
88
+ except FileNotFoundError:
89
+ continue
90
+ finally:
91
+ update_trans.cleanup()
92
+
93
+ return updated_row
94
+
95
+
96
+ def delete(self, row_id: str):
97
+ delete_trans = delete_transaction(self.path, row_id)
98
+ try:
99
+ delete_trans.execute()
100
+ except FileNotFoundError:
101
+ raise KeyError(
102
+ f"Row with ID {row_id} does not exist in table {self.spec.name}"
103
+ ) from None
104
+ finally:
105
+ delete_trans.cleanup()
106
+
107
+
108
+ def _convert_value(self, column_name: str, value: str):
109
+ column = self.spec.columns[column_name]
110
+ if column.data_type is bool:
111
+ return value.lower() == "true"
112
+ return column.data_type(value)
113
+
114
+
115
+ def get(self, row_id: str) -> dict:
116
+ _, row = self._get_row_snapshot(row_id)
117
+ return row
118
+
119
+
120
+ def _get_row_snapshot(self, row_id: str) -> tuple[str, dict]:
121
+ row_path = self.rows_path / row_id
122
+ lines, _, _ = exec("find", row_path)
123
+ paths = lines.splitlines()
124
+
125
+ if not paths:
126
+ raise KeyError(f"Row with ID '{row_id}' does not exist")
127
+
128
+ data = {}
129
+ current_transaction_id = None
130
+ for path in paths:
131
+ if path.endswith(CURRENT_TRANSACTION_EXTENSION):
132
+ current_transaction_id = Path(path).name.replace(CURRENT_TRANSACTION_EXTENSION, "")
133
+ break
134
+ if current_transaction_id is None:
135
+ raise RuntimeError(
136
+ f"Row with ID '{row_id}' is missing a current transaction marker."
137
+ )
138
+
139
+ for path in paths:
140
+ relative_path = Path(path).relative_to(row_path)
141
+ parts = relative_path.parts
142
+ if len(parts) == 4 and parts[0] == current_transaction_id:
143
+ _, _, column_name, column_value = parts
144
+ data[column_name] = self._convert_value(column_name, column_value)
145
+
146
+ return current_transaction_id, data
147
+
148
+ def get_where(self, column_name: str, value) -> list[dict]:
149
+ if column_name not in self.spec.columns:
150
+ raise ValueError(
151
+ f"Column '{column_name}' does not exist in table '{self.spec.name}'"
152
+ )
153
+
154
+ index_path = self.indexes_path / column_name / str(value)
155
+ lines, _, _ = exec("find", "-L", str(index_path))
156
+ matching_transactions = set()
157
+ rows = {}
158
+ for path in lines.splitlines():
159
+ relative_path = Path(path).relative_to(index_path)
160
+ parts = relative_path.parts
161
+ if (
162
+ len(parts) == 2
163
+ and parts[1].endswith(CURRENT_TRANSACTION_EXTENSION)
164
+ and parts[0] == parts[1][:-len(CURRENT_TRANSACTION_EXTENSION)]
165
+ ):
166
+ matching_transactions.add(parts[0])
167
+ elif len(parts) == 5 and parts[1] == parts[0] and parts[2] == FIELDS_PATH:
168
+ index_transaction_id, _, _, field_name, field_value = parts
169
+ rows.setdefault(index_transaction_id, {})[field_name] = self._convert_value(
170
+ field_name, field_value
171
+ )
172
+ return [
173
+ row
174
+ for index_transaction_id, row in rows.items()
175
+ if index_transaction_id in matching_transactions
176
+ ]
@@ -0,0 +1,54 @@
1
+ import hashlib
2
+ import json
3
+
4
+ from ..constants import ID_COLUMN_NAME
5
+
6
+
7
+ _COLUMN_TYPE_NAMES = {
8
+ int: "INTEGER",
9
+ str: "STRING",
10
+ float: "FLOAT",
11
+ bool: "BOOLEAN",
12
+ }
13
+
14
+
15
+ class column:
16
+
17
+ def __init__(
18
+ self,
19
+ name: str,
20
+ data_type: type,
21
+ ):
22
+ self.name = name
23
+ self.data_type = data_type
24
+
25
+
26
+ class table_spec:
27
+
28
+ def __init__(self, name: str, /, **columns: type):
29
+ self.name = name
30
+ self.columns = {}
31
+ self.columns[ID_COLUMN_NAME] = column(ID_COLUMN_NAME, str)
32
+
33
+ for column_name, data_type in columns.items():
34
+ if column_name in self.columns:
35
+ raise ValueError(
36
+ f"Column '{column_name}' already exists in table '{self.name}'"
37
+ )
38
+ if data_type not in _COLUMN_TYPE_NAMES:
39
+ raise TypeError("Column type must be int, str, float, or bool")
40
+ self.columns[column_name] = column(column_name, data_type)
41
+
42
+ @property
43
+ def identifier(self):
44
+ definition = {
45
+ "name": self.name,
46
+ "columns": [
47
+ (col.name, _COLUMN_TYPE_NAMES[col.data_type])
48
+ for col in self.columns.values()
49
+ ],
50
+ }
51
+ serialized = json.dumps(
52
+ definition, ensure_ascii=False, separators=(",", ":")
53
+ ).encode("utf-8")
54
+ return hashlib.sha256(serialized).hexdigest()
@@ -0,0 +1,221 @@
1
+ from uuid import uuid4
2
+ from pathlib import Path
3
+ import errno
4
+ import os
5
+ from abc import ABC, abstractmethod
6
+ import shutil
7
+ from nfs_db.constants import (
8
+ CURRENT_TRANSACTION_EXTENSION,
9
+ STAGING_PATH,
10
+ INDEXES_PATH,
11
+ ROWS_PATH,
12
+ FIELDS_PATH,
13
+ ID_COLUMN_NAME,
14
+ )
15
+
16
+
17
+ def _delete_index(index_path: Path):
18
+ index_path.unlink(missing_ok=True)
19
+ try:
20
+ index_path.parent.rmdir()
21
+ except OSError as error:
22
+ if error.errno not in (errno.ENOENT, errno.ENOTEMPTY, errno.EEXIST):
23
+ raise
24
+
25
+
26
+ class transaction(ABC):
27
+
28
+ @abstractmethod
29
+ def stage(self): ...
30
+
31
+ @abstractmethod
32
+ def execute(self): ...
33
+
34
+ @abstractmethod
35
+ def cleanup(self): ...
36
+
37
+
38
+ class insert_transaction(transaction):
39
+
40
+ def __init__(self, table_path: Path, data: dict):
41
+ self.id = str(uuid4())
42
+ self.data = data
43
+ self.row_id = data[ID_COLUMN_NAME]
44
+ self.table_path = table_path
45
+ self.staging_path = self.table_path / STAGING_PATH
46
+ self.indexes_path = self.table_path / INDEXES_PATH
47
+ self.rows_path = self.table_path / ROWS_PATH
48
+ self.staging_row_path = self.staging_path / self.id / self.row_id
49
+ self.future_row_path = self.rows_path / self.row_id
50
+ self.executed = False
51
+
52
+ def _create_indexes(self):
53
+ for name, value in self.data.items():
54
+ symlink_path = (self.indexes_path / name / str(value) / self.id)
55
+ symlink_path.parent.mkdir(parents=True, exist_ok=True)
56
+ symlink_path.symlink_to(self.future_row_path, target_is_directory=True)
57
+
58
+ def _delete_indexes(self):
59
+ for name, value in self.data.items():
60
+ _delete_index(self.indexes_path / name / str(value) / self.id)
61
+
62
+ def _create_current_transaction_marker(self):
63
+ (self.staging_row_path / (self.id + CURRENT_TRANSACTION_EXTENSION)).touch(exist_ok=True)
64
+
65
+ def _create_transaction_contents(self):
66
+ fields_path = self.staging_row_path / self.id / FIELDS_PATH
67
+ for name, value in self.data.items():
68
+ (fields_path / name / str(value)).mkdir(parents=True, exist_ok=True)
69
+
70
+ def stage(self):
71
+ self._create_transaction_contents()
72
+ self._create_current_transaction_marker()
73
+ self._create_indexes()
74
+
75
+ def execute(self):
76
+ self.executed = False
77
+ try:
78
+ os.rename(self.staging_row_path, self.future_row_path)
79
+ self.executed = True
80
+ except OSError as error:
81
+ if error.errno in (errno.EEXIST, errno.ENOTEMPTY):
82
+ raise FileExistsError() from None
83
+ raise
84
+
85
+ def cleanup(self):
86
+ if not self.executed:
87
+ self._delete_indexes()
88
+ shutil.rmtree(self.staging_row_path, ignore_errors=True)
89
+ self.staging_row_path.parent.rmdir()
90
+
91
+
92
+ class update_transaction(transaction):
93
+
94
+ def __init__(
95
+ self,
96
+ table_path: Path,
97
+ row_id: str,
98
+ existing_transaction_id: str,
99
+ data: dict,
100
+ ):
101
+ self.id = str(uuid4())
102
+ self.data = data
103
+ self.row_id = row_id
104
+ self.existing_transaction_id = existing_transaction_id
105
+ self.table_path = table_path
106
+ self.indexes_path = self.table_path / INDEXES_PATH
107
+ self.rows_path = self.table_path / ROWS_PATH
108
+ self.row_path = self.rows_path / self.row_id
109
+ self.transaction_path = self.row_path / self.id
110
+ self.executed = False
111
+
112
+ def _create_transaction_contents(self):
113
+ fields_path = self.transaction_path / FIELDS_PATH
114
+ for name, value in self.data.items():
115
+ (fields_path / name / str(value)).mkdir(parents=True, exist_ok=True)
116
+
117
+ def _delete_transaction_contents(self):
118
+ shutil.rmtree(self.transaction_path, ignore_errors=True)
119
+
120
+ def _create_new_indexes(self):
121
+ for name, value in self.data.items():
122
+ symlink_path = (self.indexes_path / name / str(value) / self.id)
123
+ symlink_path.parent.mkdir(parents=True, exist_ok=True)
124
+ symlink_path.symlink_to(self.row_path, target_is_directory=True)
125
+
126
+ def _delete_new_indexes(self):
127
+ for name, value in self.data.items():
128
+ _delete_index(self.indexes_path / name / str(value) / self.id)
129
+
130
+ def _delete_previous_indexes(self):
131
+ fields_path = (
132
+ self.row_path / self.existing_transaction_id / FIELDS_PATH
133
+ )
134
+ if not fields_path.is_dir():
135
+ return
136
+
137
+ for column_path in fields_path.iterdir():
138
+ for value_path in column_path.iterdir():
139
+ _delete_index(
140
+ self.indexes_path
141
+ / column_path.name
142
+ / value_path.name
143
+ / self.existing_transaction_id
144
+ )
145
+
146
+ def stage(self):
147
+ self._create_transaction_contents()
148
+ self._create_new_indexes()
149
+
150
+ def execute(self):
151
+ existing_transaction_marker = (
152
+ self.row_path
153
+ / f"{self.existing_transaction_id}{CURRENT_TRANSACTION_EXTENSION}"
154
+ )
155
+ new_transaction_marker = (
156
+ self.row_path / f"{self.id}{CURRENT_TRANSACTION_EXTENSION}"
157
+ )
158
+ os.rename(existing_transaction_marker, new_transaction_marker)
159
+ self.executed = True
160
+
161
+ def cleanup(self):
162
+ if self.executed:
163
+ self._delete_previous_indexes()
164
+ shutil.rmtree(
165
+ self.row_path / self.existing_transaction_id,
166
+ ignore_errors=True,
167
+ )
168
+ else:
169
+ self._delete_new_indexes()
170
+ self._delete_transaction_contents()
171
+
172
+
173
+ class delete_transaction(transaction):
174
+
175
+ def __init__(self, table_path: Path, row_id: str):
176
+ self.id = str(uuid4())
177
+ self.row_id = row_id
178
+ self.table_path = table_path
179
+ self.staging_path = self.table_path / STAGING_PATH
180
+ self.indexes_path = self.table_path / INDEXES_PATH
181
+ self.rows_path = self.table_path / ROWS_PATH
182
+ self.row_path = self.rows_path / self.row_id
183
+ self.deleted_path = self.staging_path / self.id
184
+ self.executed = False
185
+
186
+ def stage(self): ...
187
+
188
+ def execute(self):
189
+ try:
190
+ os.rename(self.row_path, self.deleted_path)
191
+ self.executed = True
192
+ except OSError as error:
193
+ if error.errno in (errno.ENOENT, errno.ENOTEMPTY):
194
+ raise FileNotFoundError() from None
195
+ raise
196
+
197
+ def _delete_indexes(self):
198
+ current_marker = next(
199
+ self.deleted_path.glob(f"*{CURRENT_TRANSACTION_EXTENSION}"),
200
+ None,
201
+ )
202
+ if current_marker is None:
203
+ raise FileNotFoundError(f"Row with ID {self.row_id} does not exist")
204
+ current_transaction = current_marker.name.removesuffix(CURRENT_TRANSACTION_EXTENSION)
205
+ fields_path = self.deleted_path / current_transaction / FIELDS_PATH
206
+ if not fields_path.is_dir():
207
+ raise FileNotFoundError(f"Fields for row with ID {self.row_id} do not exist")
208
+ for column_path in fields_path.iterdir():
209
+ for value_path in column_path.iterdir():
210
+ _delete_index(
211
+ self.indexes_path
212
+ / column_path.name
213
+ / value_path.name
214
+ / current_transaction
215
+ )
216
+
217
+ def cleanup(self):
218
+ if not self.executed:
219
+ return
220
+ self._delete_indexes()
221
+ shutil.rmtree(self.deleted_path, ignore_errors=True)
@@ -0,0 +1,14 @@
1
+ import subprocess
2
+
3
+ def exec(
4
+ command: str,
5
+ *args: str,
6
+ ) -> tuple[str, str, int]:
7
+ """Executes a shell command and returns the output and error messages."""
8
+ process = subprocess.Popen(
9
+ [command, *args],
10
+ stdout=subprocess.PIPE,
11
+ stderr=subprocess.PIPE,
12
+ )
13
+ stdout, stderr = process.communicate()
14
+ return stdout.decode("utf-8"), stderr.decode("utf-8"), process.returncode
@@ -0,0 +1,82 @@
1
+ Metadata-Version: 2.4
2
+ Name: nfs-db
3
+ Version: 1.0.0
4
+ Summary: A database-like interface for your NFS
5
+ Home-page: https://github.com/karzunn/nfs-db
6
+ Author: Carson O'Ffill
7
+ Author-email: offillcarson@gmail.com
8
+ License: MIT
9
+ Classifier: Programming Language :: Python :: 3.9
10
+ Classifier: Programming Language :: Python :: 3.10
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Classifier: Operating System :: OS Independent
15
+ Requires-Python: >=3.9
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Dynamic: author
19
+ Dynamic: author-email
20
+ Dynamic: classifier
21
+ Dynamic: description
22
+ Dynamic: description-content-type
23
+ Dynamic: home-page
24
+ Dynamic: license
25
+ Dynamic: license-file
26
+ Dynamic: requires-python
27
+ Dynamic: summary
28
+
29
+ ![Logo](logo.png)
30
+
31
+ # nfs-db
32
+
33
+ nfs-db is *not* a database engine. It is a lightweight Python interface that lets you interact with an existing NFS server through familiar database-style operations.
34
+
35
+ ### Why nfs-db?
36
+
37
+ For small projects already utilizing a NFS server, using nfs-db avoids the infrastructure complexity and operational requirements that traditional databases bring.
38
+
39
+ ### What to expect
40
+
41
+ nfs-db is not intended to compete with traditional database engines. Filesystem operations introduce overhead, and performance will not be comparable to purpose-built database systems.
42
+
43
+ nfs-db is best suited for:
44
+
45
+ - Small applications and utilities.
46
+ - Shared application state across multiple machines.
47
+ - Data processing pipelines operating on shared NFS storage.
48
+ - Workloads where atomic operations matter more than raw throughput.
49
+
50
+ It is not intended for large datasets, high-throughput workloads, or applications requiring the advanced capabilities of a traditional database.
51
+
52
+ ## Quickstart
53
+
54
+ Create a users table:
55
+
56
+ ```python
57
+ from nfs_db import database, table_spec
58
+
59
+ db = database("/mnt/nfs")
60
+ spec = table_spec("users", name=str, number=int, is_active=bool)
61
+ users = db.table(spec)
62
+ ```
63
+
64
+ Insert, retrieve, update, query, and delete rows:
65
+
66
+ ```python
67
+ row_id = users.insert({
68
+ "name": "John",
69
+ "number": 7,
70
+ "is_active": True,
71
+ })
72
+
73
+ row = users.get(row_id)
74
+ active_users = users.get_where("is_active", True)
75
+
76
+ users.update(row_id, lambda row: {**row, "number": row["number"] + 1})
77
+ users.delete(row_id)
78
+ ```
79
+
80
+ The update callback must return a row dictionary with the table's existing
81
+ fields, and it must not change `id`. If another update wins a race, the callback
82
+ may run again against the latest row, so avoid external side effects in it.
@@ -0,0 +1,25 @@
1
+ LICENSE
2
+ MANIFEST.in
3
+ README.md
4
+ requirements.txt
5
+ setup.py
6
+ nfs_db/__init__.py
7
+ nfs_db/_version.py
8
+ nfs_db/constants.py
9
+ nfs_db/database.py
10
+ nfs_db/utils.py
11
+ nfs_db.egg-info/PKG-INFO
12
+ nfs_db.egg-info/SOURCES.txt
13
+ nfs_db.egg-info/dependency_links.txt
14
+ nfs_db.egg-info/top_level.txt
15
+ nfs_db/table/__init__.py
16
+ nfs_db/table/table.py
17
+ nfs_db/table/table_spec.py
18
+ nfs_db/table/transactions.py
19
+ tests/test_delete.py
20
+ tests/test_get.py
21
+ tests/test_get_where.py
22
+ tests/test_insert.py
23
+ tests/test_table_spec.py
24
+ tests/test_transactions.py
25
+ tests/test_update.py
@@ -0,0 +1 @@
1
+ nfs_db
File without changes
nfs_db-1.0.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
nfs_db-1.0.0/setup.py ADDED
@@ -0,0 +1,32 @@
1
+ from setuptools import setup, find_packages
2
+ from runpy import run_path
3
+
4
+ with open("README.md", "r", encoding="utf-8") as fh:
5
+ long_description = fh.read()
6
+ with open("requirements.txt", "r", encoding="utf-8") as fh:
7
+ requirements = fh.read().splitlines()
8
+
9
+ version = run_path("nfs_db/_version.py")["__version__"]
10
+
11
+ setup(
12
+ name = 'nfs-db',
13
+ version = version,
14
+ author = "Carson O'Ffill",
15
+ author_email = 'offillcarson@gmail.com',
16
+ license = 'MIT',
17
+ description = 'A database-like interface for your NFS',
18
+ long_description = long_description,
19
+ long_description_content_type = "text/markdown",
20
+ url = 'https://github.com/karzunn/nfs-db',
21
+ packages = find_packages(exclude=("tests", "tests.*")),
22
+ install_requires = requirements,
23
+ python_requires='>=3.9',
24
+ classifiers=[
25
+ "Programming Language :: Python :: 3.9",
26
+ "Programming Language :: Python :: 3.10",
27
+ "Programming Language :: Python :: 3.11",
28
+ "Programming Language :: Python :: 3.12",
29
+ "Programming Language :: Python :: 3.13",
30
+ "Operating System :: OS Independent",
31
+ ]
32
+ )
@@ -0,0 +1,19 @@
1
+ from tests.base_test_case import DatabaseTestCase
2
+
3
+
4
+ class TableDeleteTests(DatabaseTestCase):
5
+ def test_delete_rejects_a_missing_row(self):
6
+ with self.assertRaisesRegex(KeyError, "does not exist"):
7
+ self.table.delete("missing")
8
+
9
+ self.assertEqual(list(self.table.staging_path.iterdir()), [])
10
+
11
+ def test_delete_removes_row_indexes_and_staging_files(self):
12
+ row_id = self.insert_row()
13
+
14
+ self.table.delete(row_id)
15
+
16
+ self.assertFalse((self.table.rows_path / row_id).exists())
17
+ self.assertFalse((self.table.indexes_path / "name" / "Ada").exists())
18
+ self.assertFalse((self.table.indexes_path / "number" / "7").exists())
19
+ self.assertEqual(list(self.table.staging_path.iterdir()), [])
@@ -0,0 +1,24 @@
1
+ from pathlib import Path
2
+
3
+ from tests.base_test_case import DatabaseTestCase
4
+
5
+
6
+ class TableGetTests(DatabaseTestCase):
7
+ def test_get_returns_all_fields_with_expected_types(self):
8
+ row_id = self.insert_row(name="Ada", number=7, active=True)
9
+
10
+ self.assertEqual(
11
+ self.table.get(row_id),
12
+ {"id": row_id, "name": "Ada", "number": 7, "active": True},
13
+ )
14
+
15
+ def test_get_rejects_a_missing_row(self):
16
+ with self.assertRaisesRegex(KeyError, "does not exist"):
17
+ self.table.get("missing")
18
+
19
+ def test_get_rejects_a_row_without_a_current_marker(self):
20
+ row_path = self.table.rows_path / "corrupt"
21
+ row_path.mkdir()
22
+
23
+ with self.assertRaisesRegex(RuntimeError, "missing a current transaction marker"):
24
+ self.table.get("corrupt")
@@ -0,0 +1,34 @@
1
+ from tests.base_test_case import DatabaseTestCase
2
+
3
+
4
+ class TableGetWhereTests(DatabaseTestCase):
5
+ def test_get_where_returns_every_matching_row(self):
6
+ first_id = self.insert_row(name="Ada", row_id="first")
7
+ second_id = self.insert_row(name="Ada", row_id="second")
8
+ self.insert_row(name="Grace", row_id="third")
9
+
10
+ matches = self.table.get_where("name", "Ada")
11
+
12
+ self.assertEqual(
13
+ {row["id"] for row in matches},
14
+ {first_id, second_id},
15
+ )
16
+ self.assertTrue(all(row["name"] == "Ada" for row in matches))
17
+
18
+ def test_get_where_tracks_insert_update_and_delete(self):
19
+ first_id = self.insert_row(name="same", row_id="first")
20
+ second_id = self.insert_row(name="same", row_id="second")
21
+ third_id = self.insert_row(name="other", row_id="third")
22
+
23
+ self.table.update(second_id, lambda row: {**row, "name": "other"})
24
+ inserted_id = self.insert_row(name="same", row_id="inserted")
25
+ self.table.delete(first_id)
26
+
27
+ same_rows = self.table.get_where("name", "same")
28
+ other_rows = self.table.get_where("name", "other")
29
+ self.assertEqual({row["id"] for row in same_rows}, {inserted_id})
30
+ self.assertEqual({row["id"] for row in other_rows}, {second_id, third_id})
31
+
32
+ def test_get_where_rejects_an_unknown_column(self):
33
+ with self.assertRaisesRegex(ValueError, "does not exist"):
34
+ self.table.get_where("missing", "value")
@@ -0,0 +1,51 @@
1
+ from tests.base_test_case import DatabaseTestCase
2
+
3
+
4
+ class TableInsertTests(DatabaseTestCase):
5
+ def test_insert_rejects_missing_and_invalid_values(self):
6
+ with self.assertRaisesRegex(ValueError, "Missing value for column 'active'"):
7
+ self.table.insert({"name": "Ada", "number": 7})
8
+
9
+ with self.assertRaisesRegex(TypeError, "Incorrect type for column 'number'"):
10
+ self.table.insert({"name": "Ada", "number": "seven", "active": True})
11
+
12
+ with self.assertRaisesRegex(TypeError, "Expected int, got bool"):
13
+ self.table.insert({"name": "Ada", "number": True, "active": True})
14
+
15
+ self.assertEqual(list(self.table.staging_path.iterdir()), [])
16
+ self.assertEqual(list(self.table.rows_path.iterdir()), [])
17
+
18
+ def test_insert_rejects_an_existing_id(self):
19
+ self.insert_row(row_id="duplicate")
20
+
21
+ with self.assertRaisesRegex(FileExistsError, "already exists"):
22
+ self.table.insert(
23
+ {
24
+ "id": "duplicate",
25
+ "name": "Different",
26
+ "number": 99,
27
+ "active": False,
28
+ }
29
+ )
30
+
31
+ def test_failed_insert_removes_new_indexes_and_staging_files(self):
32
+ self.insert_row(row_id="duplicate")
33
+ conflicting_values = ("Different", "99", "False")
34
+
35
+ with self.assertRaises(FileExistsError):
36
+ self.table.insert(
37
+ {
38
+ "id": "duplicate",
39
+ "name": conflicting_values[0],
40
+ "number": int(conflicting_values[1]),
41
+ "active": False,
42
+ }
43
+ )
44
+
45
+ for column, value in zip(("name", "number", "active"), conflicting_values):
46
+ self.assertFalse((self.table.indexes_path / column / value).exists())
47
+ self.assertEqual(list(self.table.staging_path.iterdir()), [])
48
+ current_markers = list(
49
+ (self.table.rows_path / "duplicate").glob("*.current_transaction")
50
+ )
51
+ self.assertEqual(len(current_markers), 1)
@@ -0,0 +1,18 @@
1
+ import unittest
2
+
3
+ from nfs_db import table_spec
4
+
5
+
6
+ class TableSpecTests(unittest.TestCase):
7
+ def test_name_keyword_can_define_a_column(self):
8
+ spec = table_spec("users", name=str)
9
+
10
+ self.assertIs(spec.columns["name"].data_type, str)
11
+
12
+ def test_reserved_id_column_cannot_be_redefined(self):
13
+ with self.assertRaisesRegex(ValueError, "already exists"):
14
+ table_spec("users", id=str)
15
+
16
+ def test_unsupported_column_types_are_rejected(self):
17
+ with self.assertRaisesRegex(TypeError, "must be int, str, float, or bool"):
18
+ table_spec("users", payload=bytes)
@@ -0,0 +1,53 @@
1
+ import errno
2
+ import tempfile
3
+ import unittest
4
+ from pathlib import Path
5
+ from unittest.mock import patch
6
+
7
+ from nfs_db.constants import CURRENT_TRANSACTION_EXTENSION
8
+ from nfs_db.table.transactions import (
9
+ _delete_index,
10
+ delete_transaction,
11
+ update_transaction,
12
+ )
13
+
14
+
15
+ class TransactionCleanupTests(unittest.TestCase):
16
+ def setUp(self):
17
+ self.temporary_directory = tempfile.TemporaryDirectory()
18
+ self.addCleanup(self.temporary_directory.cleanup)
19
+ self.root = Path(self.temporary_directory.name)
20
+
21
+ def test_delete_index_reraises_unexpected_directory_errors(self):
22
+ index = self.root / "value" / "link"
23
+ index.parent.mkdir()
24
+ index.touch()
25
+
26
+ with patch.object(Path, "rmdir", side_effect=OSError(errno.EACCES, "denied")):
27
+ with self.assertRaises(PermissionError):
28
+ _delete_index(index)
29
+
30
+ def test_update_cleanup_handles_a_missing_previous_transaction(self):
31
+ update = update_transaction(
32
+ self.root,
33
+ "row",
34
+ "old-transaction",
35
+ {"id": "row"},
36
+ )
37
+ update.executed = True
38
+
39
+ update.cleanup()
40
+
41
+ self.assertFalse(update.transaction_path.exists())
42
+
43
+ def test_delete_indexes_rejects_missing_marker_and_fields(self):
44
+ delete = delete_transaction(self.root, "row")
45
+ with self.assertRaisesRegex(FileNotFoundError, "does not exist"):
46
+ delete._delete_indexes()
47
+
48
+ transaction_id = "transaction"
49
+ delete.deleted_path = self.root / "deleted"
50
+ delete.deleted_path.mkdir()
51
+ (delete.deleted_path / f"{transaction_id}{CURRENT_TRANSACTION_EXTENSION}").touch()
52
+ with self.assertRaisesRegex(FileNotFoundError, "Fields for row"):
53
+ delete._delete_indexes()
@@ -0,0 +1,111 @@
1
+ from unittest.mock import patch
2
+
3
+ from tests.base_test_case import DatabaseTestCase
4
+
5
+
6
+ class TableUpdateTests(DatabaseTestCase):
7
+ def setUp(self):
8
+ super().setUp()
9
+ self.row_id = self.insert_row()
10
+ self.row_path = self.table.rows_path / self.row_id
11
+
12
+ def test_update_rejects_invalid_callbacks_and_rows(self):
13
+ with self.assertRaisesRegex(TypeError, "edit must be a callable"):
14
+ self.table.update(self.row_id, None)
15
+
16
+ with self.assertRaisesRegex(TypeError, "return a row dictionary"):
17
+ self.table.update(self.row_id, lambda row: None)
18
+
19
+ with self.assertRaisesRegex(ValueError, "exactly the table's columns"):
20
+ self.table.update(self.row_id, lambda row: {"id": self.row_id, "name": "Grace"})
21
+
22
+ with self.assertRaisesRegex(TypeError, "Incorrect type for column 'number'"):
23
+ self.table.update(
24
+ self.row_id,
25
+ lambda row: {**row, "number": "eight"},
26
+ )
27
+
28
+ with self.assertRaisesRegex(TypeError, "Expected int, got bool"):
29
+ self.table.update(
30
+ self.row_id,
31
+ lambda row: {**row, "number": True},
32
+ )
33
+
34
+ def test_update_accepts_a_callback_returning_all_correct_fields(self):
35
+ def edit(row):
36
+ row.update(name="Grace", number=8, active=False)
37
+ return row
38
+
39
+ updated = self.table.update(self.row_id, edit)
40
+
41
+ self.assertEqual(set(updated), set(self.spec.columns))
42
+ self.assertEqual(updated["id"], self.row_id)
43
+ self.assertEqual(updated["name"], "Grace")
44
+ self.assertEqual(updated["number"], 8)
45
+ self.assertFalse(updated["active"])
46
+ self.assertEqual(self.table.get(self.row_id), updated)
47
+
48
+ def test_failed_update_removes_new_indexes_and_transaction_files(self):
49
+ old_transaction_id, old_row = self.table._get_row_snapshot(self.row_id)
50
+ with patch(
51
+ "nfs_db.table.transactions.update_transaction.execute",
52
+ side_effect=OSError("simulated commit failure"),
53
+ ):
54
+ with self.assertRaisesRegex(OSError, "simulated commit failure"):
55
+ self.table.update(
56
+ self.row_id,
57
+ lambda row: {**row, "name": "Grace", "number": 8},
58
+ )
59
+
60
+ self.assertEqual(self.table.get(self.row_id), old_row)
61
+ self.assertEqual(
62
+ {path.name for path in self.row_path.iterdir()},
63
+ {old_transaction_id, f"{old_transaction_id}.current_transaction"},
64
+ )
65
+ self.assertFalse((self.table.indexes_path / "name" / "Grace").exists())
66
+ self.assertFalse((self.table.indexes_path / "number" / "8").exists())
67
+
68
+ def test_successful_update_removes_old_indexes_and_transaction_files(self):
69
+ old_transaction_id, _ = self.table._get_row_snapshot(self.row_id)
70
+
71
+ updated = self.table.update(
72
+ self.row_id,
73
+ lambda row: {**row, "name": "Grace", "number": 8},
74
+ )
75
+
76
+ self.assertFalse((self.table.indexes_path / "name" / "Ada").exists())
77
+ self.assertFalse((self.table.indexes_path / "number" / "7").exists())
78
+ self.assertFalse((self.row_path / old_transaction_id).exists())
79
+ self.assertFalse(
80
+ (self.row_path / f"{old_transaction_id}.current_transaction").exists()
81
+ )
82
+ self.assertEqual(len(list(self.row_path.glob("*.current_transaction"))), 1)
83
+ self.assertEqual(
84
+ len([path for path in self.row_path.iterdir() if path.is_dir()]), 1
85
+ )
86
+ self.assertEqual(updated, self.table.get(self.row_id))
87
+
88
+ def test_update_retries_after_another_update_moves_the_marker(self):
89
+ calls = 0
90
+
91
+ def edit(row):
92
+ nonlocal calls
93
+ calls += 1
94
+ if calls == 1:
95
+ self.table.update(
96
+ self.row_id,
97
+ lambda latest: {**latest, "number": latest["number"] + 10},
98
+ )
99
+ return {**row, "number": row["number"] + 1}
100
+
101
+ updated = self.table.update(self.row_id, edit)
102
+
103
+ self.assertEqual(calls, 2)
104
+ self.assertEqual(updated["number"], 18)
105
+ self.assertEqual(self.table.get(self.row_id), updated)
106
+
107
+ def test_update_does_not_allow_changing_id(self):
108
+ with self.assertRaisesRegex(ValueError, "cannot be modified"):
109
+ self.table.update(self.row_id, lambda row: {**row, "id": "other"})
110
+
111
+ self.assertEqual(self.table.get(self.row_id)["id"], self.row_id)