The function _create_bound_method creates a new _StateAccessor instance for every bound method. This means each method gets its own accessor instance, which is inefficient and could lead to memory overhead when there are many methods. Consider creating a single shared accessor instance for all methods within a class, or reuse the accessor from the class-level binding.

The __new__ method override is non-standard. The typical Python way to customize instance creation is to override __call__ on the metaclass rather than replacing __new__ on the class itself. This could lead to unexpected behavior with inheritance or other Python magic methods. Consider implementing __call__ on the _SessionStateClassMeta metaclass instead.

The docstring for _StateAccessor says methods can be None, but the type annotation shows dict[str, Callable[..., Any]] | None. When None is passed, it's converted to an empty dict. Consider updating the docstring to clarify that None is only accepted as a convenience and is converted to an empty dict, or remove the None option from the type annotation and always require a dict to be passed.

The field initialization only checks if the field name exists in session state, but doesn't verify if the existing value is of the expected type. If a user manually sets st.session_state["counter"] = "not a number" before decorating a class with counter: int = 0, the decorator will silently keep the string value instead of the expected int. Consider adding type validation or at least documenting this behavior, as it could lead to unexpected runtime errors when methods try to use the field.

The deep copy for mutable defaults only handles list, dict, and set. Other mutable types like bytearray, collections.deque, or custom mutable objects won't be copied, which could lead to the same mutable default being shared across all uses. Consider using a more comprehensive approach, such as always using copy.deepcopy() for all defaults, or documenting which mutable types are supported.

The registry key $$_st_session_state_class_registry is stored in session state but is not validated against user keys. A user could theoretically manually set or delete this key, which would break the collision detection mechanism. Consider using a more protected mechanism for storing this metadata, or at minimum add validation to prevent users from accidentally or intentionally modifying this internal key.

Missing test coverage for the new @st.session_state decorator functionality. According to the custom coding guidelines, the repository should have typing tests in lib/tests/streamlit/typing/ for public API features. Consider adding a typing test file (e.g., session_state_decorator_types.py) to verify that the type annotations work correctly with mypy, including field access, method calls, and the return types of decorated classes.

Missing negative assertion. According to the custom coding guidelines for unit tests, you should include a negative/anti-regression assertion when practical. This test verifies that setting undefined attributes on the class-level works for defined fields, but it doesn't verify that attempting to set a truly undefined field raises an error or behaves correctly. Consider adding an assertion that verifies attempting to set an undefined field name fails appropriately.

Missing anti-regression check. According to the custom coding guidelines, unit tests should include negative assertions when practical. This test verifies that the dict default is copied and can be modified, but doesn't verify that creating another class with a dict default doesn't share the same dict instance. Consider adding an assertion that creates a second state class with a dict default and verifies the dicts are independent.

Missing test coverage for special methods. The implementation extracts methods using inspect.getmembers with inspect.isfunction predicate and skips methods starting with underscore. However, there's no test to verify what happens if a user defines __init__, __str__, or other special methods in their state class. Consider adding a test to document and verify the expected behavior when special methods are defined.

Methods cannot call other methods via self

High Severity

The _create_bound_method function creates a _StateAccessor with only fields, not passing the methods dictionary. This means when a method uses self to call another method (e.g., self.increment()), the _StateAccessor.__getattr__ will check an empty _methods dict and raise AttributeError. Methods can access fields via self.field_name but cannot call sibling methods like self.other_method().

Class-level undefined attribute setting silently succeeds

Medium Severity

In _SessionStateClassMeta.__setattr__, when setting an attribute that isn't a defined field, the code falls through to super().__setattr__(name, value), silently setting it as a regular class attribute. This is inconsistent with instance-level behavior in _StateAccessor.__setattr__, which raises AttributeError for undefined fields. The test test_setting_undefined_attribute_raises_error claims to verify error-raising behavior but only tests setting defined attributes, missing this bug.