diff --git a/.sampo/changesets/gentle-moss-derive.md b/.sampo/changesets/gentle-moss-derive.md new file mode 100644 index 0000000..acca5a8 --- /dev/null +++ b/.sampo/changesets/gentle-moss-derive.md @@ -0,0 +1,8 @@ +--- +pypi/generaltranslation: minor +pypi/gt-i18n: minor +pypi/gt-fastapi: minor +pypi/gt-flask: minor +--- + +refactor: rename `declare_static()` to `derive()` and deprecate `declare_static()` diff --git a/packages/generaltranslation/src/generaltranslation/__init__.py b/packages/generaltranslation/src/generaltranslation/__init__.py index 73fec24..c9376f7 100644 --- a/packages/generaltranslation/src/generaltranslation/__init__.py +++ b/packages/generaltranslation/src/generaltranslation/__init__.py @@ -52,6 +52,7 @@ declare_static, declare_var, decode_vars, + derive, extract_vars, index_vars, sanitize_var, @@ -106,11 +107,12 @@ "is_superset_locale", "requires_translation", "get_plural_form", - # Static + # Derive / variable helpers "VAR_IDENTIFIER", "VAR_NAME_IDENTIFIER", "sanitize_var", "declare_var", + "derive", "declare_static", "decode_vars", "extract_vars", diff --git a/packages/generaltranslation/src/generaltranslation/static/__init__.py b/packages/generaltranslation/src/generaltranslation/static/__init__.py index 414093f..0eca171 100644 --- a/packages/generaltranslation/src/generaltranslation/static/__init__.py +++ b/packages/generaltranslation/src/generaltranslation/static/__init__.py @@ -1,8 +1,8 @@ from generaltranslation.static._condense_vars import condense_vars from generaltranslation.static._constants import VAR_IDENTIFIER, VAR_NAME_IDENTIFIER -from generaltranslation.static._declare_static import declare_static from generaltranslation.static._declare_var import declare_var from generaltranslation.static._decode_vars import decode_vars +from generaltranslation.static._derive import declare_static, derive from generaltranslation.static._extract_vars import extract_vars from generaltranslation.static._index_vars import index_vars from generaltranslation.static._sanitize_var import sanitize_var @@ -12,6 +12,7 @@ "VAR_NAME_IDENTIFIER", "sanitize_var", "declare_var", + "derive", "declare_static", "decode_vars", "extract_vars", diff --git a/packages/generaltranslation/src/generaltranslation/static/_declare_static.py b/packages/generaltranslation/src/generaltranslation/static/_declare_static.py deleted file mode 100644 index 76a3da1..0000000 --- a/packages/generaltranslation/src/generaltranslation/static/_declare_static.py +++ /dev/null @@ -1,9 +0,0 @@ -from __future__ import annotations - - -def declare_static(content: object) -> object: - """Mark *content* as statically analyzable. - - This is an identity function used as a marker for static analysis. - """ - return content diff --git a/packages/generaltranslation/src/generaltranslation/static/_derive.py b/packages/generaltranslation/src/generaltranslation/static/_derive.py new file mode 100644 index 0000000..3756de2 --- /dev/null +++ b/packages/generaltranslation/src/generaltranslation/static/_derive.py @@ -0,0 +1,26 @@ +from __future__ import annotations + +import warnings + + +def derive(content: object) -> object: + """Mark *content* as derivable (statically analyzable). + + This is an identity function used as a marker for the CLI tool's + static analysis. + """ + return content + + +def declare_static(content: object) -> object: + """Mark *content* as derivable (statically analyzable). + + .. deprecated:: + Use :func:`derive` instead. + """ + warnings.warn( + "declare_static() is deprecated, use derive() instead.", + DeprecationWarning, + stacklevel=2, + ) + return derive(content) diff --git a/packages/generaltranslation/tests/static/test_declare_static.py b/packages/generaltranslation/tests/static/test_declare_static.py new file mode 100644 index 0000000..4f2e2ac --- /dev/null +++ b/packages/generaltranslation/tests/static/test_declare_static.py @@ -0,0 +1,24 @@ +"""Tests for the deprecated declare_static() function.""" + +from __future__ import annotations + +import warnings + +from generaltranslation import declare_static + + +class TestDeclareStaticDeprecation: + """Placeholder tests for declare_static() — deprecated in favour of derive().""" + + def test_emits_deprecation_warning(self) -> None: + with warnings.catch_warnings(record=True) as w: + warnings.simplefilter("always") + declare_static("hello") + assert len(w) == 1 + assert issubclass(w[0].category, DeprecationWarning) + assert "derive()" in str(w[0].message) + + def test_still_returns_value(self) -> None: + with warnings.catch_warnings(): + warnings.simplefilter("ignore", DeprecationWarning) + assert declare_static("hello") == "hello" diff --git a/packages/generaltranslation/tests/static/test_derive.py b/packages/generaltranslation/tests/static/test_derive.py new file mode 100644 index 0000000..5fec0c2 --- /dev/null +++ b/packages/generaltranslation/tests/static/test_derive.py @@ -0,0 +1,48 @@ +"""Tests for the derive() function.""" + +from __future__ import annotations + +from generaltranslation import derive + + +class TestDerive: + """Tests for derive() — the canonical marker for derivable content.""" + + def test_returns_same_string(self) -> None: + assert derive("hello") == "hello" + + def test_returns_same_int(self) -> None: + assert derive(42) == 42 + + def test_returns_same_float(self) -> None: + assert derive(3.14) == 3.14 + + def test_returns_same_list(self) -> None: + value = [1, 2, 3] + assert derive(value) is value + + def test_returns_same_dict(self) -> None: + value = {"key": "value"} + assert derive(value) is value + + def test_returns_none(self) -> None: + assert derive(None) is None + + def test_returns_same_bool(self) -> None: + assert derive(True) is True + + def test_identity_preserves_reference(self) -> None: + """derive() should be a pure identity function — same object in, same object out.""" + obj = object() + assert derive(obj) is obj + + def test_nested_structure(self) -> None: + value = {"a": [1, {"b": 2}]} + assert derive(value) is value + + def test_empty_string(self) -> None: + assert derive("") == "" + + def test_multiline_string(self) -> None: + text = "line one\nline two\nline three" + assert derive(text) == text diff --git a/packages/gt-fastapi/src/gt_fastapi/__init__.py b/packages/gt-fastapi/src/gt_fastapi/__init__.py index 9e79b27..9622b56 100644 --- a/packages/gt-fastapi/src/gt_fastapi/__init__.py +++ b/packages/gt-fastapi/src/gt_fastapi/__init__.py @@ -1,6 +1,6 @@ """FastAPI integration for General Translation.""" -from gt_i18n import declare_static, declare_var, decode_vars, get_default_locale, get_locale, get_locales, t +from gt_i18n import declare_static, declare_var, decode_vars, derive, get_default_locale, get_locale, get_locales, t from gt_fastapi._setup import initialize_gt @@ -8,6 +8,7 @@ "initialize_gt", "t", "declare_var", + "derive", "declare_static", "decode_vars", "get_locale", diff --git a/packages/gt-flask/src/gt_flask/__init__.py b/packages/gt-flask/src/gt_flask/__init__.py index 5b72fec..73334f5 100644 --- a/packages/gt-flask/src/gt_flask/__init__.py +++ b/packages/gt-flask/src/gt_flask/__init__.py @@ -1,6 +1,6 @@ """Flask integration for General Translation.""" -from gt_i18n import declare_static, declare_var, decode_vars, get_default_locale, get_locale, get_locales, t +from gt_i18n import declare_static, declare_var, decode_vars, derive, get_default_locale, get_locale, get_locales, t from gt_flask._setup import initialize_gt @@ -8,6 +8,7 @@ "initialize_gt", "t", "declare_var", + "derive", "declare_static", "decode_vars", "get_locale", diff --git a/packages/gt-i18n/src/gt_i18n/__init__.py b/packages/gt-i18n/src/gt_i18n/__init__.py index 4e8a066..7c24ada 100644 --- a/packages/gt-i18n/src/gt_i18n/__init__.py +++ b/packages/gt-i18n/src/gt_i18n/__init__.py @@ -1,6 +1,6 @@ """Python i18n library for General Translation.""" -from generaltranslation.static import declare_static, declare_var, decode_vars +from generaltranslation.static import declare_static, declare_var, decode_vars, derive from gt_i18n.helpers._locales import ( get_default_locale, @@ -49,8 +49,9 @@ "get_locale", "get_locales", "get_default_locale", - # Static variable helpers + # Derive / variable helpers "declare_var", + "derive", "declare_static", "decode_vars", ]