auth.update_user() replaces attributes rather than updating

[sjsadowski]

Describe the bug

This is not necessarily a bug, but rather undocumented behavior. When using the update_user() method, instead of updating the user_raw_meta_data when supplying the data key, it is replaced wholesale. This is manageable by merging the dicts and changing the one required, which is how I'm handling it now. However this seems non-intuitive as a replacement, not an update.

I propose simply documenting that this is a replacement action in the supabase-py docs and that for an actual update, that needs to be self-managed. I'd suggest also providing a code snippet for 'Update the user's metadata' showing both patterns.

Alternately, adding an option that specifies an update or replace in the method would also make sense. Since this could be enacted at the library level by simply adding an additional option in addition to the 'email_redirect_to' option. This is based on the function signature here:

supabase-py/src/auth/src/supabase_auth/_sync/gotrue_client.py

Line 691 in bb7ecc5

def update_user(

and the current documentation here: https://supabase.com/docs/reference/python/auth-updateuser

Reproduction

response = supabase.auth.update_user(
    {
        "data": {"hello": "world"},
    }
)
# log user metadata
response = supabase.auth.update_user(
    {
        "data": {"one": "two"},
    }
)

Steps to reproduce

1. with an active user, pull the metadata
2. update the metadata
3. verify the metadata
4. update the metadata with different keys

Library affected

supabase-auth

Library version

supabase 2.31.0

Python version

python 3.14.7

[megandas]

Hi! I'd like to work on this issue if there isn't already a PR in progress.

I plan to update the update_user() documentation to clarify that the data field replaces existing user metadata rather than merging it, and add examples showing both the replacement behavior and the recommended manual merge pattern for preserving existing metadata.