Packages name change

[silentworks]

Chore

Migrate to the new package names and stop maintaining the older package names

Describe the chore

We need to fully migrate from the gotrue package name to supabase_auth. Currently, we maintain support for both packages by using a CLI workaround that copies all files and applies a regex to replace supabase_auth with gotrue before publishing.

However, this approach has become problematic-most notably, it prevents us from installing the package locally for development and testing. I’d like to deprecate gotrue entirely and move forward exclusively with supabase_auth.

The same issue exists with the transition from supafunc to supabase_functions. We're still using the old package imports in the supabase-py package to avoid breaking backward compatibility for users who may be importing exceptions or errors directly from these packages.

Additional context

Add any other context or screenshots that help clarify the task.

[grdsdev]

We should do a final release for the gotrue and supafunc packages, and include the classifiers as:

classifiers=[
    "Development Status :: 7 - Inactive",
],

Also, introduce a warning when initializing the client through the deprecated package, or when importing them (not sure if it's possible).

The warning message should state that the package name isn't supported anymore, and redirect it to the new package name.

import warnings

warnings.warn(
    "The 'old-package-name' is deprecated. Use 'new-package-name' instead.",
    UserWarning,
    stacklevel=2
)

We can then post an announcement on discussions about it, also say that old package names aren't receiving new features, and only patches for X months.

wdyt @silentworks and @o-santi ?

[o-santi]

I agree with that approach.

[developerlee79]

Hi. Are the final release(deprecation) for the gotrue and supafunc packages, and the migration to the new package names, open for contributions?

[silentworks]

@grdsdev I don't think those changes alone will do it. There is a scenario where a user might be making use of the AuthAPIError from gotrue based on knowing supabase-py installs it. I think the first step is to make all the exception imports available directly from supabase-py first.

So instead of a user importing from gotrue.errors:

from gotrue.errors import (
    AuthApiError,
    AuthInvalidCredentialsError,
    AuthWeakPasswordError,
)

they would import from supabase or even supabase.errors:

from supabase.errors import (
    AuthApiError,
    AuthInvalidCredentialsError,
    AuthWeakPasswordError,
)

There are no mention of the exceptions in the Supabase docs when it comes to the Python examples, so having all the exceptions/errors imported from the supabase-py package would be a give us more room to add these in the docs.

Also, introduce a warning when initializing the client through the deprecated package, or when importing them (not sure if it's possible).

I think we might be able to get this into the package files themselves by having some python comments which we would replace at publishing time inside the files. (I'm not keen on this, but it's an option).

[silentworks]

@developerlee79 this one will likely be handled by one of the existing maintainers as it's a bit more delicate. However if you see any other issue you wish to contribute to, feel free to open a PR and we'll review it.

[o-santi]

There is a scenario where a user might be making use of the AuthAPIError from gotrue based on knowing supabase-py installs it.

@silentworks can you explain this a bit further? supabase_auth declares these errors, so just switching from gotrue to supabase_auth in these cases should be enough. The equivalent should also be done inside supabase-py of course, but I don't think I understand your issue with it.

I think we might be able to get this into the package files themselves by having some python comments which we would replace at publishing time inside the files.

This can be done simply by including the warning in gotrue's root __init__.py, which is imported whenever anything from gotrue is imported.

A good example of a name deprecation/switch in the python community is sklearn, we might want to use it as a reference.

[o-santi]

Pushed the deprecations changes to deprecate-gotrue-package-name branch in auth-py (here) and deprecate-supafunc-package-name branch in functions-py (here).

The changes consist of:

1. Adding a deprecation warnings.warn to gotrue/__init__.py that gets printed whenever anything is imported from gotrue (including import gotrue).
2. Modifying the classifiers to say that the project is inactive
3. Modifying the README to explain that it's deprecated, add steps to switching to the new one and also a small paragraph explaining the reasoning behind.

I intend to manually push these releases, and remove the regex based automation from the CI in the respectives main branches (though this should only be done once they are officially deprecated), in order to simplify the switch and not have to add a lot of special cases to them.

[silentworks]

I think this PR can be used to demonstrate the issue I see with deprecating these packages in the next release of supabase-py. If I was always importing the errors for gotrue based on it being installed as a dependency of supabase-py, if we now remove it and start using supabase_auth as a dependency instead, this will leave a user with a broken system.

The code example below demonstrates the issue:

from supabase import AsyncClient, acreate_client
from gotrue.errors import (
    AuthApiError,
    AuthInvalidCredentialsError,
    AuthWeakPasswordError,
)

async def main():
    try:
        supabase = await acreate_client(url, key)
        user = await supabase.auth.sign_in_with_password(
            credentials={"email": email, "password": password}
        )

        if user:
            return {"message": "User signed in successfully", "user": user}
    except (AuthApiError, AuthInvalidCredentialsError) as exception:
        err = exception.to_dict()
        return {
            "error": err.get("message"),
        }

This can be easily resolved with a quick search and replace on the user's side of things, but we should try to not break their app in the first place.

My proposal here is that we would ship both gotrue and supabase_auth as dependencies, however the supabase-py will only make use of supabase_auth in it's imports, but we are leaving gotrue as a dependency so the user's existing code will still work whilst providing a deprecation warning and stating that gotrue will be removed in the next minor release of the supabase-py library. Then on the next release we can now safely remove gotrue as a dependency knowing that we gave the user the chance to migrate without breaking their existing code.

I think currently most of these Exceptions can be imported directly from supabase instead, but past examples that I've put out shows using the exceptions from the gotrue library.

The above example would now be:

from supabase import (
    AsyncClient, 
    acreate_client,
    AuthApiError,
    AuthInvalidCredentialsError,
    AuthWeakPasswordError,
)

async def main():
    try:
        supabase = await acreate_client(url, key)
        user = await supabase.auth.sign_in_with_password(
            credentials={"email": email, "password": password}
        )

        if user:
            return {"message": "User signed in successfully", "user": user}
    except (AuthApiError, AuthInvalidCredentialsError) as exception:
        err = exception.to_dict()
        return {
            "error": err.get("message"),
        }