Skip to content

Commit d83f98b

Browse files
nicholaskarlsonnicholaskarlson
committed
PyStatsV1 Drop-in B: prepare v0.23.0 release
1 parent 5ce9edf commit d83f98b

11 files changed

Lines changed: 388 additions & 10 deletions

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ on:
44
workflow_dispatch:
55
push:
66
branches: [ main, dev, chore/**, docs/**, feat/** ]
7+
tags:
8+
- "v*"
79
pull_request:
810
branches: [ main ]
911

‎.github/workflows/pypi-publish.yml‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
name: Publish to PyPI (trusted publisher)
22

3+
# Release policy: CI runs on v* tags first. Publish only after the tag CI is green.
4+
# Run manually against the release tag, for example:
5+
# gh workflow run pypi-publish.yml --ref v0.23.0
36
on:
4-
push:
5-
tags:
6-
- "v*"
7+
workflow_dispatch:
78

89
jobs:
910
build-and-publish:

‎README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,25 @@ pystatsv1-docs
4848

4949
Tip: the online docs are always available via the ReadTheDocs badge at the top of this README.
5050

51+
## 🧠 Psychology support helpers (v0.23.0)
52+
53+
PyStatsV1 v0.23.0 adds a small public `pystatsv1.psych` helper layer for proof-first psychology and APA-style companion labs. These helpers are intentionally modest: they do **not** replace SciPy, statsmodels, Pingouin, or R for inferential statistics. They provide a reusable bridge for identity receipts, descriptive summaries, stable JSON receipts, and numeric parity comparisons.
54+
55+
```python
56+
from pystatsv1.psych import (
57+
package_identity,
58+
describe_by_group,
59+
write_json_receipt,
60+
compare_numeric_results,
61+
)
62+
```
63+
64+
This supports the companion-lab positioning:
65+
66+
> Python for the workflow. R for verification. PyStatsV1 for the bridge.
67+
68+
See `docs/source/psych_support_helpers.rst` and `docs/source/release_notes.rst` for details.
69+
5170
## Full repository (scripts, Makefile targets, tests, docs)
5271

5372

‎docs/PYSTATSV1_DROPIN_B_PY310_BUILD_HOTFIX.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# PyStatsV1 Drop-in B Python 3.10 and Build Hotfix
2+
3+
This hotfix repairs two release-prep verification issues found after applying PyStatsV1 Drop-in B.
4+
5+
## Fixes
6+
7+
- `tests/test_release_023_metadata.py` now supports Python 3.10 by falling back from `tomllib` to `tomli`.
8+
- The contributor `dev` extra now installs `tomli` on Python versions earlier than 3.11.
9+
- The contributor `dev` extra now installs `build`, so `python -m build` works after `python -m pip install -e '.[dev,docs]'`.
10+
11+
## Expected verification
12+
13+
```bash
14+
python -m pip install -e '.[dev,docs]'
15+
make lint
16+
make test
17+
make docs-workbook-strict
18+
python -m build
19+
```
20+
21+
Expected hotfix marker from the apply script:
22+
23+
```text
24+
PYSTATSV1_DROPIN_B_PY310_BUILD_HOTFIX_APPLIED_OK
25+
```

‎docs/PYSTATSV1_DROPIN_B_V0_23_RELEASE_PREP.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# PyStatsV1 Drop-in B — v0.23.0 Release Prep
2+
3+
## Purpose
4+
5+
Prepare the public PyStatsV1 package for a reader-installable release that
6+
contains the APA Lab psychology support helpers.
7+
8+
## Changes
9+
10+
- Bumped package version from `0.22.4` to `0.23.0`.
11+
- Added release notes for `pystatsv1.psych`.
12+
- Expanded documentation for:
13+
- `package_identity()`
14+
- `describe_by_group()`
15+
- `write_json_receipt()`
16+
- `compare_numeric_results()`
17+
- Added a release-prep note at `docs/release/v0.23.0.md`.
18+
- Updated CI so `v*` release tags run the full CI workflow.
19+
- Changed PyPI publishing to a manual trusted-publisher workflow, so publication
20+
happens only after the release tag is green.
21+
- Added release metadata tests.
22+
23+
## Expected verification
24+
25+
```bash
26+
python -m pip install -e '.[dev,docs]'
27+
make lint
28+
make test
29+
make docs-workbook-strict
30+
python -m build
31+
```
32+
33+
## Expected marker
34+
35+
```text
36+
PYSTATSV1_DROPIN_B_V0_23_RELEASE_PREP_APPLIED_OK
37+
```

‎docs/release/v0.23.0.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# PyStatsV1 v0.23.0 Release Prep
2+
3+
This release prepares PyStatsV1 for the APA Article Lab companion project and
4+
other proof-first psychology workflows.
5+
6+
## Release purpose
7+
8+
PyStatsV1 v0.23.0 exposes the `pystatsv1.psych` helper layer as a public,
9+
reader-installable package feature. The helpers support the book-series phrase:
10+
11+
> Python for the workflow. R for verification. PyStatsV1 for the bridge.
12+
13+
## Public APIs documented
14+
15+
- `package_identity()`
16+
- `describe_by_group()`
17+
- `write_json_receipt()`
18+
- `compare_numeric_results()`
19+
20+
## Conservative claim boundary
21+
22+
This release does not claim that PyStatsV1 replaces SciPy, statsmodels,
23+
Pingouin, or R. The helper layer provides bridge utilities, package identity
24+
receipts, descriptive summaries, JSON receipts, and numeric comparison receipts.
25+
26+
## Local verification before tag
27+
28+
```bash
29+
git status
30+
git rev-parse HEAD
31+
python -m pip install -e '.[dev,docs]'
32+
make lint
33+
make test
34+
make docs-workbook-strict
35+
python -m build
36+
```
37+
38+
## Tag and CI
39+
40+
```bash
41+
git tag -a v0.23.0 -m "PyStatsV1 v0.23.0 with APA Lab psych support helpers"
42+
git push origin v0.23.0
43+
gh run list --limit 10
44+
gh run watch --exit-status
45+
```
46+
47+
The CI workflow now runs on `v*` tags.
48+
49+
## Publish to PyPI after tag CI is green
50+
51+
The PyPI workflow is manual-only so the release tag can be tested before the
52+
public package is published.
53+
54+
```bash
55+
gh workflow run pypi-publish.yml --ref v0.23.0
56+
gh run watch --exit-status
57+
```
58+
59+
After publication, test a clean install:
60+
61+
```bash
62+
python -m pip install --upgrade pystatsv1==0.23.0
63+
python - <<'PY'
64+
from pystatsv1.psych import package_identity
65+
print(package_identity()["version"])
66+
PY
67+
```

‎docs/source/index.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,14 @@ See :doc:`getting_started` and :doc:`contributing` for the contributor workflow.
5454

5555
workbook/index
5656

57+
58+
.. toctree::
59+
:maxdepth: 1
60+
:caption: Project docs
61+
62+
release_notes
63+
psych_support_helpers
64+
5765
.. toctree::
5866
:maxdepth: 2
5967
:caption: Track A – Applied Statistics with Python (Regression)

‎docs/source/psych_support_helpers.rst‎

Lines changed: 77 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,20 +15,91 @@ This supports the PyStatsV1 book-series positioning:
1515
* R for verification.
1616
* PyStatsV1 for the bridge.
1717

18+
Install
19+
-------
20+
21+
For readers using the public package after the v0.23.0 release:
22+
23+
.. code-block:: bash
24+
25+
python -m pip install "pystatsv1==0.23.0"
26+
27+
For contributors working from the repository:
28+
29+
.. code-block:: bash
30+
31+
python -m pip install -e .
32+
1833
Public helpers
1934
--------------
2035

2136
``package_identity()``
22-
Records the imported PyStatsV1 version, module file, distribution location,
23-
Python executable, and top-level exports.
37+
Public helper. Full call signature: ``package_identity(package_name="pystatsv1", module_name="pystatsv1")``
38+
Records the imported package name, module name, version, module file, module
39+
directory, distribution location, source-kind label, Python executable, and
40+
public top-level exports. Companion labs use this to prove which PyStatsV1
41+
package was imported.
2442

2543
``describe_by_group()``
44+
Public helper. Full call signature: ``describe_by_group(data, group_col, value_cols, *, decimals=6)``
2645
Creates JSON-stable descriptive summaries by group for one or more numeric
27-
variables.
46+
variables. ``data`` may be a pandas DataFrame or an iterable of row
47+
dictionaries. The returned records include ``n``, ``mean``, ``sd``, ``min``,
48+
and ``max`` for each group/variable pair.
2849

2950
``write_json_receipt()``
30-
Writes sorted, indented JSON receipts with a final newline.
51+
Public helper. Full call signature: ``write_json_receipt(path, payload)``
52+
Writes sorted, indented JSON receipts with a final newline and creates parent
53+
directories as needed. The return value is the written ``Path``.
3154

3255
``compare_numeric_results()``
33-
Compares numeric outputs from two analysis engines and records pass/fail,
34-
missing, and non-numeric cases.
56+
Public helper. Full call signature: ``compare_numeric_results(left, right, *, tolerance=1e-6)``
57+
Compares numeric outputs from two analysis engines and returns a
58+
JSON-serializable comparison receipt. Missing values, non-numeric values,
59+
pass/fail status, absolute differences, and the stated tolerance are recorded
60+
explicitly.
61+
62+
Minimal example
63+
---------------
64+
65+
.. code-block:: python
66+
67+
from pystatsv1.psych import (
68+
package_identity,
69+
describe_by_group,
70+
write_json_receipt,
71+
compare_numeric_results,
72+
)
73+
74+
rows = [
75+
{"condition": "control", "score": 1.0},
76+
{"condition": "control", "score": 3.0},
77+
{"condition": "planning", "score": 5.0},
78+
{"condition": "planning", "score": 7.0},
79+
]
80+
81+
identity = package_identity()
82+
descriptives = describe_by_group(rows, "condition", "score", decimals=3)
83+
parity = compare_numeric_results(
84+
{"mean_difference": 4.0},
85+
{"mean_difference": 4.0000001},
86+
tolerance=1e-5,
87+
)
88+
89+
write_json_receipt(
90+
"outputs/pystatsv1_psych_receipt.json",
91+
{
92+
"identity": identity,
93+
"descriptives": descriptives,
94+
"parity": parity,
95+
},
96+
)
97+
98+
Honest computation-source story
99+
--------------------------------
100+
101+
The helper layer is a bridge, not a replacement for statistical libraries. In
102+
the APA Article Lab pattern, PyStatsV1 records package identity, descriptive
103+
summaries, JSON receipts, and numeric comparison receipts. SciPy, statsmodels,
104+
Pingouin, and R remain the appropriate sources for many inferential procedures
105+
and independent verification checks.

‎docs/source/release_notes.rst‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
Release notes
2+
=============
3+
4+
v0.23.0 — APA Lab support helpers
5+
---------------------------------
6+
7+
PyStatsV1 v0.23.0 prepares the public package for the APA Article Lab and
8+
other proof-first psychology workflows.
9+
10+
Highlights
11+
~~~~~~~~~~
12+
13+
* Adds the public ``pystatsv1.psych`` helper layer.
14+
* Documents the helper APIs used by the APA Lab companion project.
15+
* Keeps PyStatsV1's role deliberately narrow and honest: PyStatsV1 provides
16+
bridge helpers and receipts, while SciPy, statsmodels, Pingouin, and R remain
17+
the appropriate tools for many statistical procedures.
18+
* Updates the release process so CI runs on release tags and PyPI publication is
19+
a manual trusted-publisher step after the tag is green.
20+
21+
Public psychology helper APIs
22+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
23+
24+
``package_identity()``
25+
Returns a JSON-serializable package identity receipt, including package name,
26+
module name, version, import path, distribution location, source-kind label,
27+
Python executable, and public top-level exports.
28+
29+
``describe_by_group()``
30+
Produces JSON-stable descriptive summaries by group for one or more numeric
31+
variables. It records ``n``, ``mean``, ``sd``, ``min``, and ``max`` for each
32+
group/variable pair.
33+
34+
``write_json_receipt()``
35+
Writes sorted, indented JSON receipts with a final newline and creates parent
36+
directories as needed.
37+
38+
``compare_numeric_results()``
39+
Compares numeric outputs from two analysis engines with a stated tolerance and
40+
records pass, fail, missing, and non-numeric comparison cases.
41+
42+
Release checklist
43+
~~~~~~~~~~~~~~~~~
44+
45+
Before tagging ``v0.23.0``:
46+
47+
.. code-block:: bash
48+
49+
git status
50+
git rev-parse HEAD
51+
python -m pip install -e '.[dev,docs]'
52+
make lint
53+
make test
54+
make docs-workbook-strict
55+
python -m build
56+
57+
After the local checks are green:
58+
59+
.. code-block:: bash
60+
61+
git tag -a v0.23.0 -m "PyStatsV1 v0.23.0 with APA Lab psych support helpers"
62+
git push origin v0.23.0
63+
gh run list --limit 10
64+
gh run watch --exit-status
65+
66+
After the tag CI is green and the PyPI trusted publisher is configured:
67+
68+
.. code-block:: bash
69+
70+
gh workflow run pypi-publish.yml --ref v0.23.0
71+
gh run watch --exit-status
72+
73+
Then verify the public install in a clean environment:
74+
75+
.. code-block:: bash
76+
77+
python -m pip install --upgrade pystatsv1==0.23.0
78+
python - <<'PY'
79+
from pystatsv1.psych import package_identity
80+
print(package_identity()["version"])
81+
PY

‎pyproject.toml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "pystatsv1"
7-
version = "0.22.4"
7+
version = "0.23.0"
88
description = "PyStatsV1: applied statistics labs in Python."
99
readme = "README.md"
1010
requires-python = ">=3.10"
@@ -36,6 +36,8 @@ dev = [
3636
"pytest>=8.2",
3737
"ruff>=0.6",
3838
"black>=24.0",
39+
"tomli>=2.0; python_version < '3.11'",
40+
"build>=1.2",
3941
]
4042

4143
# Docs bundle: for building Sphinx locally.

0 commit comments

Comments
 (0)