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.
- {holder_kit-0.0.2 → holder_kit-0.2.6}/.gitignore +0 -1
- {holder_kit-0.0.2 → holder_kit-0.2.6}/CMakeLists.txt +1 -1
- {holder_kit-0.0.2 → holder_kit-0.2.6}/PKG-INFO +38 -23
- holder_kit-0.2.6/README.md +111 -0
- holder_kit-0.2.6/VERSION +1 -0
- holder_kit-0.2.6/_build_backend/backend.py +12 -0
- holder_kit-0.2.6/_build_support.py +60 -0
- holder_kit-0.2.6/docs/building.md +128 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/docs/development.md +38 -8
- {holder_kit-0.0.2 → holder_kit-0.2.6}/docs/packaging.md +44 -66
- holder_kit-0.2.6/docs/publication.md +100 -0
- holder_kit-0.2.6/docs/record-contracts.md +462 -0
- holder_kit-0.2.6/docs/storage.md +142 -0
- holder_kit-0.2.6/docs/walkthrough.md +247 -0
- holder_kit-0.2.6/docs/which_holder_python_api.png +0 -0
- holder_kit-0.2.6/examples/card_lifecycle.py +31 -0
- holder_kit-0.2.6/examples/finish_project.py +34 -0
- holder_kit-0.2.6/examples/make_project.py +16 -0
- holder_kit-0.2.6/examples/milestone_analysis.py +35 -0
- holder_kit-0.2.6/examples/reopen_project.py +25 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/packaging/linux/debian/control +7 -1
- {holder_kit-0.0.2 → holder_kit-0.2.6}/packaging/linux/debian/copyright +1 -1
- {holder_kit-0.0.2 → holder_kit-0.2.6}/packaging/linux/debian/rules +6 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/pyproject.toml +11 -3
- {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/check-release-distributions.py +17 -10
- {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/develop.py +43 -133
- holder_kit-0.2.6/scripts/licenses/microsoft-runtime.txt +36 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/pypi_readme.py +5 -2
- {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/test-installed-debian.py +7 -1
- holder_kit-0.2.6/scripts/test-installed-wheel.py +112 -0
- holder_kit-0.2.6/scripts/ubuntu-package-ci.sh +23 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/wheel-notices.py +5 -21
- {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/__init__.py +21 -9
- holder_kit-0.2.6/src/holderkit/_native.pyi +69 -0
- holder_kit-0.2.6/src/holderkit/_publication.py +168 -0
- holder_kit-0.2.6/src/holderkit/_storage.py +429 -0
- holder_kit-0.2.6/src/holderkit/card_collections.py +139 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/collections.py +116 -51
- {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/data/__init__.py +5 -4
- holder_kit-0.2.6/src/holderkit/data/card.py +315 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/data/connection.py +2 -0
- holder_kit-0.2.6/src/holderkit/data/milestone.py +127 -0
- holder_kit-0.2.6/src/holderkit/data/project.py +396 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/data/tag.py +1 -2
- {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/dataframe.py +6 -2
- holder_kit-0.2.6/src/holderkit/project_collections.py +308 -0
- holder_kit-0.2.6/src/native/module.c +1747 -0
- holder_kit-0.2.6/tests/conftest.py +119 -0
- holder_kit-0.2.6/tests/test_card_batches.py +228 -0
- holder_kit-0.2.6/tests/test_card_collections.py +207 -0
- holder_kit-0.2.6/tests/test_card_movement.py +119 -0
- holder_kit-0.2.6/tests/test_card_navigation.py +144 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/tests/test_connections.py +2 -2
- {holder_kit-0.0.2 → holder_kit-0.2.6}/tests/test_graph.py +4 -2
- {holder_kit-0.0.2 → holder_kit-0.2.6}/tests/test_holder.py +31 -18
- holder_kit-0.2.6/tests/test_live_cards.py +200 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/tests/test_make.py +49 -87
- holder_kit-0.2.6/tests/test_milestones.py +262 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/tests/test_pandas.py +16 -9
- holder_kit-0.2.6/tests/test_projects.py +807 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/tests/test_tags.py +16 -15
- holder_kit-0.0.2/.github/actions/core-sdk/action.yml +0 -21
- holder_kit-0.0.2/.github/workflows/ci.yml +0 -325
- holder_kit-0.0.2/.github/workflows/launchpad.yml +0 -79
- holder_kit-0.0.2/.github/workflows/release.yml +0 -248
- holder_kit-0.0.2/.github/workflows/ubuntu-packages.yml +0 -47
- holder_kit-0.0.2/README.md +0 -96
- holder_kit-0.0.2/core-source.json +0 -4
- holder_kit-0.0.2/docs/building.md +0 -171
- holder_kit-0.0.2/docs/record-contracts.md +0 -312
- holder_kit-0.0.2/docs/walkthrough.md +0 -125
- holder_kit-0.0.2/examples/card_lifecycle.py +0 -34
- holder_kit-0.0.2/examples/milestone_analysis.py +0 -31
- holder_kit-0.0.2/release-core.json +0 -5
- holder_kit-0.0.2/scripts/configure-holder-ppa.sh +0 -14
- holder_kit-0.0.2/scripts/core-sdk.py +0 -17
- holder_kit-0.0.2/scripts/prepare-debian-source.py +0 -54
- holder_kit-0.0.2/scripts/test-installed-wheel.py +0 -48
- holder_kit-0.0.2/scripts/ubuntu-package-ci.sh +0 -40
- holder_kit-0.0.2/src/holderkit/_native.pyi +0 -52
- holder_kit-0.0.2/src/holderkit/data/card.py +0 -166
- holder_kit-0.0.2/src/holderkit/data/milestone.py +0 -71
- holder_kit-0.0.2/src/holderkit/data/project.py +0 -96
- holder_kit-0.0.2/src/native/module.c +0 -868
- holder_kit-0.0.2/tests/test_milestones.py +0 -234
- {holder_kit-0.0.2 → holder_kit-0.2.6}/LICENSE +0 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/docs/workflow.png +0 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/examples/detached_records.py +0 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/examples/graph_analysis.py +0 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/examples/pandas_analysis.py +0 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/examples/tag_analysis.py +0 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/make.sh +0 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/packaging/linux/debian/changelog +0 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/packaging/linux/debian/source/format +0 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/__init__.py +0 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/repair-linux-wheel.py +0 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/scripts/system-core-build-info.py +0 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/graph.py +0 -0
- {holder_kit-0.0.2 → holder_kit-0.2.6}/src/holderkit/py.typed +0 -0
|
@@ -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.
|
|
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.
|
|
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
|
|
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
|
-

|
|
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.
|
|
54
|
-
|
|
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(
|
|
59
|
+
print(project.cards.to_records(include_content=True))
|
|
63
60
|
```
|
|
64
61
|
|
|
65
|
-
|
|
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
|
|
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
|
|
98
|
+
[holder-python](https://github.com/HolderTeam/holder/tree/b1d7991653c258cd2b15dcf2eb3fb23947c88e3d/python/holder).
|
|
86
99
|
|
|
87
|
-
Holder Kit is
|
|
88
|
-
|
|
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
|
|
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
|
|
107
|
-
- [
|
|
108
|
-
- [
|
|
109
|
-
- [
|
|
110
|
-
- [
|
|
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
|
|
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
|
+

|
|
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).
|
holder_kit-0.2.6/VERSION
ADDED
|
@@ -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
|
|
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
|
|
21
|
-
core's semantic operations, including tag and milestone edits, rather
|
|
22
|
-
reimplementing them by parsing or rewriting card files.
|
|
23
|
-
|
|
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
|
-
|
|
65
|
-
|
|
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`
|
|
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.
|