constutil 1.1.0__tar.gz → 1.2.0__tar.gz

{constutil-1.1.0 → constutil-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: constutil
-Version: 1.1.0
+Version: 1.2.0
 Summary: Typed constant definitions and groups for Python
 Project-URL: Homepage, https://github.com/patchfork/constutil
 Project-URL: Documentation, https://constutil.patchfork.dev/
@@ -36,8 +36,7 @@ Requires **Python 3.12 or newer**.
 pip install constutil
 ```
 
-This branch prepares version 1.1.0 (Python 3.12+); PyPI currently provides 1.0.0.
-To use the unreleased changes, install directly from GitHub:
+To use changes not yet published to PyPI, install directly from GitHub:
 
 ```sh
 pip install git+https://github.com/patchfork/constutil.git
@@ -120,6 +119,12 @@ class Season(StrConstGroup):
 
 
 assert Season.get_value("Spring") == "spring"
+assert Season.get_value_map() == {
+    "SPRING": "spring",
+    "SUMMER": "summer",
+    "AUTUMN": "autumn",
+    "WINTER": "winter",
+}
 assert Season.is_valid_value("SPRING") is False
 ```
 
@@ -193,6 +198,7 @@ returned as-is and is not required to belong to the group; absent defaults are
 | `get_default()` | Configured member or `None` |
 | `get_all()` | Tuple of members |
 | `get_all_map()` | Fresh attribute-name → member dictionary |
+| `get_value_map()` | Fresh attribute-name → stored-value dictionary, in declaration order |
 | `get_all_values()` | Tuple of stored values |
 | `get_all_names()` | Tuple of display names |
 | `get_all_constant_names()` | Tuple of Python attribute names |
@@ -394,17 +400,37 @@ One-time setup:
    if you already own the project): owner `patchfork`, repository `constutil`,
    workflow filename `pypi_publish.yml`, environment `pypi`.
 
-For each new release:
-
-1. Update `project.version` in `pyproject.toml`, run `uv lock`, and push the changes.
-2. Run **Actions → Prepare GitHub release → Run workflow** on that commit's branch,
-   with the matching tag (for example, `v1.0.1` for version `1.0.1`). The workflow
-   runs CI, builds and checks the packages, creates the tag at the tested commit,
-   and creates a **draft** release with both distributions attached.
-3. Review the draft's notes and downloads, then click **Publish release** in GitHub.
-   That user action triggers `pypi_publish.yml`. The preparation workflow deliberately
-   leaves publication to the user: events created using `GITHUB_TOKEN` do not
-   automatically trigger other workflows.
+#### Trigger a release
+
+First bump the package version from the repository root:
+
+```sh
+sh scripts/bump-version.sh --dry-run patch  # Preview the next patch version
+sh scripts/bump-version.sh patch           # Or: minor, major, or an explicit 1.2.0
+```
+
+The script requires `uv` with the `uv version` command and updates
+`project.version` in `pyproject.toml` and the package entry in `uv.lock`, without
+syncing the environment. Review and commit those changes, then push them to `main`.
+It does not create a commit, tag, or release. Historical version references in
+documentation are left unchanged; review release-specific prose when preparing a
+release.
+
+Then prepare the release:
+
+1. Open [Prepare GitHub release](https://github.com/patchfork/constutil/actions/workflows/prepare_release.yml).
+2. Click **Run workflow**, select the `main` branch, enter the package version
+   prefixed with `v` as the tag (for example, **`v1.2.0`**), and start the workflow.
+3. Wait for the workflow to pass CI and create a **draft release** with the wheel
+   and source archive attached.
+4. Open [Releases](https://github.com/patchfork/constutil/releases), review the
+   draft's notes and downloads, and click **Publish release**.
+5. Publishing automatically triggers
+   [Publish to PyPI](https://github.com/patchfork/constutil/actions/workflows/pypi_publish.yml)
+   to upload those exact packages. Check that workflow for the publishing result.
+
+The preparation workflow deliberately leaves publication to the user: events
+created using `GITHUB_TOKEN` do not automatically trigger other workflows.
 
 GitHub releases are immutable after publication. Uploads must happen while the
 release is still a draft; the publish workflow never adds or replaces release

{constutil-1.1.0 → constutil-1.2.0}/README.md

@@ -14,8 +14,7 @@ Requires **Python 3.12 or newer**.
 pip install constutil
 ```
 
-This branch prepares version 1.1.0 (Python 3.12+); PyPI currently provides 1.0.0.
-To use the unreleased changes, install directly from GitHub:
+To use changes not yet published to PyPI, install directly from GitHub:
 
 ```sh
 pip install git+https://github.com/patchfork/constutil.git
@@ -98,6 +97,12 @@ class Season(StrConstGroup):
 
 
 assert Season.get_value("Spring") == "spring"
+assert Season.get_value_map() == {
+    "SPRING": "spring",
+    "SUMMER": "summer",
+    "AUTUMN": "autumn",
+    "WINTER": "winter",
+}
 assert Season.is_valid_value("SPRING") is False
 ```
 
@@ -171,6 +176,7 @@ returned as-is and is not required to belong to the group; absent defaults are
 | `get_default()` | Configured member or `None` |
 | `get_all()` | Tuple of members |
 | `get_all_map()` | Fresh attribute-name → member dictionary |
+| `get_value_map()` | Fresh attribute-name → stored-value dictionary, in declaration order |
 | `get_all_values()` | Tuple of stored values |
 | `get_all_names()` | Tuple of display names |
 | `get_all_constant_names()` | Tuple of Python attribute names |
@@ -372,17 +378,37 @@ One-time setup:
    if you already own the project): owner `patchfork`, repository `constutil`,
    workflow filename `pypi_publish.yml`, environment `pypi`.
 
-For each new release:
-
-1. Update `project.version` in `pyproject.toml`, run `uv lock`, and push the changes.
-2. Run **Actions → Prepare GitHub release → Run workflow** on that commit's branch,
-   with the matching tag (for example, `v1.0.1` for version `1.0.1`). The workflow
-   runs CI, builds and checks the packages, creates the tag at the tested commit,
-   and creates a **draft** release with both distributions attached.
-3. Review the draft's notes and downloads, then click **Publish release** in GitHub.
-   That user action triggers `pypi_publish.yml`. The preparation workflow deliberately
-   leaves publication to the user: events created using `GITHUB_TOKEN` do not
-   automatically trigger other workflows.
+#### Trigger a release
+
+First bump the package version from the repository root:
+
+```sh
+sh scripts/bump-version.sh --dry-run patch  # Preview the next patch version
+sh scripts/bump-version.sh patch           # Or: minor, major, or an explicit 1.2.0
+```
+
+The script requires `uv` with the `uv version` command and updates
+`project.version` in `pyproject.toml` and the package entry in `uv.lock`, without
+syncing the environment. Review and commit those changes, then push them to `main`.
+It does not create a commit, tag, or release. Historical version references in
+documentation are left unchanged; review release-specific prose when preparing a
+release.
+
+Then prepare the release:
+
+1. Open [Prepare GitHub release](https://github.com/patchfork/constutil/actions/workflows/prepare_release.yml).
+2. Click **Run workflow**, select the `main` branch, enter the package version
+   prefixed with `v` as the tag (for example, **`v1.2.0`**), and start the workflow.
+3. Wait for the workflow to pass CI and create a **draft release** with the wheel
+   and source archive attached.
+4. Open [Releases](https://github.com/patchfork/constutil/releases), review the
+   draft's notes and downloads, and click **Publish release**.
+5. Publishing automatically triggers
+   [Publish to PyPI](https://github.com/patchfork/constutil/actions/workflows/pypi_publish.yml)
+   to upload those exact packages. Check that workflow for the publishing result.
+
+The preparation workflow deliberately leaves publication to the user: events
+created using `GITHUB_TOKEN` do not automatically trigger other workflows.
 
 GitHub releases are immutable after publication. Uploads must happen while the
 release is still a draft; the publish workflow never adds or replaces release

{constutil-1.1.0 → constutil-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "constutil"
-version = "1.1.0"
+version = "1.2.0"
 description = "Typed constant definitions and groups for Python"
 readme = "README.md"
 requires-python = ">=3.12"

constutil-1.2.0/scripts/bump-version.sh

@@ -0,0 +1,43 @@
+#!/bin/sh
+# Update package metadata and the lockfile without installing or publishing.
+set -eu
+
+usage() {
+    cat <<'EOF'
+Usage: sh scripts/bump-version.sh [--dry-run] major|minor|patch|VERSION
+
+Examples:
+  sh scripts/bump-version.sh patch
+  sh scripts/bump-version.sh --dry-run minor
+  sh scripts/bump-version.sh 1.2.0
+
+Requires uv with the `uv version` command. Updates pyproject.toml and uv.lock.
+Does not commit, tag, or publish. --dry-run previews without changing files.
+EOF
+}
+
+dry_run=false
+if [ "${1:-}" = "--help" ] || [ "${1:-}" = "-h" ]; then
+    usage
+    exit 0
+fi
+if [ "${1:-}" = "--dry-run" ]; then
+    dry_run=true
+    shift
+fi
+if [ "$#" -ne 1 ]; then
+    usage >&2
+    exit 2
+fi
+
+case "$1" in
+    major|minor|patch) set -- --bump "$1" ;;
+    [0-9]*) ;; # uv validates and normalizes explicit Python package versions.
+    *) usage >&2; exit 2 ;;
+esac
+if [ "$dry_run" = true ]; then
+    set -- "$@" --dry-run
+fi
+
+repo_root=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+exec uv version --project "$repo_root" --no-sync "$@"

{constutil-1.1.0 → constutil-1.2.0}/src/constutil/constgroup.py

@@ -45,6 +45,21 @@ class ConstGroup(Generic[MemberT]):
             members[key] = cast(MemberT, member)
         return members
 
+    @classmethod
+    def get_value_map(cls) -> dict[str, int | str]:
+        """Return a fresh mapping of constant name to value, in class declaration order.
+
+        Keys are the class attribute names (``"MONDAY"``), the same keys
+        ``get_all_map`` uses; values are each member's ``.value``. Lookups by name go
+        through ``get_by_constant_name``; this is for handing the whole group to an
+        API that wants a plain dict, such as SQLAlchemy's ``naming_convention`` or a
+        JSON payload.
+
+        Returns:
+            A new dict each call, so callers may mutate it freely.
+        """
+        return {key: member.value for key, member in cls.get_all_map().items()}
+
     @classmethod
     def get_all(cls) -> tuple[MemberT, ...]:
         return tuple(cls.get_all_map().values())

{constutil-1.1.0 → constutil-1.2.0}/tests/test_constutil.py

@@ -44,6 +44,30 @@ def test_enumeration_and_default():
     assert len(Day.get_all()) == 2
 
 
+@pytest.mark.parametrize(
+    "group,expected,value_type",
+    [
+        (Day, [("MONDAY", 1), ("TUESDAY", 2)], int),
+        (Moon, [("TITAN", "titan"), ("RHEA", "rhea")], str),
+    ],
+)
+def test_value_map_preserves_declaration_order_filters_and_value_types(group, expected, value_type):
+    mapping = group.get_value_map()
+    assert isinstance(mapping, dict)
+    assert list(mapping.items()) == expected
+    assert all(type(value) is value_type for value in mapping.values())
+
+
+@pytest.mark.parametrize("group", [Day, Moon])
+def test_value_map_returns_a_fresh_dict(group):
+    original = group.get_value_map()
+    mapping = group.get_value_map()
+    assert mapping is not original
+    mapping.clear()
+    mapping["EXTRA"] = "extra"
+    assert group.get_value_map() == original
+
+
 @pytest.mark.parametrize(
     "value,expected",
     [(1, True), ("1", False), (True, True), (1.0, True), (0, False), (None, False)],

{constutil-1.1.0 → constutil-1.2.0}/uv.lock

@@ -278,7 +278,7 @@ wheels = [
 
 [[package]]
 name = "constutil"
-version = "1.1.0"
+version = "1.2.0"
 source = { editable = "." }
 
 [package.dev-dependencies]