graspkit-atomic 3.4.2__tar.gz → 3.4.3__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 (50) hide show
  1. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/INSTALL.md +4 -4
  2. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/PKG-INFO +3 -3
  3. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/README.md +2 -2
  4. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/README_zh.md +2 -2
  5. graspkit_atomic-3.4.3/docs/releasing.md +201 -0
  6. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/version.py +1 -1
  7. graspkit_atomic-3.4.2/docs/releasing.md +0 -186
  8. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/.gitignore +0 -0
  9. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/LICENSE +0 -0
  10. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/build_package.py +0 -0
  11. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/pyproject.toml +0 -0
  12. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/scripts/check_release.py +0 -0
  13. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/CSFs_processor/__init__.py +0 -0
  14. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/CSFs_processor/coupling.py +0 -0
  15. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/CSFs_processor/extraction.py +0 -0
  16. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/CSFs_processor/selection.py +0 -0
  17. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/CSFs_processor/validation.py +0 -0
  18. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/__init__.py +0 -0
  19. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/__init__.py +0 -0
  20. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/file_locator.py +0 -0
  21. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/__init__.py +0 -0
  22. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/base_loader.py +0 -0
  23. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/binary_file_loader.py +0 -0
  24. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/energy_file_loader.py +0 -0
  25. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/gj_factor_loader.py +0 -0
  26. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/hyperfine_structure_loader.py +0 -0
  27. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/lsj_comp_loader.py +0 -0
  28. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/mix_coef_loader.py +0 -0
  29. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/radial_analysis_loader.py +0 -0
  30. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/radial_wavefunction_loader.py +0 -0
  31. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/transition_loader.py +0 -0
  32. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/mix_coef_writer.py +0 -0
  33. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/produced_data_writor.py +0 -0
  34. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/grasp_data_extractor/__init__.py +0 -0
  35. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/grasp_data_extractor/asfs_data_processor.py +0 -0
  36. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/grasp_data_extractor/radial_analysis.py +0 -0
  37. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/grasp_data_extractor/radial_wavefunction_processor.py +0 -0
  38. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/grasp_data_extractor/rmix_data_processor.py +0 -0
  39. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/grasp_data_extractor/transition_data_processor.py +0 -0
  40. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/py.typed +0 -0
  41. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/utils/__init__.py +0 -0
  42. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/utils/data_modules.py +0 -0
  43. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/utils/environment_config.py +0 -0
  44. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/utils/quadrupole_deformation.py +0 -0
  45. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit/utils/tool_function.py +0 -0
  46. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit_plot/__init__.py +0 -0
  47. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit_plot/fig_settings.py +0 -0
  48. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit_plot/mid_coupling.py +0 -0
  49. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit_plot/plot_functions.py +0 -0
  50. {graspkit_atomic-3.4.2 → graspkit_atomic-3.4.3}/src/graspkit_plot/radial_analysis.py +0 -0
@@ -15,12 +15,12 @@ python -m pip install graspkit-atomic
15
15
  For a fixed release:
16
16
 
17
17
  ```bash
18
- python -m pip install "graspkit-atomic==3.4.2"
18
+ python -m pip install "graspkit-atomic==3.4.3"
19
19
  ```
20
20
 
21
21
  ## Declare a project dependency
22
22
 
23
- Add `"graspkit-atomic==3.4.2"` to the existing `[project].dependencies` list in
23
+ Add `"graspkit-atomic==3.4.3"` to the existing `[project].dependencies` list in
24
24
  your own `pyproject.toml`. A minimal example:
25
25
 
26
26
  ```toml
@@ -28,7 +28,7 @@ your own `pyproject.toml`. A minimal example:
28
28
  name = "atomic-analysis"
29
29
  version = "0.1.0"
30
30
  requires-python = ">=3.14"
31
- dependencies = ["graspkit-atomic==3.4.2"]
31
+ dependencies = ["graspkit-atomic==3.4.3"]
32
32
  ```
33
33
 
34
34
  For a uv-managed project, run `uv sync` after editing `pyproject.toml`, then
@@ -47,7 +47,7 @@ requires the corresponding GRASP data files.
47
47
  To install a downloaded wheel, use its exact filename:
48
48
 
49
49
  ```bash
50
- python -m pip install /path/to/graspkit_atomic-3.4.2-py3-none-any.whl
50
+ python -m pip install /path/to/graspkit_atomic-3.4.3-py3-none-any.whl
51
51
  ```
52
52
 
53
53
  A standalone source checkout also supports `python -m pip install .`.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: graspkit-atomic
3
- Version: 3.4.2
3
+ Version: 3.4.3
4
4
  Summary: Stable data I/O, processing, and plotting for GRASP calculations
5
5
  Project-URL: Homepage, https://github.com/YenochQin/graspkit
6
6
  Project-URL: Source, https://github.com/YenochQin/graspkit
@@ -85,7 +85,7 @@ For an existing uv project using Python 3.14 or newer, run `uv add graspkit-atom
85
85
  in its directory. This records the dependency in `pyproject.toml`, updates
86
86
  `uv.lock`, and installs it in the project's `.venv`. Use `uv run python analysis.py`
87
87
  to run your own analysis script; manual environment activation is not required.
88
- To pin a particular release, use `uv add "graspkit-atomic==3.4.2"`.
88
+ To pin a particular release, use `uv add "graspkit-atomic==3.4.3"`.
89
89
 
90
90
  You can also add the dependency to an existing `pyproject.toml` manually:
91
91
 
@@ -95,7 +95,7 @@ name = "atomic-analysis"
95
95
  version = "0.1.0"
96
96
  requires-python = ">=3.14"
97
97
  dependencies = [
98
- "graspkit-atomic==3.4.2",
98
+ "graspkit-atomic==3.4.3",
99
99
  ]
100
100
  ```
101
101
 
@@ -38,7 +38,7 @@ For an existing uv project using Python 3.14 or newer, run `uv add graspkit-atom
38
38
  in its directory. This records the dependency in `pyproject.toml`, updates
39
39
  `uv.lock`, and installs it in the project's `.venv`. Use `uv run python analysis.py`
40
40
  to run your own analysis script; manual environment activation is not required.
41
- To pin a particular release, use `uv add "graspkit-atomic==3.4.2"`.
41
+ To pin a particular release, use `uv add "graspkit-atomic==3.4.3"`.
42
42
 
43
43
  You can also add the dependency to an existing `pyproject.toml` manually:
44
44
 
@@ -48,7 +48,7 @@ name = "atomic-analysis"
48
48
  version = "0.1.0"
49
49
  requires-python = ">=3.14"
50
50
  dependencies = [
51
- "graspkit-atomic==3.4.2",
51
+ "graspkit-atomic==3.4.3",
52
52
  ]
53
53
  ```
54
54
 
@@ -31,7 +31,7 @@ uv run python -c "import graspkit; print(graspkit.__version__)"
31
31
  已有 uv 项目使用 Python 3.14 或更新版本时,直接在其目录运行 `uv add graspkit-atomic`。
32
32
  该命令会将依赖写入 `pyproject.toml`,更新 `uv.lock`,并安装到项目的 `.venv` 中。
33
33
  运行自己的分析脚本时使用 `uv run python analysis.py`,无需手动激活环境。
34
- 需要固定版本时,使用 `uv add "graspkit-atomic==3.4.2"`。
34
+ 需要固定版本时,使用 `uv add "graspkit-atomic==3.4.3"`。
35
35
 
36
36
  也可以手动将依赖加入已有的 `pyproject.toml`:
37
37
 
@@ -41,7 +41,7 @@ name = "atomic-analysis"
41
41
  version = "0.1.0"
42
42
  requires-python = ">=3.14"
43
43
  dependencies = [
44
- "graspkit-atomic==3.4.2",
44
+ "graspkit-atomic==3.4.3",
45
45
  ]
46
46
  ```
47
47
 
@@ -0,0 +1,201 @@
1
+ # Preparing a graspkit-atomic release
2
+
3
+ The prepared stable version is **3.4.3**. Its single source is
4
+ `src/graspkit/version.py`; Hatchling reads it through `dynamic = ["version"]`.
5
+ The local build commands below do not upload files or create Git tags.
6
+ The separate manual publishing workflow is described near the end of this guide.
7
+
8
+ ## Local build in the paired workspace
9
+
10
+ Set up or refresh the shared environment from `graspkit-tools/` with
11
+ `uv sync --extra cpu` (`--extra gpu` on a CUDA host). Then, from `graspkit/`:
12
+
13
+ ```bash
14
+ source ../graspkit-tools/.venv/bin/activate
15
+ python build_package.py --clean
16
+ ```
17
+
18
+ The helper uses the current interpreter, builds a source archive and a wheel
19
+ from that archive, runs `twine check --strict`, checks the file manifest and
20
+ metadata, and runs a wheel smoke test. Build isolation supplies Hatchling.
21
+ It never installs tools into the runtime or copies files to the Tools repo.
22
+ The obsolete `--dev` option is removed; edit the version source deliberately.
23
+ `--clean` removes only matching graspkit-atomic archives from the selected output
24
+ folder. Unknown files cause an error instead of being deleted.
25
+
26
+ Output: `dist/graspkit_atomic-3.4.3.tar.gz` and
27
+ `dist/graspkit_atomic-3.4.3-py3-none-any.whl`. An optional `--outdir PATH` selects an
28
+ empty output folder. The shell/batch wrappers select the shared Tools Python.
29
+
30
+ Equivalent individual checks:
31
+
32
+ ```bash
33
+ python -m build
34
+ python -m twine check --strict dist/*
35
+ python scripts/check_release.py dist --smoke
36
+ python -m pytest tests/
37
+ ```
38
+
39
+ Do not reuse a directory containing artifacts from other versions. The checker
40
+ prints SHA-256 hashes and rejects mixed versions, missing metadata/licenses,
41
+ unexpected archive contents and absent typing markers. The smoke test starts
42
+ a separate interpreter from a temporary directory, loads the extracted wheel,
43
+ checks its import origin and version, selects CSFs and renders a plot. Locally,
44
+ runtime dependencies come from Tools; this is not a clean dependency-resolution
45
+ test. The CI workflow installs the wheel and dependencies on a fresh runner.
46
+
47
+ ## Files and license
48
+
49
+ The wheel contains `graspkit` and `graspkit_plot`. The source archive includes
50
+ those sources, metadata, GPLv3 text and selected installation/build docs.
51
+ Research notes, agent instructions, tests, local data and historical reports
52
+ are excluded. Full regression tests remain in the development repository.
53
+ The existing GPLv3 license is recorded as `GPL-3.0-only`.
54
+
55
+ ## Build-only CI
56
+
57
+ `.github/workflows/build-release.yml` runs by manual dispatch or by an explicit
58
+ push to a `codex/release-build-check-*` branch. It is also reusable through
59
+ `workflow_call`, so the publishing workflow builds the same commit. It builds
60
+ and checks on Linux, Windows and macOS using Python 3.14, and stores GitHub
61
+ Actions artifacts. It has no PyPI credentials, OIDC publishing permission,
62
+ publish job or tag-triggered upload. CI uses an ephemeral standalone runner;
63
+ it does not create a second runtime in this paired local workspace.
64
+ A universal wheel still relies on its dependencies supporting the target OS.
65
+ Python versions above 3.14 are permitted by metadata but not yet in this matrix.
66
+
67
+ Until the workflow reaches the default branch, start a check from the release
68
+ commit by pushing it to a dedicated branch, for example:
69
+
70
+ ```bash
71
+ git push origin HEAD:refs/heads/codex/release-build-check-20261020
72
+ ```
73
+
74
+ Choose a fresh suffix for a separate run of an unchanged commit. Normal
75
+ development-branch pushes and tags do not trigger this workflow. Once the
76
+ workflow is on the default branch, the Actions page also offers **Run workflow**
77
+ with a branch selector. Review all three platform jobs before using the artifacts.
78
+
79
+ ## Before a later publication
80
+
81
+ 1. Review the exact source commit and release changes; rerun the workflow on it.
82
+ 2. Confirm PyPI ownership/availability of `graspkit-atomic`, and that version 3.4.3
83
+ has not already been published. A missing public project page alone does
84
+ not prove that a name is available.
85
+ 3. Inspect the actual archives and hashes. Publishing makes their contents
86
+ public even if the Git repository remains private. Repository URLs in the
87
+ metadata require access to that repository; provide accessible public docs
88
+ or change visibility deliberately if external users need them.
89
+ 4. Test installation from TestPyPI only when an upload is explicitly authorized.
90
+ 5. Configure the Trusted Publisher described below and run the manual
91
+ publishing workflow only when the upload is authorized.
92
+ 6. Tag the approved commit and record the version/release notes. A later commit
93
+ request also covers the parent gitlink update; this preparation creates no tag.
94
+
95
+ References: [PyPA packaging](https://packaging.python.org/en/latest/tutorials/packaging-projects/),
96
+ [Trusted Publishing](https://docs.pypi.org/trusted-publishers/).
97
+
98
+ ## Manual publishing to PyPI and GitHub
99
+
100
+ `.github/workflows/publish.yml` is named **Publish packages** in GitHub Actions.
101
+ It runs only through **Run workflow**, from `main`. Pushing commits, tags, or
102
+ completing a build does not start a publication. Its inputs are:
103
+
104
+ | Input | Default | Purpose |
105
+ | --- | --- | --- |
106
+ | `version` | Required | Exact source version, currently `3.4.3`. |
107
+ | `publish_pypi` | Off | Upload the validated packages to PyPI. |
108
+ | `github_release` | Off | Create a GitHub Release using the same packages. |
109
+ | `draft` | On | Keep the GitHub Release as a draft; turn off only for formal publication. |
110
+
111
+ Open **Actions → Publish packages → Run workflow**, select `main`, enter the
112
+ source version, and select the destinations you intend to use:
113
+
114
+ | PyPI | GitHub Release | Result |
115
+ | --- | --- | --- |
116
+ | Off | Off | Build and validate only; no publication. |
117
+ | On | Off | Build, validate and upload to PyPI. |
118
+ | Off | On | Build, validate and create a GitHub Release (draft by default). |
119
+ | On | On | Build and validate once, then upload the same files to both destinations. |
120
+
121
+ A prior dry run is optional. No separate workflow, run ID or tag input is
122
+ needed. The GitHub tag is derived as `v{version}`, for example `v3.4.3`.
123
+ The `draft` option has no effect when `github_release` is off.
124
+
125
+ ### One build, two independent destinations
126
+
127
+ Preflight checks the requested version against the source before the existing
128
+ Linux/Windows/macOS build matrix runs. The assembler checks package names,
129
+ filename/metadata versions and Python/platform tags across the full matrix.
130
+ It retains one Linux source archive, plus one universal wheel for GraspKit or
131
+ three native wheels for rCSFs. The canonical files are stored in the
132
+ **pypi-distributions** Actions artifact with SHA-256 hashes in the job summary.
133
+
134
+ Both upload jobs depend directly on the successful `prepare` job. They each
135
+ consume that same artifact and do not rebuild. Neither upload job depends on
136
+ the other: a PyPI failure does not block GitHub Release creation, and vice versa.
137
+ If an upload fails before creating a Release or accepting files, retrying that
138
+ failed job reuses the run's existing validated artifact. Resolve any existing
139
+ file/Release conflict before retrying; successful uploads are not overwritten.
140
+ The workflow has no rollback across services; inspect each job's result.
141
+ The concurrency group serializes runs of this publishing workflow.
142
+
143
+ A dry run (both destination options off) does not exercise PyPI authorization.
144
+ PyPI uploads only work for filenames that have not already been used. For a
145
+ new release of modified package contents, update the source version and enter
146
+ that version in the workflow; do not try to overwrite an existing release.
147
+
148
+ ### GitHub Release behavior
149
+
150
+ The Release job automatically reads this run's ID, attempt and source commit
151
+ from GitHub. It confirms that preflight, all three builds and preparation have
152
+ succeeded; it does not require the whole workflow or the PyPI job to finish.
153
+ It checks the downloaded artifact's GitHub SHA-256 digest, package metadata and
154
+ wheel platforms before creating a Release. These checks run with Python's
155
+ standard library and the GitHub CLI supplied by the hosted runner.
156
+
157
+ The Release contains the wheel(s), source archive and `SHA256SUMS`. Its notes
158
+ record the exact source commit, build-run URL, artifact ID and per-file hashes.
159
+ An existing tag must resolve to that commit; an existing Release for the same
160
+ tag, including a draft, causes a failure instead of being overwritten. Partial
161
+ drafts are retained for inspection. Review drafts in the repository's
162
+ **Releases** page. When a tag does not exist yet, GitHub may defer creating it
163
+ until the draft is published; the draft retains the exact target commit.
164
+
165
+ The default is a **draft**. Formal GitHub publication happens only when
166
+ `github_release` is on and `draft` is explicitly off. The Release job uses the
167
+ built-in `GITHUB_TOKEN` with `actions: read` and `contents: write`; it needs no
168
+ personal access token, PyPI credential or OIDC permission.
169
+
170
+ ### PyPI authorization
171
+
172
+ Only the `publish_pypi` job uses the `pypi` environment and `id-token: write`.
173
+ It downloads the prepared artifact and invokes `pypa/gh-action-pypi-publish`.
174
+ The workflow filename is still `publish.yml`; changing its display name to
175
+ **Publish packages** does not change the Trusted Publisher identity.
176
+
177
+ 1. In this GitHub repository, open **Settings → Environments** and ensure an
178
+ environment named exactly `pypi` exists. No PyPI API token is needed.
179
+ 2. For an existing PyPI project you own, open its **Publishing** settings and
180
+ add or verify the GitHub Trusted Publisher. For a new project, use
181
+ [account Publishing](https://pypi.org/manage/account/publishing/) to add a
182
+ pending publisher instead:
183
+
184
+ | PyPI field | Value |
185
+ | --- | --- |
186
+ | PyPI Project Name (pending publisher only) | `graspkit-atomic` |
187
+ | Owner | `YenochQin` |
188
+ | Repository name | `graspkit` |
189
+ | Workflow name | `publish.yml` |
190
+ | Environment name | `pypi` |
191
+
192
+ Enter only the workflow filename, without `.github/workflows/`. A pending
193
+ publisher does not reserve the project name; the first successful use
194
+ creates the project. Authorization for another PyPI project does not
195
+ automatically authorize this one.
196
+ 3. To rehearse, leave **publish_pypi** and **github_release** unchecked. To upload
197
+ to PyPI when authorized, enable **publish_pypi**. Enable **github_release**
198
+ too if you also want the same files on GitHub, leaving **draft** checked
199
+ unless a formal Release is intended. This workflow has no TestPyPI target.
200
+
201
+ See the [PyPI Trusted Publishing guide](https://docs.pypi.org/trusted-publishers/).
@@ -1,3 +1,3 @@
1
1
  """Package version, also read by Hatchling when building distributions."""
2
2
 
3
- __version__ = "3.4.2"
3
+ __version__ = "3.4.3"
@@ -1,186 +0,0 @@
1
- # Preparing a graspkit-atomic release
2
-
3
- The prepared stable version is **3.4.2**. Its single source is
4
- `src/graspkit/version.py`; Hatchling reads it through `dynamic = ["version"]`.
5
- The local build commands below do not upload files or create Git tags.
6
- The separate manual publishing workflow is described near the end of this guide.
7
-
8
- ## Local build in the paired workspace
9
-
10
- Set up or refresh the shared environment from `graspkit-tools/` with
11
- `uv sync --extra cpu` (`--extra gpu` on a CUDA host). Then, from `graspkit/`:
12
-
13
- ```bash
14
- source ../graspkit-tools/.venv/bin/activate
15
- python build_package.py --clean
16
- ```
17
-
18
- The helper uses the current interpreter, builds a source archive and a wheel
19
- from that archive, runs `twine check --strict`, checks the file manifest and
20
- metadata, and runs a wheel smoke test. Build isolation supplies Hatchling.
21
- It never installs tools into the runtime or copies files to the Tools repo.
22
- The obsolete `--dev` option is removed; edit the version source deliberately.
23
- `--clean` removes only matching graspkit-atomic archives from the selected output
24
- folder. Unknown files cause an error instead of being deleted.
25
-
26
- Output: `dist/graspkit_atomic-3.4.2.tar.gz` and
27
- `dist/graspkit_atomic-3.4.2-py3-none-any.whl`. An optional `--outdir PATH` selects an
28
- empty output folder. The shell/batch wrappers select the shared Tools Python.
29
-
30
- Equivalent individual checks:
31
-
32
- ```bash
33
- python -m build
34
- python -m twine check --strict dist/*
35
- python scripts/check_release.py dist --smoke
36
- python -m pytest tests/
37
- ```
38
-
39
- Do not reuse a directory containing artifacts from other versions. The checker
40
- prints SHA-256 hashes and rejects mixed versions, missing metadata/licenses,
41
- unexpected archive contents and absent typing markers. The smoke test starts
42
- a separate interpreter from a temporary directory, loads the extracted wheel,
43
- checks its import origin and version, selects CSFs and renders a plot. Locally,
44
- runtime dependencies come from Tools; this is not a clean dependency-resolution
45
- test. The CI workflow installs the wheel and dependencies on a fresh runner.
46
-
47
- ## Files and license
48
-
49
- The wheel contains `graspkit` and `graspkit_plot`. The source archive includes
50
- those sources, metadata, GPLv3 text and selected installation/build docs.
51
- Research notes, agent instructions, tests, local data and historical reports
52
- are excluded. Full regression tests remain in the development repository.
53
- The existing GPLv3 license is recorded as `GPL-3.0-only`.
54
-
55
- ## Build-only CI
56
-
57
- `.github/workflows/build-release.yml` runs by manual dispatch or by an explicit
58
- push to a `codex/release-build-check-*` branch. It is also reusable through
59
- `workflow_call`, so the publishing workflow builds the same commit. It builds
60
- and checks on Linux, Windows and macOS using Python 3.14, and stores GitHub
61
- Actions artifacts. It has no PyPI credentials, OIDC publishing permission,
62
- publish job or tag-triggered upload. CI uses an ephemeral standalone runner;
63
- it does not create a second runtime in this paired local workspace.
64
- A universal wheel still relies on its dependencies supporting the target OS.
65
- Python versions above 3.14 are permitted by metadata but not yet in this matrix.
66
-
67
- Until the workflow reaches the default branch, start a check from the release
68
- commit by pushing it to a dedicated branch, for example:
69
-
70
- ```bash
71
- git push origin HEAD:refs/heads/codex/release-build-check-20261020
72
- ```
73
-
74
- Choose a fresh suffix for a separate run of an unchanged commit. Normal
75
- development-branch pushes and tags do not trigger this workflow. Once the
76
- workflow is on the default branch, the Actions page also offers **Run workflow**
77
- with a branch selector. Review all three platform jobs before using the artifacts.
78
-
79
- ## Before a later publication
80
-
81
- 1. Review the exact source commit and release changes; rerun the workflow on it.
82
- 2. Confirm PyPI ownership/availability of `graspkit-atomic`, and that version 3.4.2
83
- has not already been published. A missing public project page alone does
84
- not prove that a name is available.
85
- 3. Inspect the actual archives and hashes. Publishing makes their contents
86
- public even if the Git repository remains private. Repository URLs in the
87
- metadata require access to that repository; provide accessible public docs
88
- or change visibility deliberately if external users need them.
89
- 4. Test installation from TestPyPI only when an upload is explicitly authorized.
90
- 5. Configure the Trusted Publisher described below and run the manual
91
- publishing workflow only when the upload is authorized.
92
- 6. Tag the approved commit and record the version/release notes. A later commit
93
- request also covers the parent gitlink update; this preparation creates no tag.
94
-
95
- References: [PyPA packaging](https://packaging.python.org/en/latest/tutorials/packaging-projects/),
96
- [Trusted Publishing](https://docs.pypi.org/trusted-publishers/).
97
-
98
- ## Manual PyPI publishing
99
-
100
- `.github/workflows/publish.yml` is named **Publish to PyPI** in GitHub Actions.
101
- It has only a `workflow_dispatch` trigger. Pushing commits, tags, or completing
102
- an ordinary build does not start it. It accepts two inputs:
103
-
104
- - `version`: the exact version in the source, currently `3.4.2`.
105
- - `publish`: a checkbox, **false by default**. Leave it unchecked for a dry run.
106
-
107
- Only `main` is accepted. Preflight checks the requested version before the
108
- existing three-platform build matrix runs. The assembler validates every
109
- platform's package name, filename/metadata version and Python/platform tags,
110
- then retains one canonical Linux source archive. GraspKit keeps only the Linux
111
- copy of its universal wheel; rCSFs keeps all three platform wheels. This avoids
112
- silently overwriting duplicate filenames from different runners.
113
-
114
- The prepared archives are stored in the **pypi-distributions** Actions artifact;
115
- the job summary lists their SHA-256 hashes and source commit. Preparation and
116
- build jobs have no OIDC permission. Only the final, separately gated `publish`
117
- job uses the `pypi` environment and `id-token: write`. That job downloads the
118
- prepared artifact and invokes `pypa/gh-action-pypi-publish`; it does not rebuild.
119
- When `publish` is false, the upload job is skipped entirely. The workflow group
120
- serializes publication attempts. It neither bumps versions nor creates tags.
121
-
122
- ### Configure authorization in the browser
123
-
124
- This rename creates a new PyPI project, `graspkit-atomic`. Authorization for the
125
- previous `grasp-atomic-kit` project does not carry over; configure the publisher
126
- for the new name below. The repository and Python import names stay unchanged.
127
-
128
- 1. In this GitHub repository, open **Settings → Environments → New environment**
129
- and create an environment named exactly **pypi**. No PyPI token or environment
130
- secret is needed. You can restrict its deployment branches to `main`.
131
- 2. Log in to [PyPI Publishing](https://pypi.org/manage/account/publishing/).
132
- Under **Add a new pending publisher**, choose **GitHub** and enter:
133
-
134
- | PyPI field | Value |
135
- | --- | --- |
136
- | PyPI Project Name | `graspkit-atomic` |
137
- | Owner | `YenochQin` |
138
- | Repository name | `graspkit` |
139
- | Workflow name | `publish.yml` |
140
- | Environment name | `pypi` |
141
-
142
- Enter only `publish.yml`, without `.github/workflows/`. The owner is the
143
- GitHub account name, not the PyPI username. Add the pending publisher. This
144
- does not upload files, create the project or reserve its name; the project
145
- is created on the first successful publication. If you already own an
146
- existing project with this name, add the publisher in that project's
147
- Publishing settings instead.
148
- 3. For a rehearsal, choose **Actions → Publish to PyPI → Run workflow**, select
149
- `main`, enter `3.4.2` and leave **publish unchecked**. All builds and
150
- package checks run, and the upload job is skipped. A dry run does not test
151
- the PyPI OIDC exchange because it never enters the publishing job.
152
- 4. Only when publication is authorized, run the same workflow from `main` with
153
- the exact version and **publish checked**. Then install that version from
154
- PyPI to verify it. TestPyPI is not a destination in this production workflow.
155
-
156
- The pending-publisher setup follows the [PyPI guide](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
157
-
158
- ## GitHub Release drafts from a successful rehearsal
159
-
160
- Open **Actions → Draft GitHub Release → Run workflow** and select `main`.
161
- Fill in `run_id` with the numeric ID from a successful **Publish to PyPI**
162
- rehearsal URL (`/actions/runs/NUMBER`), and `tag` with `v3.4.2` (or the
163
- version of that rehearsal). The selected run must have `publish` unchecked:
164
- `preflight`, all three builds and `prepare` must pass, and `publish` must be
165
- skipped. Runs from forks, other workflows or branches are rejected.
166
-
167
- The workflow downloads that run's unexpired `pypi-distributions` artifact,
168
- checks its GitHub SHA-256 digest, and verifies package names, metadata versions
169
- and the expected wheel platforms. It reuses the exact archives without
170
- installing dependencies or rebuilding. The script uses Python's standard
171
- library and the GitHub CLI supplied by the hosted runner.
172
-
173
- The resulting **draft** contains the wheel(s), source archive and `SHA256SUMS`.
174
- Its notes record the source commit, run URL, artifact ID and per-file hashes.
175
- The Release target is the rehearsal's commit, even if `main` has moved since.
176
- An existing tag must resolve to that commit; an existing Release for the tag
177
- (including a draft) causes a failure instead of overwriting it. Failed partial
178
- drafts are retained for inspection. If an artifact has expired, run a new
179
- rehearsal and use its run ID.
180
-
181
- This workflow always creates a draft: it has no formal-publication switch and
182
- no PyPI job or OIDC permission. It needs only the built-in `GITHUB_TOKEN` with
183
- `actions: read` and `contents: write`, not a personal token or PyPI secret.
184
- Review the draft in **Releases**; publishing it later requires a separate
185
- manual action. If the tag does not exist yet, GitHub may defer creating it
186
- until the draft is published; the draft retains the exact target commit.
File without changes