tai42-storage-github 2.0.1__tar.gz → 2.0.2__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 (26) hide show
  1. {tai42_storage_github-2.0.1/src/tai42_storage_github.egg-info → tai42_storage_github-2.0.2}/PKG-INFO +3 -3
  2. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/pyproject.toml +3 -3
  3. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/src/tai42_storage_github/storage.py +51 -25
  4. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/src/tai42_storage_github/tai-plugin.yml +2 -2
  5. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2/src/tai42_storage_github.egg-info}/PKG-INFO +3 -3
  6. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/src/tai42_storage_github.egg-info/requires.txt +2 -2
  7. tai42_storage_github-2.0.2/tests/test_delete_dir.py +101 -0
  8. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/tests/test_text.py +11 -22
  9. tai42_storage_github-2.0.1/tests/test_delete_dir.py +0 -80
  10. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/LICENSE +0 -0
  11. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/NOTICE +0 -0
  12. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/README.md +0 -0
  13. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/setup.cfg +0 -0
  14. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/src/tai42_storage_github/__init__.py +0 -0
  15. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/src/tai42_storage_github/client.py +0 -0
  16. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/src/tai42_storage_github/docs/index.mdx +0 -0
  17. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/src/tai42_storage_github/py.typed +0 -0
  18. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/src/tai42_storage_github/settings.py +0 -0
  19. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/src/tai42_storage_github.egg-info/SOURCES.txt +0 -0
  20. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/src/tai42_storage_github.egg-info/dependency_links.txt +0 -0
  21. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/src/tai42_storage_github.egg-info/top_level.txt +0 -0
  22. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/tests/test_binary.py +0 -0
  23. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/tests/test_import_graph.py +0 -0
  24. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/tests/test_plugin_spec.py +0 -0
  25. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/tests/test_registration.py +0 -0
  26. {tai42_storage_github-2.0.1 → tai42_storage_github-2.0.2}/tests/test_security.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: tai42-storage-github
3
- Version: 2.0.1
3
+ Version: 2.0.2
4
4
  Summary: GitHub-backed Storage provider (text + binary/media) for the TAI ecosystem.
5
5
  Author-email: tai42 <oss@tai42.ai>
6
6
  License-Expression: Apache-2.0
@@ -19,8 +19,8 @@ Requires-Python: >=3.13
19
19
  Description-Content-Type: text/markdown
20
20
  License-File: LICENSE
21
21
  License-File: NOTICE
22
- Requires-Dist: tai42-contract<26,>=25.0
23
- Requires-Dist: tai42-kit<14,>=13.0
22
+ Requires-Dist: tai42-contract<27,>=26.0
23
+ Requires-Dist: tai42-kit<15,>=14.0
24
24
  Requires-Dist: httpx>=0.28
25
25
  Requires-Dist: pydantic>=2.12
26
26
  Requires-Dist: pydantic-settings>=2.15.0
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "tai42-storage-github"
7
- version = "2.0.1"
7
+ version = "2.0.2"
8
8
  description = "GitHub-backed Storage provider (text + binary/media) for the TAI ecosystem."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.13"
@@ -26,9 +26,9 @@ dependencies = [
26
26
  # The pure interface contract the backend registers through — Storage,
27
27
  # ObjectStat, assert_not_root, and the tai42_app handle.
28
28
  # The contract floor is rewritten by scripts/range_sync.py at release.
29
- "tai42-contract>=25.0,<26",
29
+ "tai42-contract>=26.0,<27",
30
30
  # Pooled clients + settings primitives (PooledClient, TaiBaseSettings, cache).
31
- "tai42-kit>=13.0,<14",
31
+ "tai42-kit>=14.0,<15",
32
32
  "httpx>=0.28",
33
33
  "pydantic>=2.12",
34
34
  "pydantic-settings>=2.15.0",
@@ -13,7 +13,7 @@ from __future__ import annotations
13
13
  import base64
14
14
  import logging
15
15
  import mimetypes
16
- from typing import Final
16
+ from typing import Final, NamedTuple
17
17
 
18
18
  import httpx
19
19
  from tai42_contract.app import tai42_app
@@ -35,6 +35,13 @@ _RAW_FORM: Final = "application/vnd.github.raw+json"
35
35
  _JSON: Final = "application/json"
36
36
 
37
37
 
38
+ class _Blob(NamedTuple):
39
+ """A file in the branch's tree: its path and the blob sha a write or delete names."""
40
+
41
+ path: str
42
+ sha: str
43
+
44
+
38
45
  def _join(base: str, path: str) -> str:
39
46
  """Join ``path`` onto ``base``, dropping empty and stray-slash segments.
40
47
 
@@ -234,13 +241,14 @@ class GithubStorage(Storage):
234
241
 
235
242
  async def list(self) -> list[str]:
236
243
  """Every blob path in the repo."""
237
- return await self._list_blobs("")
244
+ return [blob.path for blob in await self._blobs("")]
238
245
 
239
- async def _list_blobs(self, prefix: str) -> list[str]:
240
- """Every blob path in the repo, optionally filtered to ``prefix``.
246
+ async def _blobs(self, prefix: str) -> list[_Blob]:
247
+ """Every blob in the repo with its blob sha, optionally filtered to ``prefix``.
241
248
 
242
249
  Uses the recursive Git Trees API (one request); its ``truncated`` flag is
243
- raised on loudly rather than acting on a partial listing.
250
+ raised on loudly rather than acting on a partial listing, and so is a blob
251
+ entry carrying no sha.
244
252
  """
245
253
  settings = _configured_settings()
246
254
  url = settings.trees_api_url.format(username=settings.username, repo=settings.repo, branch=settings.branch)
@@ -252,13 +260,18 @@ class GithubStorage(Storage):
252
260
  raise RuntimeError(f"Expected a tree object from {url}, got {type(data).__name__}") # noqa: TRY004 raised type is intentional (invariant/state/validation taxonomy); TypeError would change behaviour
253
261
  if data.get("truncated"):
254
262
  raise RuntimeError(f"GitHub tree listing was truncated; the tree is too large to list safely: {url}")
255
- return [
256
- item["path"]
257
- for item in data.get("tree", [])
258
- if isinstance(item, dict)
259
- and item.get("type") == "blob"
260
- and (not prefix or item["path"].startswith(prefix))
261
- ]
263
+ blobs: list[_Blob] = []
264
+ for item in data.get("tree", []):
265
+ if not isinstance(item, dict) or item.get("type") != "blob":
266
+ continue
267
+ path = item["path"]
268
+ if prefix and not path.startswith(prefix):
269
+ continue
270
+ sha = item.get("sha")
271
+ if not isinstance(sha, str) or not sha:
272
+ raise RuntimeError(f"GitHub tree listing at {url} carries no blob sha for {path}.")
273
+ blobs.append(_Blob(path, sha))
274
+ return blobs
262
275
 
263
276
  async def upload(self, path: str, content: str) -> None:
264
277
  """Write ``content`` (UTF-8) to ``path`` via the Contents API."""
@@ -326,28 +339,41 @@ class GithubStorage(Storage):
326
339
  if not sha:
327
340
  raise RuntimeError(f"GitHub Contents API returned no blob sha for {path}; cannot delete it.")
328
341
 
329
- payload = {"message": f"Delete {path}", "sha": sha, "branch": settings.branch}
330
- resp = await client.request("DELETE", url, headers=headers, json=payload)
331
- _raise_for_status(resp, "deleting", path, url)
342
+ await self._delete_blob(client, settings, path, sha)
332
343
 
333
344
  async def delete_dir(self, path: str) -> None:
334
345
  """Delete every file under ``path`` sequentially (GitHub has no bulk delete).
335
346
 
336
- A failure mid-loop raises immediately; the partial deletion surfaces loudly.
347
+ The one tree listing supplies each file's blob sha, so each file costs one
348
+ DELETE. A file already gone is skipped; a file changed since the listing
349
+ answers 409, which raises like every other failure mid-loop, so a partial
350
+ deletion surfaces loudly.
337
351
  """
338
352
  assert_not_root(path)
339
353
  prefix = path if path.endswith("/") else f"{path}/"
340
- files = await self._list_blobs(prefix)
341
- if not files:
354
+ blobs = await self._blobs(prefix)
355
+ if not blobs:
342
356
  raise FileNotFoundError(f"Directory not found or empty: {path}")
343
357
 
344
- for file_path in files:
345
- try:
346
- await self.delete(file_path)
347
- except FileNotFoundError:
348
- # Already gone (concurrent delete); the delete is idempotent. A
349
- # real DELETE failure raises HTTPStatusError and is not caught here.
350
- logger.info("Object %s already gone during dir delete of %s; skipping", file_path, path)
358
+ settings = _configured_settings()
359
+ async with tai42_app.clients.client_ctx(GithubHttpxClient) as client:
360
+ for blob in blobs:
361
+ try:
362
+ await self._delete_blob(client, settings, blob.path, blob.sha)
363
+ except FileNotFoundError:
364
+ # Already gone (concurrent delete); the delete is idempotent. A
365
+ # real DELETE failure raises HTTPStatusError and is not caught here.
366
+ logger.info("Object %s already gone during dir delete of %s; skipping", blob.path, path)
367
+
368
+ @staticmethod
369
+ async def _delete_blob(client: httpx.AsyncClient, settings: GithubStorageSettings, path: str, sha: str) -> None:
370
+ """Delete the file at ``path`` holding blob ``sha``; a missing object raises ``FileNotFoundError``."""
371
+ url = _contents_url(settings, path)
372
+ payload = {"message": f"Delete {path}", "sha": sha, "branch": settings.branch}
373
+ resp = await client.request("DELETE", url, headers=_api_headers(settings), json=payload)
374
+ if resp.status_code == 404:
375
+ raise FileNotFoundError(f"Object not found: {path}")
376
+ _raise_for_status(resp, "deleting", path, url)
351
377
 
352
378
 
353
379
  __all__ = ["GithubStorage"]
@@ -2,12 +2,12 @@ spec_version: 1
2
2
  namespace: tai42
3
3
  name: storage-github
4
4
  package: tai42-storage-github
5
- version: 2.0.1
5
+ version: 2.0.2
6
6
  description: GitHub-backed Storage provider (text + binary/media) for the TAI ecosystem.
7
7
  license: Apache-2.0
8
8
  homepage: https://tai42.ai
9
9
  repository: https://github.com/tai42ai/tai42/tree/main/plugins/storage-github
10
- contract: '>=25.0,<26'
10
+ contract: '>=26.0,<27'
11
11
  categories:
12
12
  - storage
13
13
  tags:
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: tai42-storage-github
3
- Version: 2.0.1
3
+ Version: 2.0.2
4
4
  Summary: GitHub-backed Storage provider (text + binary/media) for the TAI ecosystem.
5
5
  Author-email: tai42 <oss@tai42.ai>
6
6
  License-Expression: Apache-2.0
@@ -19,8 +19,8 @@ Requires-Python: >=3.13
19
19
  Description-Content-Type: text/markdown
20
20
  License-File: LICENSE
21
21
  License-File: NOTICE
22
- Requires-Dist: tai42-contract<26,>=25.0
23
- Requires-Dist: tai42-kit<14,>=13.0
22
+ Requires-Dist: tai42-contract<27,>=26.0
23
+ Requires-Dist: tai42-kit<15,>=14.0
24
24
  Requires-Dist: httpx>=0.28
25
25
  Requires-Dist: pydantic>=2.12
26
26
  Requires-Dist: pydantic-settings>=2.15.0
@@ -1,5 +1,5 @@
1
- tai42-contract<26,>=25.0
2
- tai42-kit<14,>=13.0
1
+ tai42-contract<27,>=26.0
2
+ tai42-kit<15,>=14.0
3
3
  httpx>=0.28
4
4
  pydantic>=2.12
5
5
  pydantic-settings>=2.15.0
@@ -0,0 +1,101 @@
1
+ """``delete_dir``: the root guard, one tree listing, a DELETE per blob with its tree sha, and error propagation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import pytest
6
+ from httpx import HTTPStatusError
7
+
8
+ from tai42_storage_github import GithubStorage
9
+
10
+ from .conftest import make_response
11
+
12
+ TREE_URL = "https://api.github.com/repos/acme/content/git/trees/dev"
13
+ CONTENTS_URL = "https://api.github.com/repos/acme/content/contents"
14
+
15
+
16
+ def _tree(*entries: dict[str, str]):
17
+ return make_response(status=200, json_body={"truncated": False, "tree": list(entries)})
18
+
19
+
20
+ def _deleted(client) -> list[tuple[str, str]]:
21
+ """The ``(url, sha)`` of every DELETE the client was asked to send."""
22
+ deleted = []
23
+ for call in client.request.call_args_list:
24
+ assert call.args[0] == "DELETE"
25
+ deleted.append((call.args[1], call.kwargs["json"]["sha"]))
26
+ return deleted
27
+
28
+
29
+ @pytest.mark.parametrize("root", ["", "/", ".", " ", "//", "a/..", "./x/../..", "../x", "/.."])
30
+ async def test_delete_dir_root_escape_refused(root):
31
+ with pytest.raises(ValueError, match="storage root"):
32
+ await GithubStorage().delete_dir(root)
33
+
34
+
35
+ @pytest.mark.parametrize("path", ["d", "d/"])
36
+ async def test_delete_dir_deletes_each_blob_under_it_with_its_tree_sha(client, path):
37
+ client.get.return_value = _tree(
38
+ {"path": "d/a.j2", "type": "blob", "sha": "s1"},
39
+ {"path": "d/sub", "type": "tree", "sha": "t1"},
40
+ {"path": "d/sub/b.j2", "type": "blob", "sha": "s2"},
41
+ {"path": "dd/c.j2", "type": "blob", "sha": "s3"},
42
+ {"path": "e/d.j2", "type": "blob", "sha": "s4"},
43
+ )
44
+ client.request.return_value = make_response(status=200)
45
+
46
+ await GithubStorage().delete_dir(path)
47
+
48
+ client.get.assert_awaited_once()
49
+ assert client.get.call_args.args[0] == TREE_URL
50
+ assert client.get.call_args.kwargs["params"] == {"recursive": "1"}
51
+ assert _deleted(client) == [(f"{CONTENTS_URL}/d/a.j2", "s1"), (f"{CONTENTS_URL}/d/sub/b.j2", "s2")]
52
+ payload = client.request.call_args.kwargs["json"]
53
+ assert payload == {"message": "Delete d/sub/b.j2", "sha": "s2", "branch": "dev"}
54
+
55
+
56
+ async def test_delete_dir_of_an_empty_listing_raises_filenotfound_and_deletes_nothing(client):
57
+ client.get.return_value = _tree({"path": "e/a.j2", "type": "blob", "sha": "s1"})
58
+
59
+ with pytest.raises(FileNotFoundError):
60
+ await GithubStorage().delete_dir("d")
61
+
62
+ client.get.assert_awaited_once()
63
+ client.request.assert_not_called()
64
+
65
+
66
+ async def test_delete_dir_skips_a_file_already_gone_and_deletes_the_rest(client):
67
+ client.get.return_value = _tree(
68
+ {"path": "d/a.j2", "type": "blob", "sha": "s1"},
69
+ {"path": "d/b.j2", "type": "blob", "sha": "s2"},
70
+ )
71
+ client.request.side_effect = [make_response(status=404), make_response(status=200)]
72
+
73
+ await GithubStorage().delete_dir("d")
74
+
75
+ assert _deleted(client) == [(f"{CONTENTS_URL}/d/a.j2", "s1"), (f"{CONTENTS_URL}/d/b.j2", "s2")]
76
+
77
+
78
+ async def test_delete_dir_raises_on_a_file_changed_since_the_listing(client):
79
+ client.get.return_value = _tree(
80
+ {"path": "d/a.j2", "type": "blob", "sha": "s1"},
81
+ {"path": "d/b.j2", "type": "blob", "sha": "s2"},
82
+ )
83
+ client.request.return_value = make_response(status=409)
84
+
85
+ with pytest.raises(HTTPStatusError):
86
+ await GithubStorage().delete_dir("d")
87
+
88
+ assert client.request.await_count == 1
89
+
90
+
91
+ async def test_delete_dir_raises_on_a_blob_without_a_sha_before_deleting_anything(client):
92
+ client.get.return_value = _tree(
93
+ {"path": "d/a.j2", "type": "blob", "sha": "s1"},
94
+ {"path": "d/b.j2", "type": "blob"},
95
+ )
96
+
97
+ with pytest.raises(RuntimeError, match="no blob sha"):
98
+ await GithubStorage().delete_dir("d")
99
+
100
+ client.get.assert_awaited_once()
101
+ client.request.assert_not_called()
@@ -82,9 +82,9 @@ async def test_list_returns_blob_paths_via_trees(client):
82
82
  json_body={
83
83
  "truncated": False,
84
84
  "tree": [
85
- {"path": "a.j2", "type": "blob"},
86
- {"path": "d", "type": "tree"},
87
- {"path": "d/b.j2", "type": "blob"},
85
+ {"path": "a.j2", "type": "blob", "sha": "s1"},
86
+ {"path": "d", "type": "tree", "sha": "t1"},
87
+ {"path": "d/b.j2", "type": "blob", "sha": "s2"},
88
88
  ],
89
89
  },
90
90
  )
@@ -123,25 +123,6 @@ async def test_list_server_error_propagates(client):
123
123
  await GithubStorage().list()
124
124
 
125
125
 
126
- async def test_list_blobs_prefix_filters_and_excludes_trees(client):
127
- client.get.return_value = make_response(
128
- status=200,
129
- json_body={
130
- "truncated": False,
131
- "tree": [
132
- {"path": "d/a.j2", "type": "blob"},
133
- {"path": "d/sub", "type": "tree"},
134
- {"path": "d/sub/b.j2", "type": "blob"},
135
- {"path": "dd/c.j2", "type": "blob"},
136
- ],
137
- },
138
- )
139
-
140
- files = await GithubStorage()._list_blobs("d/")
141
-
142
- assert files == ["d/a.j2", "d/sub/b.j2"]
143
-
144
-
145
126
  async def test_upload_create_puts_without_sha(client):
146
127
  client.get.return_value = make_response(status=404)
147
128
  client.put.return_value = make_response(status=200)
@@ -252,6 +233,14 @@ async def test_delete_on_directory_path_raises_filenotfound(client):
252
233
  client.request.assert_not_called()
253
234
 
254
235
 
236
+ async def test_delete_of_a_file_gone_before_its_delete_raises_filenotfound(client):
237
+ client.get.return_value = make_response(status=200, json_body={"sha": "abc"})
238
+ client.request.return_value = make_response(status=404)
239
+
240
+ with pytest.raises(FileNotFoundError):
241
+ await GithubStorage().delete("a/b.j2")
242
+
243
+
255
244
  async def test_delete_call_error_propagates(client):
256
245
  client.get.return_value = make_response(status=200, json_body={"sha": "abc"})
257
246
  client.request.return_value = make_response(status=422)
@@ -1,80 +0,0 @@
1
- """``delete_dir``: the root guard, per-file deletion, and error propagation."""
2
-
3
- from __future__ import annotations
4
-
5
- from unittest.mock import AsyncMock
6
-
7
- import pytest
8
- from httpx import HTTPStatusError, Request
9
-
10
- from tai42_storage_github import GithubStorage
11
-
12
- from .conftest import make_response
13
-
14
-
15
- @pytest.mark.parametrize("root", ["", "/", ".", " ", "//", "a/..", "./x/../..", "../x", "/.."])
16
- async def test_delete_dir_root_escape_refused(root):
17
- with pytest.raises(ValueError, match="storage root"):
18
- await GithubStorage().delete_dir(root)
19
-
20
-
21
- async def test_delete_dir_deletes_each_file(monkeypatch):
22
- store = GithubStorage()
23
- list_blobs = AsyncMock(return_value=["d/a.j2", "d/b.j2"])
24
- monkeypatch.setattr(store, "_list_blobs", list_blobs)
25
- deleted: list[str] = []
26
- monkeypatch.setattr(store, "delete", AsyncMock(side_effect=lambda p: deleted.append(p)))
27
-
28
- await store.delete_dir("d")
29
-
30
- assert deleted == ["d/a.j2", "d/b.j2"]
31
- # The prefix passed to the listing carries a trailing slash so "d" never
32
- # matches sibling "dd/...".
33
- assert list_blobs.call_args.args[0] == "d/"
34
-
35
-
36
- async def test_delete_dir_keeps_existing_trailing_slash(monkeypatch):
37
- store = GithubStorage()
38
- list_blobs = AsyncMock(return_value=["d/a.j2"])
39
- monkeypatch.setattr(store, "_list_blobs", list_blobs)
40
- monkeypatch.setattr(store, "delete", AsyncMock())
41
-
42
- await store.delete_dir("d/")
43
-
44
- assert list_blobs.call_args.args[0] == "d/"
45
-
46
-
47
- async def test_delete_dir_empty_raises_filenotfound(monkeypatch):
48
- store = GithubStorage()
49
- monkeypatch.setattr(store, "_list_blobs", AsyncMock(return_value=[]))
50
-
51
- with pytest.raises(FileNotFoundError):
52
- await store.delete_dir("d")
53
-
54
-
55
- async def test_delete_dir_tolerates_vanished_file(monkeypatch):
56
- store = GithubStorage()
57
- monkeypatch.setattr(store, "_list_blobs", AsyncMock(return_value=["d/a.j2", "d/b.j2"]))
58
- deleted: list[str] = []
59
-
60
- async def _delete(p):
61
- if p == "d/a.j2":
62
- raise FileNotFoundError("vanished")
63
- deleted.append(p)
64
-
65
- monkeypatch.setattr(store, "delete", AsyncMock(side_effect=_delete))
66
-
67
- await store.delete_dir("d")
68
-
69
- assert deleted == ["d/b.j2"]
70
-
71
-
72
- async def test_delete_dir_real_failure_propagates(monkeypatch):
73
- store = GithubStorage()
74
- monkeypatch.setattr(store, "_list_blobs", AsyncMock(return_value=["d/a.j2", "d/b.j2"]))
75
- request = Request("DELETE", "https://example.invalid")
76
- err = HTTPStatusError("boom", request=request, response=make_response(status=500))
77
- monkeypatch.setattr(store, "delete", AsyncMock(side_effect=err))
78
-
79
- with pytest.raises(HTTPStatusError):
80
- await store.delete_dir("d")