holder-kit 0.0.2__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 (99) hide show
  1. {holder_kit-0.0.2 → holder_kit-0.2.6}/.gitignore +0 -1
  2. {holder_kit-0.0.2 → holder_kit-0.2.6}/CMakeLists.txt +1 -1
  3. {holder_kit-0.0.2 → holder_kit-0.2.6}/PKG-INFO +38 -23
  4. holder_kit-0.2.6/README.md +111 -0
  5. holder_kit-0.2.6/VERSION +1 -0
  6. holder_kit-0.2.6/_build_backend/backend.py +12 -0
  7. holder_kit-0.2.6/_build_support.py +60 -0
  8. holder_kit-0.2.6/docs/building.md +128 -0
  9. {holder_kit-0.0.2 → holder_kit-0.2.6}/docs/development.md +38 -8
  10. {holder_kit-0.0.2 → holder_kit-0.2.6}/docs/packaging.md +44 -66
  11. holder_kit-0.2.6/docs/publication.md +100 -0
  12. holder_kit-0.2.6/docs/record-contracts.md +462 -0
  13. holder_kit-0.2.6/docs/storage.md +142 -0
  14. holder_kit-0.2.6/docs/walkthrough.md +247 -0
  15. holder_kit-0.2.6/docs/which_holder_python_api.png +0 -0
  16. holder_kit-0.2.6/examples/card_lifecycle.py +31 -0
  17. holder_kit-0.2.6/examples/finish_project.py +34 -0
  18. holder_kit-0.2.6/examples/make_project.py +16 -0
  19. holder_kit-0.2.6/examples/milestone_analysis.py +35 -0
  20. holder_kit-0.2.6/examples/reopen_project.py +25 -0
  21. {holder_kit-0.0.2 → holder_kit-0.2.6}/packaging/linux/debian/control +7 -1
  22. {holder_kit-0.0.2 → holder_kit-0.2.6}/packaging/linux/debian/copyright +1 -1
  23. {holder_kit-0.0.2 → holder_kit-0.2.6}/packaging/linux/debian/rules +6 -0
  24. {holder_kit-0.0.2 → holder_kit-0.2.6}/pyproject.toml +11 -3
  25. {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/check-release-distributions.py +17 -10
  26. {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/develop.py +43 -133
  27. holder_kit-0.2.6/scripts/licenses/microsoft-runtime.txt +36 -0
  28. {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/pypi_readme.py +5 -2
  29. {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/test-installed-debian.py +7 -1
  30. holder_kit-0.2.6/scripts/test-installed-wheel.py +112 -0
  31. holder_kit-0.2.6/scripts/ubuntu-package-ci.sh +23 -0
  32. {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/wheel-notices.py +5 -21
  33. {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/__init__.py +21 -9
  34. holder_kit-0.2.6/src/holderkit/_native.pyi +69 -0
  35. holder_kit-0.2.6/src/holderkit/_publication.py +168 -0
  36. holder_kit-0.2.6/src/holderkit/_storage.py +429 -0
  37. holder_kit-0.2.6/src/holderkit/card_collections.py +139 -0
  38. {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/collections.py +116 -51
  39. {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/data/__init__.py +5 -4
  40. holder_kit-0.2.6/src/holderkit/data/card.py +315 -0
  41. {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/data/connection.py +2 -0
  42. holder_kit-0.2.6/src/holderkit/data/milestone.py +127 -0
  43. holder_kit-0.2.6/src/holderkit/data/project.py +396 -0
  44. {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/data/tag.py +1 -2
  45. {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/dataframe.py +6 -2
  46. holder_kit-0.2.6/src/holderkit/project_collections.py +308 -0
  47. holder_kit-0.2.6/src/native/module.c +1747 -0
  48. holder_kit-0.2.6/tests/conftest.py +119 -0
  49. holder_kit-0.2.6/tests/test_card_batches.py +228 -0
  50. holder_kit-0.2.6/tests/test_card_collections.py +207 -0
  51. holder_kit-0.2.6/tests/test_card_movement.py +119 -0
  52. holder_kit-0.2.6/tests/test_card_navigation.py +144 -0
  53. {holder_kit-0.0.2 → holder_kit-0.2.6}/tests/test_connections.py +2 -2
  54. {holder_kit-0.0.2 → holder_kit-0.2.6}/tests/test_graph.py +4 -2
  55. {holder_kit-0.0.2 → holder_kit-0.2.6}/tests/test_holder.py +31 -18
  56. holder_kit-0.2.6/tests/test_live_cards.py +200 -0
  57. {holder_kit-0.0.2 → holder_kit-0.2.6}/tests/test_make.py +49 -87
  58. holder_kit-0.2.6/tests/test_milestones.py +262 -0
  59. {holder_kit-0.0.2 → holder_kit-0.2.6}/tests/test_pandas.py +16 -9
  60. holder_kit-0.2.6/tests/test_projects.py +807 -0
  61. {holder_kit-0.0.2 → holder_kit-0.2.6}/tests/test_tags.py +16 -15
  62. holder_kit-0.0.2/.github/actions/core-sdk/action.yml +0 -21
  63. holder_kit-0.0.2/.github/workflows/ci.yml +0 -325
  64. holder_kit-0.0.2/.github/workflows/launchpad.yml +0 -79
  65. holder_kit-0.0.2/.github/workflows/release.yml +0 -248
  66. holder_kit-0.0.2/.github/workflows/ubuntu-packages.yml +0 -47
  67. holder_kit-0.0.2/README.md +0 -96
  68. holder_kit-0.0.2/core-source.json +0 -4
  69. holder_kit-0.0.2/docs/building.md +0 -171
  70. holder_kit-0.0.2/docs/record-contracts.md +0 -312
  71. holder_kit-0.0.2/docs/walkthrough.md +0 -125
  72. holder_kit-0.0.2/examples/card_lifecycle.py +0 -34
  73. holder_kit-0.0.2/examples/milestone_analysis.py +0 -31
  74. holder_kit-0.0.2/release-core.json +0 -5
  75. holder_kit-0.0.2/scripts/configure-holder-ppa.sh +0 -14
  76. holder_kit-0.0.2/scripts/core-sdk.py +0 -17
  77. holder_kit-0.0.2/scripts/prepare-debian-source.py +0 -54
  78. holder_kit-0.0.2/scripts/test-installed-wheel.py +0 -48
  79. holder_kit-0.0.2/scripts/ubuntu-package-ci.sh +0 -40
  80. holder_kit-0.0.2/src/holderkit/_native.pyi +0 -52
  81. holder_kit-0.0.2/src/holderkit/data/card.py +0 -166
  82. holder_kit-0.0.2/src/holderkit/data/milestone.py +0 -71
  83. holder_kit-0.0.2/src/holderkit/data/project.py +0 -96
  84. holder_kit-0.0.2/src/native/module.c +0 -868
  85. holder_kit-0.0.2/tests/test_milestones.py +0 -234
  86. {holder_kit-0.0.2 → holder_kit-0.2.6}/LICENSE +0 -0
  87. {holder_kit-0.0.2 → holder_kit-0.2.6}/docs/workflow.png +0 -0
  88. {holder_kit-0.0.2 → holder_kit-0.2.6}/examples/detached_records.py +0 -0
  89. {holder_kit-0.0.2 → holder_kit-0.2.6}/examples/graph_analysis.py +0 -0
  90. {holder_kit-0.0.2 → holder_kit-0.2.6}/examples/pandas_analysis.py +0 -0
  91. {holder_kit-0.0.2 → holder_kit-0.2.6}/examples/tag_analysis.py +0 -0
  92. {holder_kit-0.0.2 → holder_kit-0.2.6}/make.sh +0 -0
  93. {holder_kit-0.0.2 → holder_kit-0.2.6}/packaging/linux/debian/changelog +0 -0
  94. {holder_kit-0.0.2 → holder_kit-0.2.6}/packaging/linux/debian/source/format +0 -0
  95. {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/__init__.py +0 -0
  96. {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/repair-linux-wheel.py +0 -0
  97. {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/system-core-build-info.py +0 -0
  98. {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/graph.py +0 -0
  99. {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/py.typed +0 -0
@@ -4,7 +4,6 @@
4
4
  **/__pycache__/
5
5
  *.egg-info/
6
6
  *.so
7
- /.core-sdk/
8
7
  /out/
9
8
  /dist/
10
9
  /debian/
@@ -45,7 +45,7 @@ elseif(HOLDER_KIT_CORE_SOURCE)
45
45
  set(holder_schema "${HOLDER_KIT_CORE_SOURCE}/schema/schema.sql")
46
46
  else()
47
47
  if(NOT EXISTS "${HOLDER_CORE_SDK}/libholder-manifest.json")
48
- message(FATAL_ERROR "Missing core SDK. Run scripts/core-sdk.py resolve and fetch, then set HOLDER_CORE_SDK. No automatic source fallback is available.")
48
+ message(FATAL_ERROR "Missing core SDK. Set HOLDER_CORE_SDK to a prepared core SDK, or set HOLDER_KIT_CORE_SOURCE to build core from source (./make.sh uses ../../core).")
49
49
  endif()
50
50
  set(holder_DIR "${HOLDER_CORE_SDK}/lib/cmake/holder" CACHE PATH "Selected core CMake package" FORCE)
51
51
  find_package(holder CONFIG REQUIRED PATHS "${holder_DIR}" NO_DEFAULT_PATH)
@@ -1,9 +1,9 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: holder-kit
3
- Version: 0.0.2
3
+ Version: 0.2.6
4
4
  Summary: Holder Kit: CPython bindings for embedded libholder
5
5
  License-Expression: GPL-3.0-only
6
- Project-URL: Repository, https://github.com/HolderTeam/holder-kit
6
+ Project-URL: Repository, https://github.com/HolderTeam/holder/tree/main/python/kit
7
7
  Requires-Python: >=3.10
8
8
  Provides-Extra: test
9
9
  Requires-Dist: mypy>=1.15; extra == "test"
@@ -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-kit/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/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.
@@ -50,19 +50,32 @@ A typical workflow looks like this:
50
50
  ```python
51
51
  import holderkit
52
52
 
53
- with holderkit.open("./knowledge") as holder:
54
- project = holder.create_project("Research")
55
-
56
- card = holder.create_card(
57
- project.project_id,
53
+ with holderkit.create("Research") as project:
54
+ card = project.create_card(
58
55
  "Interesting question",
59
56
  "Something worth investigating.",
60
57
  )
61
58
 
62
- print(card.title)
59
+ print(project.cards.to_records(include_content=True))
63
60
  ```
64
61
 
65
- Follow the [walkthrough](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/walkthrough.md) to create connected cards, add tags
62
+ Or clone an existing Holder project and explore its cards:
63
+
64
+ ```python
65
+ with holderkit.clone("git@example.org:research.git") as project:
66
+ for card in project.cards.to_records(include_content=True):
67
+ print(card["title"], card["content"])
68
+ ```
69
+
70
+ Replace the example URL with your project's Git remote. Holder Kit chooses
71
+ local storage automatically. These examples need Git installed.
72
+
73
+ When your experiment is ready, publish it while the project is open with
74
+ `project.push(remote_url="git@example.org:research.git", branch="experiments/results")`.
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/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/publication.md).
77
+
78
+ Follow the [walkthrough](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/walkthrough.md) to create connected cards, add tags
66
79
  and milestones, and analyse detached records with pandas and NetworkX.
67
80
 
68
81
  ## Installation
@@ -71,7 +84,7 @@ Holder Kit is currently in early development.
71
84
 
72
85
  The Python distribution is named `holder-kit` and the import package is `holderkit`.
73
86
 
74
- See [Building Holder Kit](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/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.
75
88
 
76
89
  Ubuntu packages are also available as `python3-holder-kit` for supported Holder package repositories.
77
90
 
@@ -82,11 +95,10 @@ the Python process. This makes it suitable for scripts, notebooks, data analysis
82
95
  and applications that want to embed Holder functionality.
83
96
 
84
97
  To control a running Holder installation through the Framework API, use
85
- [holder-python](https://github.com/HolderTeam/holder-python).
98
+ [holder-python](https://github.com/HolderTeam/holder/tree/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/holder).
86
99
 
87
- Holder Kit is versioned independently from the
88
- [Holder Framework](https://github.com/HolderTeam/holder-framework) and
89
- [core library](https://github.com/HolderTeam/holder-core).
100
+ Holder Kit is part of [Holder](https://github.com/HolderTeam/holder) and is
101
+ released with it, at the same version.
90
102
 
91
103
  ## Examples
92
104
 
@@ -97,17 +109,20 @@ The repository includes examples covering:
97
109
  - pandas analysis;
98
110
  - connection graphs;
99
111
  - tag analysis;
100
- - milestone and calendar analysis.
112
+ - milestone and calendar analysis;
113
+ - creating projects, retaining local edits and explicitly finishing an experiment.
101
114
 
102
- See the [`examples/`](https://github.com/HolderTeam/holder-kit/tree/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/examples) directory.
115
+ See the [`examples/`](https://github.com/HolderTeam/holder/tree/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/examples) directory.
103
116
 
104
117
  ## Documentation
105
118
 
106
- - [Walkthrough](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/walkthrough.md)
107
- - [Detached record contracts](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/record-contracts.md)
108
- - [Building from source](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/building.md)
109
- - [Development](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/development.md)
110
- - [Packaging](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/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)
111
126
 
112
127
  ## Status
113
128
 
@@ -115,4 +130,4 @@ Holder Kit is under active development. The current API covers projects, cards,
115
130
 
116
131
  ## Licence
117
132
 
118
- See [LICENSE](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/LICENSE).
133
+ See [LICENSE](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/LICENSE).
@@ -0,0 +1,111 @@
1
+ # Holder Kit
2
+
3
+ **Analyse, transform and import Holder data with Python.**
4
+
5
+ Holder Kit gives Python programs direct access to Holder projects, cards, connections, tags and milestones.
6
+
7
+ Typical uses include:
8
+
9
+ - **Data analysis** — load Holder data into pandas and explore it with familiar Python tools.
10
+ - **Bulk import and transformation** — create or modify large collections of cards programmatically.
11
+ - **Machine learning** — extract Holder content for classification, clustering, embeddings, ranking and other experiments.
12
+ - **Graph analysis** — export explicit connections between cards to NetworkX.
13
+ - **Dataset and corpus preparation** — turn a Holder knowledge base into structured Python records for further processing.
14
+ - **Offline automation** — perform maintenance, migration and batch operations without running the Holder daemon.
15
+
16
+ The base package exposes ordinary Python records and has no data-science dependencies. pandas and NetworkX integrations are available as optional extras.
17
+
18
+ A typical workflow looks like this:
19
+
20
+ ![AI generated image](https://raw.githubusercontent.com/HolderTeam/holder/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/workflow.png)
21
+
22
+ 1. You make a new project, or clone an existing one.
23
+ 2. You do work and analysis.
24
+ 3. You push your experiment, or discard it.
25
+
26
+ ## A first example
27
+
28
+ ```python
29
+ import holderkit
30
+
31
+ with holderkit.create("Research") as project:
32
+ card = project.create_card(
33
+ "Interesting question",
34
+ "Something worth investigating.",
35
+ )
36
+
37
+ print(project.cards.to_records(include_content=True))
38
+ ```
39
+
40
+ Or clone an existing Holder project and explore its cards:
41
+
42
+ ```python
43
+ with holderkit.clone("git@example.org:research.git") as project:
44
+ for card in project.cards.to_records(include_content=True):
45
+ print(card["title"], card["content"])
46
+ ```
47
+
48
+ Replace the example URL with your project's Git remote. Holder Kit chooses
49
+ local storage automatically. These examples need Git installed.
50
+
51
+ When your experiment is ready, publish it while the project is open with
52
+ `project.push(remote_url="git@example.org:research.git", branch="experiments/results")`.
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/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/publication.md).
55
+
56
+ Follow the [walkthrough](https://github.com/HolderTeam/holder/blob/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/docs/walkthrough.md) to create connected cards, add tags
57
+ and milestones, and analyse detached records with pandas and NetworkX.
58
+
59
+ ## Installation
60
+
61
+ Holder Kit is currently in early development.
62
+
63
+ The Python distribution is named `holder-kit` and the import package is `holderkit`.
64
+
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
+
67
+ Ubuntu packages are also available as `python3-holder-kit` for supported Holder package repositories.
68
+
69
+ ## How Holder Kit fits into Holder
70
+
71
+ Holder Kit is a Python binding over `libholder`, running Holder directly inside
72
+ the Python process. This makes it suitable for scripts, notebooks, data analysis
73
+ and applications that want to embed Holder functionality.
74
+
75
+ To control a running Holder installation through the Framework API, use
76
+ [holder-python](https://github.com/HolderTeam/holder/tree/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/holder).
77
+
78
+ Holder Kit is part of [Holder](https://github.com/HolderTeam/holder) and is
79
+ released with it, at the same version.
80
+
81
+ ## Examples
82
+
83
+ The repository includes examples covering:
84
+
85
+ - card creation and lifecycle;
86
+ - detached Python records;
87
+ - pandas analysis;
88
+ - connection graphs;
89
+ - tag analysis;
90
+ - milestone and calendar analysis;
91
+ - creating projects, retaining local edits and explicitly finishing an experiment.
92
+
93
+ See the [`examples/`](https://github.com/HolderTeam/holder/tree/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/kit/examples) directory.
94
+
95
+ ## Documentation
96
+
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
+
105
+ ## Status
106
+
107
+ Holder Kit is under active development. The current API covers projects, cards, explicit connections, tags, milestones and analytical exports, with more of the `libholder` API to follow.
108
+
109
+ ## Licence
110
+
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)}
@@ -0,0 +1,128 @@
1
+ # Building Holder Kit
2
+
3
+ This guide covers building and installing a checkout. See
4
+ [Development](development.md) for tests and code changes, and
5
+ [Packaging](packaging.md) for wheels and Ubuntu packages.
6
+
7
+ ## Prerequisites
8
+
9
+ Holder Kit requires Python 3.10 or newer with virtualenv support and development
10
+ headers, CMake 3.22 or newer, and C/C++ compilers. Linux, macOS and BSD builds
11
+ also need `pkg-config` and core's native development dependencies. Use core's
12
+ README (`../../core/README.md`) and CMake configuration for that dependency list.
13
+
14
+ On macOS, install Xcode Command Line Tools and the required Homebrew packages.
15
+ The developer script discovers Homebrew and its OpenSSL prefixes; set
16
+ `CMAKE_PREFIX_PATH` if CMake cannot find a library. On BSD, use the platform's
17
+ ports or package manager. The script does not install system packages.
18
+
19
+ ## Build with core source
20
+
21
+ `make.sh` is the Bash entry point on Linux, macOS and BSD. It runs
22
+ `scripts/develop.py`, creates or reuses `.venv`, and installs Holder Kit as an
23
+ editable package with all test dependencies, including pandas and NetworkX.
24
+
25
+ From `python/kit/` in a checkout of the holder repository:
26
+
27
+ ```sh
28
+ ./make.sh setup
29
+ ```
30
+
31
+ This builds core from source in the same checkout (`../../core`), so Kit is
32
+ always built against the core beside it. Set `HOLDER_KIT_CORE_SOURCE` to build
33
+ against a different core source directory. Builds leave the checkout on its
34
+ current branch and revision. They print core's revision and working-tree status,
35
+ and record them in `out/make/core-source.json`.
36
+
37
+ Before creating a virtualenv or installing Python packages, the source workflow
38
+ checks tools, Python headers and core's CMake prerequisites with
39
+ `BUILD_TESTING=OFF`. If configuration fails, fix the reported prerequisite and
40
+ rerun the command.
41
+
42
+ The script uses its own directory and invokes the virtualenv directly; shell
43
+ activation is optional.
44
+
45
+ For a manual build without the developer script, create a virtualenv and pass
46
+ the core source path explicitly:
47
+
48
+ ```sh
49
+ python3 -m venv .venv
50
+ . .venv/bin/activate
51
+ python -m pip install -e . \
52
+ --config-settings=cmake.define.HOLDER_KIT_CORE_SOURCE="$PWD/../../core"
53
+ ```
54
+
55
+ Direct pip/CMake builds require an explicit core selection; the default above
56
+ belongs to the developer script.
57
+
58
+ ## Build with a core SDK
59
+
60
+ SDK builds use a prebuilt core library instead of building core: a Holder
61
+ release's core SDK, or one that a CI run's `Core / SDK` workflow built. Fetch
62
+ and verify it with core's `scripts/core-sdk.py`, then point `HOLDER_CORE_SDK`
63
+ at the prepared SDK directory (the one containing `libholder-manifest.json`):
64
+
65
+ ```sh
66
+ HOLDER_CORE_SDK=/path/to/sdk ./make.sh --sdk setup
67
+ ```
68
+
69
+ `HOLDER_CORE_SDK` selects the SDK workflow unless `HOLDER_KIT_CORE_SOURCE` is
70
+ set. Combining `--sdk` with an explicit source path is rejected, and `--sdk`
71
+ without a prepared SDK stops before creating a virtualenv. For manual builds on
72
+ Linux or macOS, set `HOLDER_CORE_SDK` and `SKBUILD_CMAKE_BUILD_TYPE` (matching
73
+ the SDK's configuration) and run `python -m pip install -e .`.
74
+
75
+ Linux and macOS SDK builds still need core's native development dependencies.
76
+ The Linux SDK uses the Ubuntu 24.04 dependency ABI. Mixing it with another
77
+ distribution's C++ dependency ABI can cause import failures; use a source build
78
+ or the series-specific [Ubuntu package](packaging.md#ubuntu-packages).
79
+
80
+ ### Windows
81
+
82
+ Use an MSVC developer environment and a supported Python. Run the Python helper
83
+ directly if Bash is unavailable:
84
+
85
+ ```powershell
86
+ $env:HOLDER_CORE_SDK = "C:\path\to\sdk"
87
+ python scripts/develop.py --sdk setup
88
+ ```
89
+
90
+ The helper configures the SDK's bundled vcpkg toolchain and prebuilt dependencies.
91
+ For direct pip/CMake builds, set `HOLDER_CORE_SDK` and pass these CMake
92
+ definitions:
93
+
94
+ | Definition | Value |
95
+ | --- | --- |
96
+ | `CMAKE_TOOLCHAIN_FILE` | `<sdk>/vcpkg/scripts/buildsystems/vcpkg.cmake` |
97
+ | `VCPKG_INSTALLED_DIR` | `<sdk>/vcpkg/installed` |
98
+ | `VCPKG_TARGET_TRIPLET` | `x64-windows` |
99
+ | `VCPKG_MANIFEST_MODE` | `OFF` |
100
+ | `VCPKG_APPLOCAL_DEPS` | `OFF` |
101
+
102
+ Holder Kit does not bootstrap vcpkg or compile the SDK's dependencies. Windows
103
+ SDKs without bundled development dependencies are rejected.
104
+
105
+ ## Build settings and output
106
+
107
+ Build commands accept `Debug`, `Release`, `RelWithDebInfo` or `MinSizeRel`:
108
+
109
+ ```sh
110
+ ./make.sh setup Debug
111
+ ./make.sh --sdk setup Release
112
+ ```
113
+
114
+ The default is `RelWithDebInfo`. Source and SDK builds, and each build type, have
115
+ separate native directories under `build/make`.
116
+
117
+ | Environment variable | Purpose |
118
+ | --- | --- |
119
+ | `HOLDER_KIT` | Bootstrap Python interpreter; otherwise reuse the selected venv or use `python3` |
120
+ | `HOLDER_KIT_VENV` | Virtualenv path; defaults to `.venv` |
121
+ | `HOLDER_KIT_CORE_SOURCE` | Core source directory; defaults to `../../core` |
122
+ | `HOLDER_CORE_SDK` | Prepared SDK directory containing `libholder-manifest.json` |
123
+ | `BUILD_TYPE` | Default native build type |
124
+ | `CMAKE_BUILD_PARALLEL_LEVEL` | Build parallelism limit |
125
+
126
+ `./make.sh clean` removes only `build/make` and `out/make`. It retains `.venv`
127
+ and other build directories. Run
128
+ `./make.sh --help` for the complete command reference.
@@ -13,14 +13,18 @@ Holder Kit embeds libholder in the Python process. It does not talk to a running
13
13
  | `src/native/module.c` | CPython extension, exposed as `holderkit._native` |
14
14
  | `src/holderkit/` | Public Python API, typed records and optional adapters |
15
15
  | `tests/` | API, adapter and developer-script tests |
16
- | `examples/` | Runnable examples using temporary Holder data |
16
+ | `examples/` | Runnable examples for project and analysis APIs |
17
17
  | `scripts/develop.py` | Developer environment and build commands |
18
18
  | `CMakeLists.txt` | Native extension build and resource installation |
19
19
 
20
- Keep reusable storage and domain behavior in holder-core. The Python layer calls
21
- core's semantic operations, including tag and milestone edits, rather than
22
- reimplementing them by parsing or rewriting card files. Core also owns SDK
23
- selection and validation; `scripts/core-sdk.py` delegates to its shared tool.
20
+ Keep reusable storage and domain behavior in core (`../../core`). The Python
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
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.
24
28
 
25
29
  The package ships the schema from the selected core source or SDK as
26
30
  `holderkit/_schema.sql`. Installed packages must work without a source checkout.
@@ -59,18 +63,34 @@ directory or contact a running daemon. Follow that pattern for new tests.
59
63
  ./make.sh examples graph
60
64
  ./make.sh examples tags
61
65
  ./make.sh examples milestones
66
+ ./make.sh examples make_project
67
+ ./make.sh examples finish_project
62
68
  ```
63
69
 
64
- Examples use temporary data directories and clean up on exit. They can also be
65
- run directly with the development environment's Python. The pandas, tag and
70
+ `make_project` uses automatic storage and keeps the project it creates. The other
71
+ examples use temporary data directories and clean up on exit. Examples can also
72
+ be run directly with the development environment's Python. The pandas, tag and
66
73
  milestone analysis examples require the pandas extra; graph analysis uses both
67
74
  pandas and graph extras. Ordinary base-package use imports neither dependency.
68
75
 
76
+ The workspace tests start disposable Git servers on loopback to test real remote
77
+ clones. They require Git and permission to bind/connect local sockets. Fixtures
78
+ use temporary contexts and bare repositories, never a live Holder project.
79
+
69
80
  ## Public API contracts
70
81
 
71
82
  `Context` owns the native `holder_context`; close it explicitly or use a context
72
83
  manager. Native runtime failures raise `holderkit.HolderError`, and invalid core
73
- arguments raise `ValueError`. `Project` and `Card` are frozen, slotted dataclasses.
84
+ arguments raise `ValueError`. `Project` is a live interface to one project;
85
+ its properties read current state. `Card` is also live and keeps its owning
86
+ Project through `card.project`. Use `Project.to_record()` and `Card.to_record()`
87
+ for detached values. Card identity is stable; reads and edits require an open owner. Managed Projects own
88
+ their context; Projects obtained from a Context borrow it and close independently.
89
+
90
+ Card-scoped tags, connections and milestones are adapters over the existing
91
+ Project and collection operations. Keep ownership/lifetime checks on live handles,
92
+ and reuse Core semantics and detached record schemas. Single-card exports must
93
+ not scan an entire project to select their source.
74
94
 
75
95
  Records, DataFrames and graphs are detached data. They remain usable after the
76
96
  context closes, and editing them does not write back to Holder. Card exports
@@ -83,6 +103,11 @@ mutation limits. Consult those contracts when changing the API, and keep them
83
103
  and the examples consistent with the code. Test empty exports, optional
84
104
  dependencies, ownership checks and failure behavior where relevant.
85
105
 
106
+ ## Clone build requirements
107
+
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.
110
+
86
111
  ## Native sanitizers
87
112
 
88
113
  For native memory-safety work, use a separate pip/CMake build with
@@ -126,3 +151,8 @@ is `HolderTeam/holder-kit`. When updating an older environment, uninstall the
126
151
  former `holder` distribution and replace `import holder` with `import holderkit`.
127
152
  Dependency declarations use `holder-kit`, `holder-kit[pandas]` or
128
153
  `holder-kit[graph]`. There is no compatibility import shim.
154
+
155
+ ## Card batches
156
+
157
+ `project.cards(...)` batches, filtered or not, page through Core's generated
158
+ `list_cards` operation, which Kit builds against from the same commit.