holder-kit 0.2.5__tar.gz → 0.2.6__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 (81) hide show
  1. {holder_kit-0.2.5 → holder_kit-0.2.6}/PKG-INFO +15 -15
  2. {holder_kit-0.2.5 → holder_kit-0.2.6}/README.md +14 -14
  3. holder_kit-0.2.6/VERSION +1 -0
  4. holder_kit-0.2.6/_build_backend/backend.py +12 -0
  5. holder_kit-0.2.6/_build_support.py +60 -0
  6. {holder_kit-0.2.5 → holder_kit-0.2.6}/docs/development.md +11 -12
  7. {holder_kit-0.2.5 → holder_kit-0.2.6}/docs/packaging.md +9 -8
  8. {holder_kit-0.2.5 → holder_kit-0.2.6}/docs/record-contracts.md +80 -96
  9. {holder_kit-0.2.5 → holder_kit-0.2.6}/docs/walkthrough.md +4 -4
  10. holder_kit-0.2.6/examples/milestone_analysis.py +35 -0
  11. {holder_kit-0.2.5 → holder_kit-0.2.6}/pyproject.toml +10 -2
  12. {holder_kit-0.2.5 → holder_kit-0.2.6}/scripts/check-release-distributions.py +6 -4
  13. {holder_kit-0.2.5 → holder_kit-0.2.6}/scripts/develop.py +1 -1
  14. {holder_kit-0.2.5 → holder_kit-0.2.6}/scripts/test-installed-debian.py +1 -1
  15. {holder_kit-0.2.5 → holder_kit-0.2.6}/scripts/test-installed-wheel.py +2 -4
  16. {holder_kit-0.2.5 → holder_kit-0.2.6}/src/holderkit/__init__.py +6 -6
  17. holder_kit-0.2.6/src/holderkit/_native.pyi +69 -0
  18. {holder_kit-0.2.5 → holder_kit-0.2.6}/src/holderkit/_storage.py +1 -5
  19. {holder_kit-0.2.5 → holder_kit-0.2.6}/src/holderkit/card_collections.py +20 -14
  20. {holder_kit-0.2.5 → holder_kit-0.2.6}/src/holderkit/collections.py +104 -41
  21. {holder_kit-0.2.5 → holder_kit-0.2.6}/src/holderkit/data/__init__.py +2 -2
  22. {holder_kit-0.2.5 → holder_kit-0.2.6}/src/holderkit/data/card.py +2 -4
  23. {holder_kit-0.2.5 → holder_kit-0.2.6}/src/holderkit/data/connection.py +2 -0
  24. holder_kit-0.2.6/src/holderkit/data/milestone.py +127 -0
  25. {holder_kit-0.2.5 → holder_kit-0.2.6}/src/holderkit/data/project.py +14 -21
  26. {holder_kit-0.2.5 → holder_kit-0.2.6}/src/holderkit/data/tag.py +1 -2
  27. {holder_kit-0.2.5 → holder_kit-0.2.6}/src/holderkit/dataframe.py +6 -2
  28. {holder_kit-0.2.5 → holder_kit-0.2.6}/src/holderkit/project_collections.py +30 -59
  29. holder_kit-0.2.6/src/native/module.c +1747 -0
  30. holder_kit-0.2.6/tests/conftest.py +119 -0
  31. {holder_kit-0.2.5 → holder_kit-0.2.6}/tests/test_card_batches.py +14 -39
  32. {holder_kit-0.2.5 → holder_kit-0.2.6}/tests/test_card_collections.py +29 -27
  33. {holder_kit-0.2.5 → holder_kit-0.2.6}/tests/test_card_navigation.py +7 -1
  34. {holder_kit-0.2.5 → holder_kit-0.2.6}/tests/test_connections.py +2 -2
  35. {holder_kit-0.2.5 → holder_kit-0.2.6}/tests/test_graph.py +2 -1
  36. {holder_kit-0.2.5 → holder_kit-0.2.6}/tests/test_holder.py +25 -11
  37. {holder_kit-0.2.5 → holder_kit-0.2.6}/tests/test_live_cards.py +8 -5
  38. {holder_kit-0.2.5 → holder_kit-0.2.6}/tests/test_make.py +1 -1
  39. holder_kit-0.2.6/tests/test_milestones.py +262 -0
  40. {holder_kit-0.2.5 → holder_kit-0.2.6}/tests/test_pandas.py +12 -7
  41. {holder_kit-0.2.5 → holder_kit-0.2.6}/tests/test_projects.py +10 -21
  42. {holder_kit-0.2.5 → holder_kit-0.2.6}/tests/test_tags.py +16 -15
  43. holder_kit-0.2.5/AGENTS.md +0 -20
  44. holder_kit-0.2.5/examples/milestone_analysis.py +0 -31
  45. holder_kit-0.2.5/src/holderkit/_native.pyi +0 -65
  46. holder_kit-0.2.5/src/holderkit/data/milestone.py +0 -71
  47. holder_kit-0.2.5/src/native/module.c +0 -1074
  48. holder_kit-0.2.5/tests/test_milestones.py +0 -234
  49. {holder_kit-0.2.5 → holder_kit-0.2.6}/.gitignore +0 -0
  50. {holder_kit-0.2.5 → holder_kit-0.2.6}/CMakeLists.txt +0 -0
  51. {holder_kit-0.2.5 → holder_kit-0.2.6}/LICENSE +0 -0
  52. {holder_kit-0.2.5 → holder_kit-0.2.6}/docs/building.md +0 -0
  53. {holder_kit-0.2.5 → holder_kit-0.2.6}/docs/publication.md +0 -0
  54. {holder_kit-0.2.5 → holder_kit-0.2.6}/docs/storage.md +0 -0
  55. {holder_kit-0.2.5 → holder_kit-0.2.6}/docs/which_holder_python_api.png +0 -0
  56. {holder_kit-0.2.5 → holder_kit-0.2.6}/docs/workflow.png +0 -0
  57. {holder_kit-0.2.5 → holder_kit-0.2.6}/examples/card_lifecycle.py +0 -0
  58. {holder_kit-0.2.5 → holder_kit-0.2.6}/examples/detached_records.py +0 -0
  59. {holder_kit-0.2.5 → holder_kit-0.2.6}/examples/finish_project.py +0 -0
  60. {holder_kit-0.2.5 → holder_kit-0.2.6}/examples/graph_analysis.py +0 -0
  61. {holder_kit-0.2.5 → holder_kit-0.2.6}/examples/make_project.py +0 -0
  62. {holder_kit-0.2.5 → holder_kit-0.2.6}/examples/pandas_analysis.py +0 -0
  63. {holder_kit-0.2.5 → holder_kit-0.2.6}/examples/reopen_project.py +0 -0
  64. {holder_kit-0.2.5 → holder_kit-0.2.6}/examples/tag_analysis.py +0 -0
  65. {holder_kit-0.2.5 → holder_kit-0.2.6}/make.sh +0 -0
  66. {holder_kit-0.2.5 → holder_kit-0.2.6}/packaging/linux/debian/changelog +0 -0
  67. {holder_kit-0.2.5 → holder_kit-0.2.6}/packaging/linux/debian/control +0 -0
  68. {holder_kit-0.2.5 → holder_kit-0.2.6}/packaging/linux/debian/copyright +0 -0
  69. {holder_kit-0.2.5 → holder_kit-0.2.6}/packaging/linux/debian/rules +0 -0
  70. {holder_kit-0.2.5 → holder_kit-0.2.6}/packaging/linux/debian/source/format +0 -0
  71. {holder_kit-0.2.5 → holder_kit-0.2.6}/scripts/__init__.py +0 -0
  72. {holder_kit-0.2.5 → holder_kit-0.2.6}/scripts/licenses/microsoft-runtime.txt +0 -0
  73. {holder_kit-0.2.5 → holder_kit-0.2.6}/scripts/pypi_readme.py +0 -0
  74. {holder_kit-0.2.5 → holder_kit-0.2.6}/scripts/repair-linux-wheel.py +0 -0
  75. {holder_kit-0.2.5 → holder_kit-0.2.6}/scripts/system-core-build-info.py +0 -0
  76. {holder_kit-0.2.5 → holder_kit-0.2.6}/scripts/ubuntu-package-ci.sh +0 -0
  77. {holder_kit-0.2.5 → holder_kit-0.2.6}/scripts/wheel-notices.py +0 -0
  78. {holder_kit-0.2.5 → holder_kit-0.2.6}/src/holderkit/_publication.py +0 -0
  79. {holder_kit-0.2.5 → holder_kit-0.2.6}/src/holderkit/graph.py +0 -0
  80. {holder_kit-0.2.5 → holder_kit-0.2.6}/src/holderkit/py.typed +0 -0
  81. {holder_kit-0.2.5 → holder_kit-0.2.6}/tests/test_card_movement.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: holder-kit
3
- Version: 0.2.5
3
+ Version: 0.2.6
4
4
  Summary: Holder Kit: CPython bindings for embedded libholder
5
5
  License-Expression: GPL-3.0-only
6
6
  Project-URL: Repository, https://github.com/HolderTeam/holder/tree/main/python/kit
@@ -39,7 +39,7 @@ The base package exposes ordinary Python records and has no data-science depende
39
39
 
40
40
  A typical workflow looks like this:
41
41
 
42
- ![AI generated image](https://raw.githubusercontent.com/HolderTeam/holder/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/workflow.png)
42
+ ![AI generated image](https://raw.githubusercontent.com/HolderTeam/holder/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/workflow.png)
43
43
 
44
44
  1. You make a new project, or clone an existing one.
45
45
  2. You do work and analysis.
@@ -73,9 +73,9 @@ local storage automatically. These examples need Git installed.
73
73
  When your experiment is ready, publish it while the project is open with
74
74
  `project.push(remote_url="git@example.org:research.git", branch="experiments/results")`.
75
75
  Use `project.close()` to keep your work, or `project.discard(confirm=True)` to
76
- remove it locally. See [Publishing and finishing a project](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/publication.md).
76
+ remove it locally. See [Publishing and finishing a project](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/publication.md).
77
77
 
78
- Follow the [walkthrough](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/walkthrough.md) to create connected cards, add tags
78
+ Follow the [walkthrough](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/walkthrough.md) to create connected cards, add tags
79
79
  and milestones, and analyse detached records with pandas and NetworkX.
80
80
 
81
81
  ## Installation
@@ -84,7 +84,7 @@ Holder Kit is currently in early development.
84
84
 
85
85
  The Python distribution is named `holder-kit` and the import package is `holderkit`.
86
86
 
87
- See [Building Holder Kit](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/building.md) for installing the current version from source.
87
+ See [Building Holder Kit](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/building.md) for installing the current version from source.
88
88
 
89
89
  Ubuntu packages are also available as `python3-holder-kit` for supported Holder package repositories.
90
90
 
@@ -95,7 +95,7 @@ the Python process. This makes it suitable for scripts, notebooks, data analysis
95
95
  and applications that want to embed Holder functionality.
96
96
 
97
97
  To control a running Holder installation through the Framework API, use
98
- [holder-python](https://github.com/HolderTeam/holder/tree/9f3155a328431c6a5bde1b6194895834ac751437/python/holder).
98
+ [holder-python](https://github.com/HolderTeam/holder/tree/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/holder).
99
99
 
100
100
  Holder Kit is part of [Holder](https://github.com/HolderTeam/holder) and is
101
101
  released with it, at the same version.
@@ -112,17 +112,17 @@ The repository includes examples covering:
112
112
  - milestone and calendar analysis;
113
113
  - creating projects, retaining local edits and explicitly finishing an experiment.
114
114
 
115
- See the [`examples/`](https://github.com/HolderTeam/holder/tree/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/examples) directory.
115
+ See the [`examples/`](https://github.com/HolderTeam/holder/tree/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/examples) directory.
116
116
 
117
117
  ## Documentation
118
118
 
119
- - [Walkthrough](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/walkthrough.md)
120
- - [Publishing and finishing a project](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/publication.md)
121
- - [Detached record contracts](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/record-contracts.md)
122
- - [Advanced: storage and reopening](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/storage.md)
123
- - [Building from source](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/building.md)
124
- - [Development](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/development.md)
125
- - [Packaging](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/packaging.md)
119
+ - [Walkthrough](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/walkthrough.md)
120
+ - [Publishing and finishing a project](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/publication.md)
121
+ - [Detached record contracts](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/record-contracts.md)
122
+ - [Advanced: storage and reopening](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/storage.md)
123
+ - [Building from source](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/building.md)
124
+ - [Development](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/development.md)
125
+ - [Packaging](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/packaging.md)
126
126
 
127
127
  ## Status
128
128
 
@@ -130,4 +130,4 @@ Holder Kit is under active development. The current API covers projects, cards,
130
130
 
131
131
  ## Licence
132
132
 
133
- See [LICENSE](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/LICENSE).
133
+ See [LICENSE](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/LICENSE).
@@ -17,7 +17,7 @@ The base package exposes ordinary Python records and has no data-science depende
17
17
 
18
18
  A typical workflow looks like this:
19
19
 
20
- ![AI generated image](https://raw.githubusercontent.com/HolderTeam/holder/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/workflow.png)
20
+ ![AI generated image](https://raw.githubusercontent.com/HolderTeam/holder/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/workflow.png)
21
21
 
22
22
  1. You make a new project, or clone an existing one.
23
23
  2. You do work and analysis.
@@ -51,9 +51,9 @@ local storage automatically. These examples need Git installed.
51
51
  When your experiment is ready, publish it while the project is open with
52
52
  `project.push(remote_url="git@example.org:research.git", branch="experiments/results")`.
53
53
  Use `project.close()` to keep your work, or `project.discard(confirm=True)` to
54
- remove it locally. See [Publishing and finishing a project](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/publication.md).
54
+ remove it locally. See [Publishing and finishing a project](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/publication.md).
55
55
 
56
- Follow the [walkthrough](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/walkthrough.md) to create connected cards, add tags
56
+ Follow the [walkthrough](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/walkthrough.md) to create connected cards, add tags
57
57
  and milestones, and analyse detached records with pandas and NetworkX.
58
58
 
59
59
  ## Installation
@@ -62,7 +62,7 @@ Holder Kit is currently in early development.
62
62
 
63
63
  The Python distribution is named `holder-kit` and the import package is `holderkit`.
64
64
 
65
- See [Building Holder Kit](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/building.md) for installing the current version from source.
65
+ See [Building Holder Kit](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/building.md) for installing the current version from source.
66
66
 
67
67
  Ubuntu packages are also available as `python3-holder-kit` for supported Holder package repositories.
68
68
 
@@ -73,7 +73,7 @@ the Python process. This makes it suitable for scripts, notebooks, data analysis
73
73
  and applications that want to embed Holder functionality.
74
74
 
75
75
  To control a running Holder installation through the Framework API, use
76
- [holder-python](https://github.com/HolderTeam/holder/tree/9f3155a328431c6a5bde1b6194895834ac751437/python/holder).
76
+ [holder-python](https://github.com/HolderTeam/holder/tree/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/holder).
77
77
 
78
78
  Holder Kit is part of [Holder](https://github.com/HolderTeam/holder) and is
79
79
  released with it, at the same version.
@@ -90,17 +90,17 @@ The repository includes examples covering:
90
90
  - milestone and calendar analysis;
91
91
  - creating projects, retaining local edits and explicitly finishing an experiment.
92
92
 
93
- See the [`examples/`](https://github.com/HolderTeam/holder/tree/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/examples) directory.
93
+ See the [`examples/`](https://github.com/HolderTeam/holder/tree/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/examples) directory.
94
94
 
95
95
  ## Documentation
96
96
 
97
- - [Walkthrough](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/walkthrough.md)
98
- - [Publishing and finishing a project](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/publication.md)
99
- - [Detached record contracts](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/record-contracts.md)
100
- - [Advanced: storage and reopening](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/storage.md)
101
- - [Building from source](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/building.md)
102
- - [Development](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/development.md)
103
- - [Packaging](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/packaging.md)
97
+ - [Walkthrough](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/walkthrough.md)
98
+ - [Publishing and finishing a project](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/publication.md)
99
+ - [Detached record contracts](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/record-contracts.md)
100
+ - [Advanced: storage and reopening](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/storage.md)
101
+ - [Building from source](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/building.md)
102
+ - [Development](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/development.md)
103
+ - [Packaging](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/packaging.md)
104
104
 
105
105
  ## Status
106
106
 
@@ -108,4 +108,4 @@ Holder Kit is under active development. The current API covers projects, cards,
108
108
 
109
109
  ## Licence
110
110
 
111
- See [LICENSE](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/LICENSE).
111
+ See [LICENSE](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/LICENSE).
@@ -0,0 +1 @@
1
+ 0.2.6
@@ -0,0 +1,12 @@
1
+ """Prepare product-version metadata, then delegate to the existing build backend."""
2
+ import importlib.util
3
+ from pathlib import Path
4
+
5
+ PACKAGE = Path(__file__).resolve().parents[1]
6
+ shared = PACKAGE.parent / '_build_support.py'
7
+ path = shared if shared.is_file() else PACKAGE / '_build_support.py'
8
+ spec = importlib.util.spec_from_file_location('_holder_build_support', path)
9
+ support = importlib.util.module_from_spec(spec)
10
+ spec.loader.exec_module(support)
11
+
12
+ globals().update(support.backend_hooks(PACKAGE, 'scikit_build_core.build'))
@@ -0,0 +1,60 @@
1
+ """Shared PEP 517 version preparation; copied into standalone source packages."""
2
+ from __future__ import annotations
3
+
4
+ import functools
5
+ import importlib
6
+ import os
7
+ from pathlib import Path
8
+ import re
9
+ from email.parser import Parser
10
+
11
+
12
+ def read_version(package: Path, *, preview: bool = False, env=None) -> str:
13
+ package = package.resolve()
14
+ checkout = (package.parent / '_build_support.py').is_file()
15
+ source = package.parent.parent / 'VERSION' if checkout else package / 'VERSION'
16
+ if not source.is_file():
17
+ raise ValueError(f'Missing version input: {source}; prepare the exported source before building')
18
+ version = source.read_text().strip()
19
+ if not re.fullmatch(r'[0-9]+\.[0-9]+\.[0-9]+(?:[-+.][0-9A-Za-z.-]+)?', version):
20
+ raise ValueError(f'Invalid product version in {source}: {version!r}')
21
+ if preview:
22
+ number = int((os.environ if env is None else env).get('HOLDER_PYTHON_PREVIEW_NUMBER', '0'))
23
+ if number < 0:
24
+ raise ValueError('Preview number must be non-negative')
25
+ if number:
26
+ if checkout:
27
+ version = f'{version}.post{number}'
28
+ elif not version.endswith(f'.post{number}'):
29
+ raise ValueError('Preview number differs from the prepared source version')
30
+ metadata = package / 'PKG-INFO'
31
+ if not checkout and metadata.is_file():
32
+ recorded = Parser().parsestr(metadata.read_text())['Version']
33
+ if recorded != version:
34
+ raise ValueError('Prepared VERSION differs from source-distribution metadata')
35
+ return version
36
+
37
+
38
+ def prepare(package: Path, *, preview: bool = False) -> None:
39
+ version = read_version(package, preview=preview)
40
+ (package / 'VERSION').write_text(version + '\n')
41
+ support = package / '_build_support.py'
42
+ if support.resolve() != Path(__file__).resolve():
43
+ support.write_bytes(Path(__file__).read_bytes())
44
+
45
+
46
+ def backend_hooks(package: Path, backend: str, *, preview: bool = False) -> dict:
47
+ delegate = importlib.import_module(backend)
48
+
49
+ def wrapped(hook):
50
+ @functools.wraps(hook)
51
+ def call(*args, **kwargs):
52
+ prepare(package, preview=preview)
53
+ return hook(*args, **kwargs)
54
+ return call
55
+
56
+ names = ('build_wheel', 'build_sdist', 'build_editable',
57
+ 'prepare_metadata_for_build_wheel', 'prepare_metadata_for_build_editable',
58
+ 'get_requires_for_build_wheel', 'get_requires_for_build_sdist',
59
+ 'get_requires_for_build_editable')
60
+ return {name: wrapped(getattr(delegate, name)) for name in names if hasattr(delegate, name)}
@@ -19,9 +19,12 @@ Holder Kit embeds libholder in the Python process. It does not talk to a running
19
19
 
20
20
  Keep reusable storage and domain behavior in core (`../../core`). The Python
21
21
  layer calls core's semantic operations, including tag and milestone edits, rather
22
- than reimplementing them by parsing or rewriting card files. Kit uses only core's
23
- C API; see [AGENTS.md](../AGENTS.md). A change that needs both goes in one pull
24
- request.
22
+ than reimplementing them by parsing or rewriting card files. Kit uses only
23
+ core's generated C API, `#include <holder/holder_api.h>`. Its native extension must not
24
+ include core's other headers or refer to files in `../../core` by path from code,
25
+ CMake or scripts. Kit consumes core's installed header, CMake package and schema;
26
+ CI checks this boundary by building against a core SDK from the same commit.
27
+ A change that needs both goes in one pull request, with core's own tests.
25
28
 
26
29
  The package ships the schema from the selected core source or SDK as
27
30
  `holderkit/_schema.sql`. Installed packages must work without a source checkout.
@@ -102,10 +105,8 @@ dependencies, ownership checks and failure behavior where relevant.
102
105
 
103
106
  ## Clone build requirements
104
107
 
105
- Clone uses core's `holder_project_import` API, which the core beside Kit
106
- provides. Building against an older core SDK without project import support
107
- still makes clone raise `NotImplementedError` before creating storage or
108
- contacting the remote.
108
+ Clone uses core's generated `holder_import_project` API. Build Kit against a
109
+ core SDK from the same revision so this operation is available.
109
110
 
110
111
  ## Native sanitizers
111
112
 
@@ -151,9 +152,7 @@ former `holder` distribution and replace `import holder` with `import holderkit`
151
152
  Dependency declarations use `holder-kit`, `holder-kit[pandas]` or
152
153
  `holder-kit[graph]`. There is no compatibility import shim.
153
154
 
154
- ## Filtered card batch build requirements
155
+ ## Card batches
155
156
 
156
- Filtered `project.cards(...)` batches use Core's `holder_card_collection_page_json`
157
- API, advertised by `HOLDER_HAS_CARD_COLLECTION_PAGE`, which the core beside Kit
158
- provides. Existing unfiltered batches work with older SDKs; requesting filters
159
- or explicit ordering without this API raises `NotImplementedError`.
157
+ `project.cards(...)` batches, filtered or not, page through Core's generated
158
+ `list_cards` operation, which Kit builds against from the same commit.
@@ -1,8 +1,8 @@
1
1
  # Packaging Holder Kit
2
2
 
3
3
  The Python distribution is `holder-kit`; its import package is `holderkit`.
4
- The version in `pyproject.toml` is independent of libholder and the Holder
5
- Framework. The base package has no data-science dependencies; `pandas` and
4
+ Package metadata derives its version from root `VERSION` in a checkout; source
5
+ distributions retain that version for standalone rebuilds. The base package has no data-science dependencies; `pandas` and
6
6
  `graph` are optional extras.
7
7
 
8
8
  See [Building](building.md) for prerequisites and core selection, and
@@ -51,7 +51,7 @@ installed SDK-wheel smoke test, including `_core_build.json` validation.
51
51
 
52
52
  `Release / Kit to PyPI`
53
53
  ([`release-kit-pypi.yml`](../../../.github/workflows/release-kit-pypi.yml))
54
- builds wheels for CPython 3.10–3.14 and a source archive. Supported wheel platforms are:
54
+ builds wheels for CPython 3.10–3.15 and a source archive. Supported wheel platforms are:
55
55
 
56
56
  | Platform | Architecture | Minimum runtime |
57
57
  | --- | --- | --- |
@@ -84,7 +84,7 @@ Each wheel is installed in a fresh virtualenv and tested before optional
84
84
  adapters are installed, then runs the installed integration tests. Linux also
85
85
  runs in clean Debian Python containers. The source archive is built and
86
86
  installed with the same Release SDK. The final distribution check requires all
87
- 15 wheels and the source archive, checks each wheel's core against the SDKs'
87
+ 18 wheels and the source archive, checks each wheel's core against the SDKs'
88
88
  `core-selection`, validates metadata, and records the core and the file sizes
89
89
  and SHA256 hashes in the `kit-release-manifest` artifact.
90
90
 
@@ -106,7 +106,7 @@ candidates. `pypi` or `testpypi` publishes only after all distribution checks
106
106
  pass, using the corresponding GitHub environment and Trusted Publishing.
107
107
  Holder Kit is released with the rest of Holder, at the same version: publishing
108
108
  must run from the release's `holder-v<version>` tag, and requires the version in
109
- `pyproject.toml`, the repository's `VERSION` and core's version to equal it. Pull requests build candidates without
109
+ the repository's `VERSION` and core's version to equal it. Pull requests build candidates without
110
110
  publishing.
111
111
 
112
112
  ## Ubuntu packages
@@ -159,10 +159,11 @@ installs optional adapters and runs integration tests.
159
159
 
160
160
  `holder-kit` is one of the source packages that `Release / Launchpad`
161
161
  ([`release-launchpad.yml`](../../../.github/workflows/release-launchpad.yml))
162
- uploads to `ppa:holderteam/holder`, with `holder-core` and `holder-daemon`. The
163
- release tag uploads all three. A manual run with `packages=kit` and a new
162
+ uploads to `ppa:holderteam/holder`, with `holder-core`, `holder-daemon` and
163
+ `holder-desktop`. The release tag uploads all four. A manual run with `packages=kit` and a new
164
164
  `package_revision` uploads only Kit, for a packaging-only fix. Kit's version
165
165
  must equal core's: its source package builds against `libholder-dev` of that
166
166
  version, so on Launchpad it waits for the core packages from the same upload.
167
- The upstream tarball is `python/kit/` as committed. Pull requests that change
167
+ The upstream tarball contains committed `python/kit/` source plus generated
168
+ `VERSION` and the shared Python build helper from the same commit. Pull requests that change
168
169
  the packaging build the source package unsigned without uploading.
@@ -23,7 +23,6 @@ requiring a sample row.
23
23
  | `name` | `str` | Project display name |
24
24
  | `root_path` | `str` | Project storage root reported by libholder |
25
25
  | `privacy_mode` | `str` | Current privacy mode |
26
- | `id_scheme` | `str` | Identifier scheme reported by libholder |
27
26
  | `created_at` | `int` | Creation time as Unix seconds |
28
27
  | `updated_at` | `int` | Last update time as Unix seconds |
29
28
  | `git_remote_url` | `str \| None` | Configured Git remote URL |
@@ -45,7 +44,7 @@ requiring a sample row.
45
44
  | `deleted_at` | `int \| None` | Soft-deletion time; live exports use `None` |
46
45
 
47
46
  This inexpensive contract is returned by `cards.to_records()`. It comes from
48
- `holder_card_list` and does not open or decrypt card files.
47
+ `holder_list_cards` with `include_content=false` and does not open or decrypt card files.
49
48
 
50
49
  ## `CompleteCardRecord`
51
50
 
@@ -65,9 +64,9 @@ columns in either card record contract.
65
64
 
66
65
  ## Extraction behavior and limitations
67
66
 
68
- Metadata-only extraction calls `holder_card_list` once per selected project.
69
- Complete extraction uses `holder_card_list_complete_page` and follows its
70
- opaque cursor until exhausted, avoiding one native operation per card. Each
67
+ Metadata-only extraction calls `holder_list_cards` with `include_content=false`
68
+ and follows its opaque cursor. Complete extraction calls the same operation
69
+ with `include_content=true`, avoiding one native operation per card. Each
71
70
  page is ordered by `card_id`, contains live cards only, and reads bodies from
72
71
  their authoritative durable files rather than the disposable FTS index.
73
72
 
@@ -177,11 +176,11 @@ in Trash raises `ValueError`. Restoring the Card makes its retained adapters
177
176
  usable again. There is no cached membership data or automatic reopening.
178
177
 
179
178
  - `card.tags.list()` and `.list_editable()` return tag names. `.add(tag)` and
180
- `.remove(tag)` retain `TagAddResult` and `TagRemoveResult`, including the
181
- distinction between trailing tags and occurrences in prose. `.to_records()`
179
+ `.remove(tag)` retain `TagAddResult` and `TagRemoveResult`. Removing a tag
180
+ that also occurs in prose raises `HolderError`. `.to_records()`
182
181
  returns only that card's `TagRecord` values; `.to_dataframe()` uses the tag
183
182
  schema and dtypes. Core's editable-tag read still reads the authoritative
184
- body and retains its existing missing-file policy.
183
+ body and raises `HolderError` when the card file is missing.
185
184
  - `card.connections.add(target_card, kind, label=None)` and
186
185
  `.remove(target_card, kind)` accept a Card, not an ID. Both owners must be
187
186
  open, target identity must exist, and the Cards must share a Context. Targets
@@ -191,13 +190,11 @@ usable again. There is no cached membership data or automatic reopening.
191
190
  including external or unresolved targets already stored by Core. They do not
192
191
  add backlinks, hierarchy connections or inline wikilinks.
193
192
  - `card.milestones.list()` and `.to_records()` return `MilestoneRecord` values
194
- for that card. `.add(start_at, end_at=None, all_day=False, kind=None,
195
- description=None)` retains the Project operation's keyword-only options and
196
- returns the updated full list. `.update(milestone_id, changes)` returns one
197
- record and uses the existing tri-state `MilestoneUpdate` validation and
198
- ownership checks. `.remove(milestone_id)` retains Core's no-op behaviour for
199
- absent or foreign IDs. `.to_dataframe()` uses the milestone schema without
200
- the project/title columns of a project-wide export.
193
+ for that card. `.add(dates=(), *, kind=None, description=None)` returns the
194
+ new milestone. `.update(milestone_id, changes)` returns the updated record.
195
+ `.remove(milestone_id)` returns the card's remaining milestones; removing an
196
+ absent ID, or one on another card, changes nothing. `.to_dataframe()` uses the
197
+ milestone schema without the `card_title` column of a project-wide export.
201
198
 
202
199
  These single-card exports use existing scoped reads and do not scan all project
203
200
  cards. Results are detached and remain usable after close; changing them does
@@ -278,25 +275,29 @@ non-card targets; use `to_type` to distinguish those targets.
278
275
  | `project_id` | `str` | Source card's owning project |
279
276
  | `from_card_id` | `str` | Source card identifier |
280
277
  | `to_card_id` | `str` | Target identifier |
278
+ | `target_project_id` | `str \| None` | Explicit target project, or `None` for the source project |
281
279
  | `to_type` | `str` | Core target type, such as `card` or `resource` |
282
280
  | `kind` | `str` | Relationship kind; custom kinds are allowed |
283
281
  | `label` | `str \| None` | Optional connection label |
284
282
  | `created_at` | `int` | Core timestamp in Unix seconds; core refreshes it on upsert |
285
- | `to_title` | `str \| None` | Resolved target card title, or `None` |
283
+ | `to_title` | `str \| None` | Target card title when a loaded card belongs to the declared target project, or `None` |
286
284
 
287
285
  Core has no separate connection ID. Identity is the tuple
288
- `(project_id, from_card_id, to_card_id, to_type, kind)`. Several kinds may connect
286
+ `(project_id, from_card_id, target_project_id or project_id, to_card_id, to_type, kind)`. Several kinds may connect
289
287
  the same ordered pair; reverse-direction links and self-links are distinct.
290
288
  `CONNECTION_RECORD_FIELDS` defines column order, including for empty exports.
291
289
  The pandas adapter uses nullable string columns and UTC timestamps with the
292
290
  same rules as the other tables. Join `from_card_id` to card records' `card_id`,
293
- and join card targets by `to_card_id` after selecting `to_type == "card"`.
291
+ and join card targets by both the effective target project and `to_card_id` after
292
+ selecting `to_type == "card"`.
294
293
 
295
- Extraction first selects card metadata and then calls `holder_card_list_links`
294
+ Extraction first selects card metadata and then calls `holder_list_card_links`
296
295
  once per source card. It does not read bodies or provide an atomic snapshot
297
296
  across cards/projects. Errors propagate instead of returning a partial list.
298
297
  Targets may be outside the selected project, unresolved, or trashed; target
299
- liveness is not guaranteed by this export. Records retain no context handles.
298
+ liveness is not guaranteed by this export. A cross-project link retains its
299
+ target project ID even if the target title cannot be loaded. Records retain no
300
+ context handles.
300
301
 
301
302
  ## NetworkX conversion
302
303
 
@@ -312,6 +313,8 @@ Selected card nodes have `exported=True`. Referenced card targets lacking a
312
313
  selected record receive a minimal node containing `card_id`, core's nullable
313
314
  target title and `exported=False`. This preserves outgoing cross-project and
314
315
  unresolved connections without claiming complete metadata for those endpoints.
316
+ Graph nodes are keyed by card ID alone, so this adapter cannot distinguish
317
+ cards with the same ID in different projects (for example, after a fork).
315
318
  Non-card connections are preserved by records/DataFrames but omitted from the
316
319
  card graph. Hierarchy remains a node attribute, not a fabricated explicit edge.
317
320
  All graph data is detached; mutation has no automatic write-back.
@@ -357,17 +360,15 @@ The pandas adapter and combined `tags` table use nullable `string` columns and
357
360
  nullable `boolean` for `editable`, even when empty. Join on `project_id` and
358
361
  `card_id` to the cards table, and on `project_id` to projects.
359
362
 
360
- The normalized tag list is read from core's extracted index, in alphabetical
361
- order. `editable` is membership in core's trailing-tag-line list, read from
362
- the authoritative body; it is not a guarantee that removing that occurrence
363
- will leave the card untagged. A tag may also occur in prose. There is one
364
- indexed tag read per selected card and, for tagged cards, one editable-list
365
- read. These separate reads do not form an atomic snapshot. No Python-side
366
- Markdown parsing or extra body/content column is introduced.
363
+ The normalized tag list and `editable` flag come from the generated Card
364
+ record. `editable` means `remove_card_tag` can remove the tag from its trailing
365
+ line without leaving another occurrence in prose. Reading these fields requires
366
+ the card body. Separate reads do not form an atomic snapshot. Kit does no
367
+ Python-side Markdown parsing.
367
368
 
368
369
  `tags.list(card_id)` returns normalized names; `tags.list_editable(card_id)`
369
370
  returns trailing-line names in core's order. `tags.project_counts(project_id)`
370
- returns `ProjectTagRecord` dictionaries (`project_id`, `tag`, integer `count`),
371
+ returns `ProjectTagRecord` dictionaries (`project_id`, `tag`, integer `card_count`),
371
372
  ordered by count descending then tag ascending. `tags.cards_with_tag(project_id,
372
373
  tag)` returns `TaggedCardRecord` dictionaries (`card_id`, `title`), using
373
374
  core's case-insensitive live-card search; equal-time matches have no promised
@@ -377,84 +378,81 @@ or mutations for unknown cards raise `HolderError`.
377
378
  `tags.add(card_id, tag)` returns `TagAddResult.ADDED` or `.ALREADY_PRESENT`.
378
379
  Core lowercases a valid bare tag and adds it to the trailing tag line only if
379
380
  it does not occur anywhere in the body. `tags.remove(card_id, tag)` returns
380
- `TagRemoveResult.REMOVED`, `.NOT_PRESENT` or
381
- `.PRESENT_OUTSIDE_EDITABLE_TAG_LINE`; it never rewrites prose. `REMOVED` means
382
- the trailing occurrence was removed, not necessarily that the tag disappeared
383
- from the card. These `IntEnum` members mirror core statuses; successful changes
384
- have numeric value zero, so compare named members rather than testing truthiness.
381
+ `TagRemoveResult.REMOVED` or `.NOT_PRESENT`. A tag also present in prose raises
382
+ `HolderError` because the generated operation leaves the card unchanged. These
383
+ `IntEnum` members are Kit results; compare named members rather than testing
384
+ truthiness.
385
385
  Malformed tags raise `ValueError`; non-string arguments raise `TypeError`.
386
386
  Core owns tag grammar, extraction, durable edits and reindexing. No bulk/atomic
387
387
  mutation contract is implied, and exported records/tables do not
388
388
  refresh automatically after a mutation. Live Card properties read the changes.
389
389
 
390
- Core's editable-list read currently substitutes an empty body if a card file
391
- is missing. The flag can therefore be false in that situation despite an indexed
392
- tag remaining present. By contrast, `include_content=True` still uses complete
393
- card extraction, whose missing-body failure propagates. Native read failures
394
- propagate without returning partial exports; closed contexts raise `RuntimeError`.
390
+ Missing card bodies cause tag reads and exports to fail with `HolderError`.
391
+ Native read failures propagate without returning partial exports; closed
392
+ contexts raise `RuntimeError`.
395
393
 
396
394
  ## Milestone records and operations
397
395
 
398
- `context.milestones.list(card_id)` returns detached `MilestoneRecord` dictionaries
399
- in core's ascending `start_at` order. `MILESTONE_RECORD_FIELDS` defines their schema:
396
+ Milestones have the contract's shape: labelled dates. Each date has a `role`
397
+ (what it is for, such as `"start"` or `"deadline"`) and exactly one of `date`, a
398
+ calendar day `YYYY-MM-DD` with no time zone, or `datetime`, an instant in RFC 3339
399
+ with an offset and whole seconds. A milestone may have no dates.
400
+
401
+ `context.milestones.list(project_id, card_id)` returns detached `MilestoneRecord`
402
+ dictionaries. `MILESTONE_RECORD_FIELDS` defines their schema:
400
403
 
401
404
  | Field | Python type | Meaning |
402
405
  |---|---|---|
403
406
  | `milestone_id` | `str` | Core-generated milestone UUID |
407
+ | `project_id` | `str` | The project of the owning card |
404
408
  | `card_id` | `str` | Owning card identifier |
405
- | `start_at` | `int` | Start time in Unix seconds |
406
- | `end_at` | `int \| None` | Optional end time; None denotes a point |
407
- | `all_day` | `bool` | Core's all-day flag; no Python timezone/date normalization |
409
+ | `dates` | `list[MilestoneDateRecord]` | The labelled dates, in the order given |
408
410
  | `kind` | `str \| None` | Optional kind, including custom values |
409
411
  | `description` | `str \| None` | Optional description |
410
412
  | `created_at` | `int` | Core creation time in Unix seconds |
411
413
  | `updated_at` | `int` | Core last-update time in Unix seconds |
412
414
 
413
415
  `milestones.to_records(project_id=None)` selects live cards and reads their
414
- milestones once per card. It returns `ProjectMilestoneRecord` dictionaries adding
415
- `project_id` and `card_title` from the selected card metadata. Field order is
416
- `PROJECT_MILESTONE_RECORD_FIELDS`: `project_id`, the milestone fields above, then
417
- `card_title`. `milestones.in_range(project_id, from_at, to_at)` returns the same
418
- contract, with the project ID supplied by the query and nullable `card_title`
419
- resolved by core. It uses core's bulk calendar query and excludes trashed cards.
420
- Unknown projects and empty selections yield empty results.
421
-
422
- Range selection is `from_at <= start_at <= to_at`, **not interval overlap**.
423
- A span beginning before the range is omitted even if it ends inside it. Reversed
424
- query bounds return an empty list. Equal-start ordering is unspecified. Card-local
425
- lists are start-ordered; whole-context exports preserve selected card order, not
426
- a globally sorted calendar. Sort detached data explicitly when needed.
416
+ milestones once per card, adding the card's title as `card_title`
417
+ (`PROJECT_MILESTONE_RECORD_FIELDS`). Unknown projects and empty selections yield
418
+ empty results.
419
+
420
+ `milestones.calendar(project_id, first_day, last_day, *, time_zone=None)` returns
421
+ the same `ProjectMilestoneRecord` values for milestones with a date in the days
422
+ from `first_day` to `last_day` (a `date` or `YYYY-MM-DD`) in `time_zone`, such as
423
+ `"Europe/London"`, or this device's zone when omitted. A day date is in it when
424
+ its day is in those days, whatever the zone; an instant is in it when it falls in
425
+ those days in the zone. Core works out the window, across daylight-saving
426
+ changes. Trashed cards are left out; reversed days give an empty list; an unknown
427
+ zone or a malformed day raises `ValueError` and an unknown project `HolderError`.
427
428
 
428
429
  `milestones.to_dataframe()` and the combined `milestones` table preserve that
429
- extended schema. IDs/text use nullable strings, `all_day` uses nullable `boolean`,
430
- and all four time columns use `datetime64[ns, UTC]`; `end_at=None` becomes `NaT`.
431
- Empty tables keep the same columns/dtypes. Join on `project_id` and `card_id` to
432
- cards. Timestamps outside pandas' nanosecond range can remain valid core/record
433
- values but cannot be represented by this DataFrame contract; conversion errors
434
- propagate rather than silently clipping or changing precision.
430
+ schema. IDs and text use nullable strings, `dates` stays a Python list per row
431
+ (an `object` column), and `created_at`/`updated_at` use `datetime64[ns, UTC]`.
432
+ Empty tables keep the same columns and dtypes. Join on `project_id` and `card_id`
433
+ to cards.
435
434
 
436
435
  ### Explicit mutations and partial updates
437
436
 
438
- `milestones.add(card_id, start_at, *, end_at=None, all_day=False, kind=None,
439
- description=None)` returns the **full updated card milestone list**, not just the
440
- new row. Each addition gets a new core ID; repeating a successful add creates
441
- another milestone. Empty kind/description strings on add are normalized to None
442
- by core. `milestones.remove(card_id, milestone_id)` returns None; absent IDs and
443
- IDs owned by another card are no-ops, but an unknown card raises `HolderError`.
444
-
445
- `milestones.update(project_id, card_id, milestone_id, changes)` accepts a typed
446
- `MilestoneUpdate` dictionary and returns the single updated `MilestoneRecord`:
447
-
448
- - Absent fields stay unchanged; an empty dictionary is a no-op for an existing,
449
- correctly owned live milestone.
450
- - `end_at`, `kind` and `description` accept None to clear their value.
451
- - `start_at` and `all_day` cannot be cleared; None raises `ValueError`.
452
- - Unknown keys raise `ValueError`. Times must be signed 64-bit integer Unix
453
- seconds, not bool/float; flags must be bool; text must be str or None. Invalid
454
- Python field types raise `TypeError`, out-of-range integers `OverflowError`.
455
- - Core verifies the matching project/card/milestone ownership and live-card
456
- status. Mismatch raises `HolderError`. An update creating `end_at < start_at`
457
- also raises `HolderError` through the current C ABI exception translation.
437
+ `milestones.add(project_id, card_id, dates=(), *, kind=None, description=None)`
438
+ returns the new milestone. `dates` is a sequence of mappings with a `role` and one
439
+ of `date` (a `date` or `YYYY-MM-DD`) or `datetime` (an aware `datetime` or an RFC
440
+ 3339 string); Kit converts `date` and `datetime` objects to the contract's
441
+ strings. Each addition gets a new core ID. `milestones.remove(project_id, card_id,
442
+ milestone_id)` returns the card's remaining milestones; absent IDs and IDs owned
443
+ by another card change nothing, but an unknown card raises `HolderError`.
444
+
445
+ `milestones.update(project_id, card_id, milestone_id, changes)` accepts a
446
+ `MilestoneUpdate` dictionary and returns the updated `MilestoneRecord`:
447
+
448
+ - Absent fields stay unchanged; an empty dictionary changes nothing.
449
+ - `dates` replaces all of the milestone's dates; `kind` and `description` accept
450
+ None to clear them.
451
+ - Unknown keys, a date without a role or without exactly one of `date` and
452
+ `datetime`, and a naive `datetime` raise `ValueError`; wrong Python types raise
453
+ `TypeError`. Core rejects a malformed day or instant with `ValueError`.
454
+ - Core checks the project, card and milestone belong together and the card is
455
+ live; a mismatch raises `HolderError`.
458
456
 
459
457
  Core owns durable front-matter editing, index updates and Git commits; Python
460
458
  does not parse or rewrite Markdown. Exported records do not
@@ -462,17 +460,3 @@ refresh automatically. Live Card properties read current state. Valid calls on a
462
460
  Failed reads abort exports without a partial result; no export-wide snapshot,
463
461
  transaction, revision check or bulk mutation guarantee is implied.
464
462
 
465
- ### Current core limitations
466
-
467
- The public add operation does not enforce the update operation's reversed-span
468
- validation. Direct card-list/add/remove operations also do not expose the same
469
- explicit live-card ownership check as update and the calendar query; use selected
470
- live cards. Python preserves these contracts rather than duplicating domain policy.
471
-
472
- Add/remove replace index rows before attempting their durable card-file write.
473
- A missing file or another durable-write failure can therefore raise an error
474
- after index changes already occurred. Update checks/reads the file before changing
475
- the index, but none of these APIs promises an atomic multi-store transaction or
476
- automatic rollback on every failure. Do not blindly retry failed additions or
477
- infer unchanged storage from an exception. Strengthening this behavior requires
478
- an owning core change, not a Python-only transaction wrapper.