Prepare for 4.0.0 release

.github/CONTRIBUTING.md

@@ -7,7 +7,7 @@ Before spending time working on a pull request, please [open an idea discussion]
 To speed up the review process, please ensure:
 
 * your change has corresponding tests that run with the existing pytest suite and pass.
-* the code is formatted with [black](https://black.readthedocs.io/en/stable/index.html), included in the dev dependencies.
+* the code is formatted with [ruff](https://docs.astral.sh/ruff/), included in the dev dependencies.
 * you are open to feedback!
 
 Thank you and we look forward to your contribution! ✨

.github/workflows/publish.yml

@@ -21,9 +21,7 @@ jobs:
         uses: astral-sh/setup-uv@v7
 
       - name: Set version from tag
-        run: |
-          VERSION=${GITHUB_REF#refs/tags/v}
-          sed -i "s/^__version__ = .*/__version__ = \"${VERSION}\"/" us/version.py
+        run: uv version "${GITHUB_REF#refs/tags/v}"
 
       - name: Build package
         run: uv build

CHANGELOG.md

@@ -3,8 +3,9 @@
 ## 4.0.0
 
 * add counties, thanks to [Ray Kiddy](https://github.com/rkiddy)
-* DC has returned to `STATES_AND_TERRITORIES`, thanks to [Kavi Gupta](https://github.com/kavigupta)
 * add `clean_name()` method and `fallback_func` parameter to `lookup()` to provide customizable matching, thanks to [Max Filenko](https://github.com/mfilenko) and [Charlie Tonneslan](https://github.com/c-tonneslan)
+* DC has returned to `STATES_AND_TERRITORIES`, thanks to [Kavi Gupta](https://github.com/kavigupta)
+* add `us.__version__` and deprecate `us.version`
 * fix `py.typed` location, thanks to [johnw-bluemark](https://github.com/johnw-bluemark)
 * add support for Python 3.13 and 3.14
 * switch to [uv](https://docs.astral.sh/uv/) for development and packaging

README.md

@@ -25,10 +25,10 @@ As per usual:
 pip install us
 ```
 
-or 
+or
 
 ```
-uv install us
+uv add us
 ```
 
 
@@ -39,7 +39,8 @@ This project uses [uv](https://docs.astral.sh/uv/) for development.
 ```
 uv sync
 uv run pytest
-uv run black --check us
+uv run ruff check us
+uv run ruff format --check us
 ```
 
 

pyproject.toml

@@ -1,14 +1,15 @@
 [build-system]
 requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
 
 [project]
 name = "us"
-description = "US state meta information and other fun stuff"
+version = "4.0.0.dev0"
+description = "US state metadata"
 readme = "README.md"
 urls.Homepage = "https://github.com/unitedstates/python-us/"
 urls."Issue tracker" = "https://github.com/unitedstates/python-us/issues"
 requires-python = ">=3.8"
-dynamic = ["version"]
 authors = [{ name = "Jeremy Carbaugh", email = "jeremy@jcarbaugh.com" }]
 classifiers = [
     "Programming Language :: Python",
@@ -30,9 +31,6 @@ states = "us.cli.states:main"
 [dependency-groups]
 dev = ['ruff', 'pytest', 'pytz']
 
-[tool.setuptools.dynamic]
-version = { attr = "us.version.__version__" }
-
 [tool.ruff]
 line-length = 120
 target-version = "py38"

us/__init__.py

@@ -1,10 +1,40 @@
-from .states import (  # noqa
-    STATES,  # noqa
-    STATES_CONTIGUOUS,  # noqa
-    STATES_CONTINENTAL,  # noqa
-    TERRITORIES,  # noqa
-    STATES_AND_TERRITORIES,  # noqa
-    OBSOLETE,  # noqa
-)  # noqa
-from .unitedstatesofamerica import *  # noqa
-from .version import __version__ as version  # noqa
+from .states import (
+    STATES,
+    STATES_CONTIGUOUS,
+    STATES_CONTINENTAL,
+    TERRITORIES,
+    STATES_AND_TERRITORIES,
+    OBSOLETE,
+)
+from .unitedstatesofamerica import name, abbr, birthday
+
+try:
+    from importlib.metadata import version as _get_version
+
+    __version__ = _get_version("us")
+except Exception:
+    __version__ = "unknown"
+
+
+# Deprecated support for us.version. Remove in the 5.0 release.
+def __getattr__(name):
+    if name == "version":
+        from warnings import warn
+
+        warn("us.version is deprecated, use us.__version__ instead", DeprecationWarning)
+        return __version__
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+__all__ = [
+    "STATES",
+    "STATES_CONTIGUOUS",
+    "STATES_CONTINENTAL",
+    "TERRITORIES",
+    "STATES_AND_TERRITORIES",
+    "OBSOLETE",
+    "name",
+    "abbr",
+    "birthday",
+    "__version__",
+]

us/tests/test_us.py

@@ -16,6 +16,12 @@ def test_attribute():
         assert state == getattr(us.states, state.abbr)
 
 
+def test_version_deprecation():
+    with pytest.warns(DeprecationWarning):
+        version = us.version
+    assert version == us.__version__
+
+
 def test_valid_timezones():
     for state in us.STATES_AND_TERRITORIES:
         if state.capital: