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

[moss-bryophyta]

Mirrors generaltranslation/gt#1062 for the Python libraries.

Changes

• Add new derive() function as the canonical replacement for declare_static()
• declare_static() now delegates to derive() and emits a DeprecationWarning
• Export derive from all packages: generaltranslation, gt-i18n, gt-fastapi, gt-flask
• Update comments from "Static" to "Derive / variable helpers" where referring to the declare static concept

Greptile Summary

This PR introduces derive() as the new canonical replacement for declare_static() across all four packages (generaltranslation, gt-i18n, gt-fastapi, gt-flask), mirroring a parallel change in the JS/TS libraries. declare_static() is preserved as a deprecated wrapper that delegates to derive() and emits a DeprecationWarning, ensuring backwards compatibility.

Key changes:

• New _derive.py replaces the deleted _declare_static.py, housing both derive() (canonical) and declare_static() (deprecated shim with stacklevel=2 correctly set)
• derive exported from all public package __all__ lists consistently
• New comprehensive test suite: test_derive.py covers identity semantics across all common Python types; test_declare_static.py verifies the deprecation warning and passthrough behaviour
• Section comment updated from # Static to # Derive / variable helpers across package __init__.py files

Minor observations:

• The declare_static docstring's first line duplicates derive()'s summary without flagging the deprecation upfront — worth clarifying for API reference readers
• The assert len(w) == 1 assertion in test_emits_deprecation_warning is slightly brittle; using a predicate-based check would be more robust against future incidental warnings

Confidence Score: 5/5

• This PR is safe to merge — it is a clean, backwards-compatible deprecation refactor with no logic changes to existing behaviour.
• The core change is a straightforward rename with a deprecation shim. The identity function semantics are unchanged, the deprecation warning uses the correct stacklevel, all packages are updated consistently, and a solid test suite is included. Only minor style suggestions were found — no bugs or regressions.
• No files require special attention.

Important Files Changed

Filename	Overview
packages/generaltranslation/src/generaltranslation/static/_derive.py	New file introducing derive() as the canonical identity-marker function and declare_static() as a deprecated wrapper; stacklevel=2 is correctly set; minor docstring clarity issue on declare_static's first line.
packages/generaltranslation/src/generaltranslation/static/init.py	Import source correctly switched from deleted _declare_static.py to _derive.py; both derive and declare_static added to all.
packages/generaltranslation/src/generaltranslation/init.py	derive correctly imported and added to all; section comment updated to "Derive / variable helpers".
packages/generaltranslation/tests/static/test_declare_static.py	New deprecation tests; exact len(w)==1 assertion is slightly fragile but not a critical issue in a controlled test environment.
packages/generaltranslation/tests/static/test_derive.py	Comprehensive identity-function tests covering strings, ints, floats, bools, None, dicts, lists, and nested structures; all correct.
packages/gt-i18n/src/gt_i18n/init.py	derive correctly added to imports and all; section comment updated consistently.
packages/gt-fastapi/src/gt_fastapi/init.py	derive added to import line and all; no issues.
packages/gt-flask/src/gt_flask/init.py	derive added to import line and all; mirrors gt-fastapi changes cleanly.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["User code calls\ndeclare_static(content)"] -->|deprecated path| B["declare_static()\nin _derive.py"]
    B --> C["warnings.warn(DeprecationWarning,\nstacklevel=2)"]
    C --> D["derive(content)"]
    E["User code calls\nderive(content)"] -->|canonical path| D
    D --> F["return content\n(identity function)"]

    subgraph Packages ["Re-exported from all packages"]
        G[generaltranslation]
        H[gt-i18n]
        I[gt-fastapi]
        J[gt-flask]
    end

    D -.->|exported via| G
    D -.->|exported via| H
    D -.->|exported via| I
    D -.->|exported via| J

Loading

Comments Outside Diff (1)

1. packages/generaltranslation/src/generaltranslation/__init__.py, line 51-58 (link)

   derive import breaks alphabetical ordering

   The existing import block appears to be sorted alphabetically (condense_vars, declare_static, declare_var, decode_vars, …). Inserting derive between declare_var and decode_vars breaks that order — alphabetically decode_vars (deco…) should precede derive (deri…).

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: packages/generaltranslation/src/generaltranslation/__init__.py
   Line: 51-58
   
   Comment:
   **`derive` import breaks alphabetical ordering**
   
   The existing import block appears to be sorted alphabetically (`condense_vars`, `declare_static`, `declare_var`, `decode_vars`, …). Inserting `derive` between `declare_var` and `decode_vars` breaks that order — alphabetically `decode_vars` (`deco…`) should precede `derive` (`deri…`).
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix All With AI

This is a comment left during a code review.
Path: packages/generaltranslation/tests/static/test_declare_static.py
Line: 17

Comment:
**Fragile exact-count assertion**

`assert len(w) == 1` can fail if any other code touched during the test emits a `DeprecationWarning` (e.g., from an import side-effect or a future dependency update). A more robust pattern is to assert that *at least one* matching warning was emitted, or to narrow the assertion to check only warnings from the expected source module:

```suggestion
            assert any(
                issubclass(warning.category, DeprecationWarning)
                and "derive()" in str(warning.message)
                for warning in w
            )
```

This also makes the separate `assert "derive()" in str(w[0].message)` check redundant and the two assertions can be collapsed into one.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: packages/generaltranslation/src/generaltranslation/static/_derive.py
Line: 15-16

Comment:
**Docstring first line doesn't mention deprecation**

`declare_static`'s one-liner summary ("Mark *content* as derivable (statically analyzable).") is identical to `derive()`'s. A reader scanning quick-reference docs won't immediately see that this function is deprecated — the `.. deprecated::` block is easy to miss further down. Consider making the deprecation explicit in the first line:

```suggestion
def declare_static(content: object) -> object:
    """Deprecated: use :func:`derive` instead.

    .. deprecated::
        Use :func:`derive` instead.
    """
```

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: "chore: add changeset..."}

Greptile also left 1 inline comment on this PR.

[ErnestM1234]

@greptileai plz review