refactor: rename declare_static() to derive(), deprecate old name

.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()`

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",

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",

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)

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"

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

packages/gt-fastapi/src/gt_fastapi/__init__.py

@@ -1,13 +1,14 @@
 """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
 
 __all__ = [
     "initialize_gt",
     "t",
     "declare_var",
+    "derive",
     "declare_static",
     "decode_vars",
     "get_locale",

packages/gt-flask/src/gt_flask/__init__.py

@@ -1,13 +1,14 @@
 """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
 
 __all__ = [
     "initialize_gt",
     "t",
     "declare_var",
+    "derive",
     "declare_static",
     "decode_vars",
     "get_locale",

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",
 ]