django-supabase 1.0.0__tar.gz

django_supabase-1.0.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.3
+Name: django-supabase
+Version: 1.0.0
+Summary: A lightweight django package designed to connect Django applications to Supabase Auth, Database Access, and Storage
+Author: Lakan
+Author-email: Lakan <leydotpy.dev@gmail.com>
+Requires-Dist: celery>=5.6.3
+Requires-Dist: django>=6.0.6
+Requires-Dist: django-celery-beat>=2.9.0
+Requires-Dist: django-celery-results>=2.6.0
+Requires-Dist: django-guardian>=3.3.2
+Requires-Dist: django-redis>=7.0.0
+Requires-Dist: djangorestframework>=3.17.1
+Requires-Dist: gunicorn>=26.0.0
+Requires-Dist: pyjwt[crypto]>=2.10.0
+Requires-Dist: redis>=8.0.0
+Requires-Dist: supabase>=2.31.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Django Supabase 
+
+Professional, production-ready Supabase integration for Django.
+
+## Features
+
+- 🔐 **Authentication**: Seamless Supabase Auth + Django User model sync
+- 💾 **Database**: Direct PostgreSQL connection with Django ORM
+- 📦 **Storage**: Django storage backends for Supabase Storage
+- 🚀 **Production-Ready**: Connection pooling, caching, error handling
+- 🔧 **Django-Native**: Uses Django's ecosystem and patterns
+
+## Installation
+
+```bash
+pip install django-supabase
+```
+
+## Quick Setup
+### Add to INSTALLED_APPS:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    'django_supabase',
+    'django_supabase.auth',
+]
+```
+
+## Configure Settings
+
+```python
+SUPABASE_URL = 'https://your-project.supabase.co'
+SUPABASE_KEY = 'your-publishable-or-anon-key'
+SUPABASE_SECRET_KEY = 'your-secret-or-service-role-key'  # server-side only
+
+# Recommended default: ask Supabase Auth to validate bearer tokens.
+SUPABASE_JWT_VERIFICATION = 'auth_server'
+
+# Optional for projects using asymmetric JWT signing keys:
+# SUPABASE_JWT_VERIFICATION = 'jwks'
+# SUPABASE_JWT_ALGORITHMS = ['RS256', 'ES256']
+
+# Legacy/local-only fallback for HS256 shared-secret verification:
+# SUPABASE_JWT_VERIFICATION = 'jwt_secret'
+# SUPABASE_JWT_SECRET = 'your-jwt-secret'
+
+AUTH_USER_MODEL = 'supabase_auth.SupabaseUser'
+
+AUTHENTICATION_BACKENDS = [
+    'django_supabase.auth.backends.SupabaseAuthBackend',
+    'django.contrib.auth.backends.ModelBackend',
+]
+
+DATABASES = {
+    'default': {
+        'ENGINE': 'django_supabase.db.engine.SupabasePostgreSQLEngine',
+        'NAME': 'postgres',
+        'USER': 'postgres',
+        'PASSWORD': 'your-password',
+        'HOST': 'db.your-project.supabase.co',
+        'PORT': 5432,
+    }
+}
+
+STORAGES = {
+    'default': {
+        'BACKEND': 'django_supabase.storage.backends.SupabaseMediaStorage',
+    },
+    'staticfiles': {
+        'BACKEND': 'django_supabase.storage.backends.SupabaseStaticStorage',
+    },
+}
+```
+
+## Run Migrations
+
+```bash
+python manage.py migrate
+python manage.py create_storage_buckets
+```
+
+# Usage Example
+## Authentication
+
+```python
+from django.contrib.auth import authenticate
+
+# Email/Password login
+user = authenticate(email='user@example.com', password='password')
+
+# JWT Token authentication (in views)
+# Token automatically extracted from Authorization: Bearer <token>
+```
+
+## Frontend OAuth
+
+Use Supabase Auth in the frontend with a publishable key. After OAuth login,
+send the Supabase session access token to Django:
+
+```javascript
+const { data, error } = await supabase.auth.signInWithOAuth({
+  provider: 'google',
+  options: { redirectTo: 'https://your-frontend.example.com/auth/callback' },
+})
+
+const { data: sessionData } = await supabase.auth.getSession()
+
+await fetch('/api/me/', {
+  headers: {
+    Authorization: `Bearer ${sessionData.session.access_token}`,
+  },
+})
+```
+
+Django validates the bearer token through `SupabaseAuthMiddleware` and syncs the
+local user by Supabase `sub` / `user.id`, not by email alone.
+
+## File Upload
+
+```python
+from django_supabase.storage.utils import upload_file_to_supabase
+
+file = ...
+
+url = upload_file_to_supabase(file, 'media', path='uploads/')
+
+```
+
+## Direct Supabase Queries
+
+```python
+from django_supabase.db.client import get_supabase_client
+
+supabase = get_supabase_client()
+response = supabase.table('posts').select('*').execute()
+```
+
+### Test
+
+```python
+# supabase_integration/tests.py
+from django.test import TestCase
+from django.contrib.auth import get_user_model
+from django_supabase.db.client import get_supabase_client
+
+User = get_user_model()
+
+class SupabaseIntegrationTestCase(TestCase):
+    """Base test case with Supabase utilities"""
+    
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+        cls.supabase = get_supabase_client()
+    
+    def create_test_user(self, email='test@example.com'):
+        """Helper to create test users"""
+        return User.objects.create_user(
+            username=email,
+            email=email,
+            password='testpass123'
+        )
+```

django_supabase-1.0.0/README.md

@@ -0,0 +1,164 @@
+# Django Supabase 
+
+Professional, production-ready Supabase integration for Django.
+
+## Features
+
+- 🔐 **Authentication**: Seamless Supabase Auth + Django User model sync
+- 💾 **Database**: Direct PostgreSQL connection with Django ORM
+- 📦 **Storage**: Django storage backends for Supabase Storage
+- 🚀 **Production-Ready**: Connection pooling, caching, error handling
+- 🔧 **Django-Native**: Uses Django's ecosystem and patterns
+
+## Installation
+
+```bash
+pip install django-supabase
+```
+
+## Quick Setup
+### Add to INSTALLED_APPS:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    'django_supabase',
+    'django_supabase.auth',
+]
+```
+
+## Configure Settings
+
+```python
+SUPABASE_URL = 'https://your-project.supabase.co'
+SUPABASE_KEY = 'your-publishable-or-anon-key'
+SUPABASE_SECRET_KEY = 'your-secret-or-service-role-key'  # server-side only
+
+# Recommended default: ask Supabase Auth to validate bearer tokens.
+SUPABASE_JWT_VERIFICATION = 'auth_server'
+
+# Optional for projects using asymmetric JWT signing keys:
+# SUPABASE_JWT_VERIFICATION = 'jwks'
+# SUPABASE_JWT_ALGORITHMS = ['RS256', 'ES256']
+
+# Legacy/local-only fallback for HS256 shared-secret verification:
+# SUPABASE_JWT_VERIFICATION = 'jwt_secret'
+# SUPABASE_JWT_SECRET = 'your-jwt-secret'
+
+AUTH_USER_MODEL = 'supabase_auth.SupabaseUser'
+
+AUTHENTICATION_BACKENDS = [
+    'django_supabase.auth.backends.SupabaseAuthBackend',
+    'django.contrib.auth.backends.ModelBackend',
+]
+
+DATABASES = {
+    'default': {
+        'ENGINE': 'django_supabase.db.engine.SupabasePostgreSQLEngine',
+        'NAME': 'postgres',
+        'USER': 'postgres',
+        'PASSWORD': 'your-password',
+        'HOST': 'db.your-project.supabase.co',
+        'PORT': 5432,
+    }
+}
+
+STORAGES = {
+    'default': {
+        'BACKEND': 'django_supabase.storage.backends.SupabaseMediaStorage',
+    },
+    'staticfiles': {
+        'BACKEND': 'django_supabase.storage.backends.SupabaseStaticStorage',
+    },
+}
+```
+
+## Run Migrations
+
+```bash
+python manage.py migrate
+python manage.py create_storage_buckets
+```
+
+# Usage Example
+## Authentication
+
+```python
+from django.contrib.auth import authenticate
+
+# Email/Password login
+user = authenticate(email='user@example.com', password='password')
+
+# JWT Token authentication (in views)
+# Token automatically extracted from Authorization: Bearer <token>
+```
+
+## Frontend OAuth
+
+Use Supabase Auth in the frontend with a publishable key. After OAuth login,
+send the Supabase session access token to Django:
+
+```javascript
+const { data, error } = await supabase.auth.signInWithOAuth({
+  provider: 'google',
+  options: { redirectTo: 'https://your-frontend.example.com/auth/callback' },
+})
+
+const { data: sessionData } = await supabase.auth.getSession()
+
+await fetch('/api/me/', {
+  headers: {
+    Authorization: `Bearer ${sessionData.session.access_token}`,
+  },
+})
+```
+
+Django validates the bearer token through `SupabaseAuthMiddleware` and syncs the
+local user by Supabase `sub` / `user.id`, not by email alone.
+
+## File Upload
+
+```python
+from django_supabase.storage.utils import upload_file_to_supabase
+
+file = ...
+
+url = upload_file_to_supabase(file, 'media', path='uploads/')
+
+```
+
+## Direct Supabase Queries
+
+```python
+from django_supabase.db.client import get_supabase_client
+
+supabase = get_supabase_client()
+response = supabase.table('posts').select('*').execute()
+```
+
+### Test
+
+```python
+# supabase_integration/tests.py
+from django.test import TestCase
+from django.contrib.auth import get_user_model
+from django_supabase.db.client import get_supabase_client
+
+User = get_user_model()
+
+class SupabaseIntegrationTestCase(TestCase):
+    """Base test case with Supabase utilities"""
+    
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+        cls.supabase = get_supabase_client()
+    
+    def create_test_user(self, email='test@example.com'):
+        """Helper to create test users"""
+        return User.objects.create_user(
+            username=email,
+            email=email,
+            password='testpass123'
+        )
+```

django_supabase-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "django-supabase"
+version = "1.0.0"
+description = "A lightweight django package designed to connect Django applications to Supabase Auth, Database Access, and Storage"
+readme = "README.md"
+authors = [
+    { name = "Lakan", email = "leydotpy.dev@gmail.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "celery>=5.6.3",
+    "django>=6.0.6",
+    "django-celery-beat>=2.9.0",
+    "django-celery-results>=2.6.0",
+    "django-guardian>=3.3.2",
+    "django-redis>=7.0.0",
+    "djangorestframework>=3.17.1",
+    "gunicorn>=26.0.0",
+    "pyjwt[crypto]>=2.10.0",
+    "redis>=8.0.0",
+    "supabase>=2.31.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.7,<0.10.0"]
+build-backend = "uv_build"

django_supabase-1.0.0/src/django_supabase/__init__.py

@@ -0,0 +1,4 @@
+__version__ = '1.0.0'
+
+default_app_config = 'django_supabase.apps.DjangoSupabaseConfig'
+

django_supabase-1.0.0/src/django_supabase/apps.py

@@ -0,0 +1,13 @@
+from django.apps import AppConfig
+
+
+class DjangoSupabaseConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'django_supabase'
+    verbose_name = 'Supabase Integration'
+
+    def ready(self):
+        """Initialize Supabase integration on Django startup"""
+        from .conf import supabase_settings
+        # Validate settings on startup
+        supabase_settings.configure()

django_supabase-1.0.0/src/django_supabase/auth/__init__.py

@@ -0,0 +1 @@
+default_app_config = 'django_supabase.auth.apps.SupabaseAuthConfig'

django_supabase-1.0.0/src/django_supabase/auth/apps.py

@@ -0,0 +1,8 @@
+from django.apps import AppConfig
+
+
+class SupabaseAuthConfig(AppConfig):
+    name = 'django_supabase.auth'
+    label = 'supabase_auth'
+    verbose_name = 'Supabase User'
+    verbose_name_plural = 'Supabase Users'

django_supabase-1.0.0/src/django_supabase/auth/backends.py

@@ -0,0 +1,121 @@
+import logging
+
+from django.conf import settings
+from django.contrib.auth import get_user_model
+from django.contrib.auth.backends import BaseBackend
+from supabase import create_client
+
+from .sync import sync_user_from_claims, sync_user_from_supabase
+from .tokens import (
+    SupabaseTokenError,
+    token_algorithm,
+    verify_token_with_jwks,
+    verify_token_with_secret,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SupabaseAuthBackend(BaseBackend):
+    """
+    Authenticates against Supabase and syncs with Django User model
+    """
+
+    def __init__(self):
+        self.supabase = create_client(
+            settings.SUPABASE_URL,
+            settings.SUPABASE_KEY
+        )
+
+    def authenticate(self, request, token=None, **credentials):
+        if token:
+            return self._authenticate_token(token)
+
+        # Email/password auth
+        email = credentials.get('email')
+        password = credentials.get('password')
+
+        if not email or not password:
+            return None
+
+        try:
+            response = self.supabase.auth.sign_in_with_password({
+                "email": email,
+                "password": password
+            })
+
+            if response.user:
+                user, created = self._sync_user(response.user)
+                return user
+
+        except Exception as exc:
+            logger.debug('Supabase email/password authentication failed: %s', exc)
+            return None
+
+    def _authenticate_token(self, token):
+        """Validate JWT token from Supabase"""
+        verification_mode = getattr(
+            settings,
+            'SUPABASE_JWT_VERIFICATION',
+            'auth_server',
+        ).lower()
+
+        if verification_mode == 'auth_server':
+            return self._authenticate_token_with_auth_server(token)
+
+        if verification_mode == 'jwks':
+            return self._authenticate_token_with_jwks(token)
+
+        if verification_mode == 'jwt_secret':
+            return self._authenticate_token_with_secret(token)
+
+        logger.error('Unsupported SUPABASE_JWT_VERIFICATION mode: %s', verification_mode)
+        return None
+
+    def _authenticate_token_with_auth_server(self, token):
+        try:
+            response = self.supabase.auth.get_user(token)
+            supabase_user = getattr(response, 'user', None)
+            if not supabase_user:
+                return None
+            user, _ = sync_user_from_supabase(supabase_user)
+            return user
+        except Exception as exc:
+            logger.debug('Supabase Auth server token validation failed: %s', exc)
+            return None
+
+    def _authenticate_token_with_jwks(self, token):
+        try:
+            if token_algorithm(token) == 'HS256':
+                logger.warning(
+                    'Received HS256 token while SUPABASE_JWT_VERIFICATION=jwks'
+                )
+                return None
+            payload = verify_token_with_jwks(token)
+            if getattr(settings, 'SUPABASE_SYNC_USER_FROM_AUTH_ON_TOKEN', False):
+                return self._authenticate_token_with_auth_server(token)
+            user, _ = sync_user_from_claims(payload)
+            return user
+        except SupabaseTokenError as exc:
+            logger.debug('Supabase JWKS token validation failed: %s', exc)
+            return None
+
+    def _authenticate_token_with_secret(self, token):
+        try:
+            payload = verify_token_with_secret(token)
+            user, _ = sync_user_from_claims(payload)
+            return user
+        except SupabaseTokenError as exc:
+            logger.debug('Supabase JWT secret token validation failed: %s', exc)
+            return None
+
+    def _sync_user(self, supabase_user):
+        """Sync Supabase user with Django User model"""
+        return sync_user_from_supabase(supabase_user)
+
+    def get_user(self, user_id):
+        User = get_user_model()
+        try:
+            return User.objects.get(pk=user_id)
+        except User.DoesNotExist:
+            return None

django_supabase-1.0.0/src/django_supabase/auth/middleware.py

@@ -0,0 +1,33 @@
+from django.contrib.auth import authenticate
+from django.contrib.auth.middleware import get_user
+from django.utils.functional import SimpleLazyObject
+
+
+class SupabaseAuthMiddleware:
+    """
+    Middleware to authenticate requests using Supabase JWT tokens
+    """
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        # Extract token from Authorization header
+        auth_header = request.META.get('HTTP_AUTHORIZATION', '')
+
+        scheme, _, token = auth_header.partition(' ')
+
+        if scheme.lower() == 'bearer' and token:
+            request.user = SimpleLazyObject(
+                lambda: self._authenticate_token(request, token.strip())
+            )
+        else:
+            request.user = SimpleLazyObject(lambda: get_user(request))
+
+        response = self.get_response(request)
+        return response
+
+    def _authenticate_token(self, request, token):
+        """Authenticate using token"""
+        user = authenticate(request, token=token)
+        return user or get_user(request)

django_supabase-1.0.0/src/django_supabase/auth/migrations/0001_initial.py

@@ -0,0 +1,63 @@
+# Generated by Django 6.0.6 on 2026-06-11 12:57
+
+import django.contrib.auth.models
+import django.contrib.auth.validators
+import django.utils.timezone
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('auth', '0012_alter_user_first_name_max_length'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='SupabaseUser',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('password', models.CharField(max_length=128, verbose_name='password')),
+                ('last_login', models.DateTimeField(blank=True, null=True, verbose_name='last login')),
+                ('is_superuser', models.BooleanField(default=False, help_text='Designates that this user has all permissions without explicitly assigning them.', verbose_name='superuser status')),
+                ('username', models.CharField(error_messages={'unique': 'A user with that username already exists.'}, help_text='Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.', max_length=150, unique=True, validators=[django.contrib.auth.validators.UnicodeUsernameValidator()], verbose_name='username')),
+                ('first_name', models.CharField(blank=True, max_length=150, verbose_name='first name')),
+                ('last_name', models.CharField(blank=True, max_length=150, verbose_name='last name')),
+                ('email', models.EmailField(blank=True, max_length=254, verbose_name='email address')),
+                ('is_staff', models.BooleanField(default=False, help_text='Designates whether the user can log into this admin site.', verbose_name='staff status')),
+                ('is_active', models.BooleanField(default=True, help_text='Designates whether this user should be treated as active. Unselect this instead of deleting accounts.', verbose_name='active')),
+                ('date_joined', models.DateTimeField(default=django.utils.timezone.now, verbose_name='date joined')),
+                ('supabase_id', models.UUIDField(blank=True, db_index=True, null=True, unique=True)),
+                ('phone', models.CharField(blank=True, max_length=32)),
+                ('display_name', models.CharField(blank=True, max_length=150)),
+                ('avatar_url', models.URLField(blank=True)),
+                ('aud', models.CharField(blank=True, max_length=64)),
+                ('role', models.CharField(blank=True, max_length=64)),
+                ('provider', models.CharField(blank=True, max_length=64)),
+                ('providers', models.JSONField(blank=True, default=list)),
+                ('app_metadata', models.JSONField(blank=True, default=dict)),
+                ('user_metadata', models.JSONField(blank=True, default=dict)),
+                ('metadata', models.JSONField(blank=True, default=dict)),
+                ('identities', models.JSONField(blank=True, default=list)),
+                ('email_confirmed_at', models.DateTimeField(blank=True, null=True)),
+                ('phone_confirmed_at', models.DateTimeField(blank=True, null=True)),
+                ('last_sign_in_at', models.DateTimeField(blank=True, null=True)),
+                ('supabase_created_at', models.DateTimeField(blank=True, null=True)),
+                ('supabase_updated_at', models.DateTimeField(blank=True, null=True)),
+                ('is_anonymous', models.BooleanField(default=False)),
+                ('is_sso_user', models.BooleanField(default=False)),
+                ('banned_until', models.DateTimeField(blank=True, null=True)),
+                ('groups', models.ManyToManyField(blank=True, help_text='The groups this user belongs to. A user will get all permissions granted to each of their groups.', related_name='user_set', related_query_name='user', to='auth.group', verbose_name='groups')),
+                ('user_permissions', models.ManyToManyField(blank=True, help_text='Specific permissions for this user.', related_name='user_set', related_query_name='user', to='auth.permission', verbose_name='user permissions')),
+            ],
+            options={
+                'db_table': 'auth_user',
+                'swappable': 'AUTH_USER_MODEL',
+            },
+            managers=[
+                ('objects', django.contrib.auth.models.UserManager()),
+            ],
+        ),
+    ]

django_supabase-1.0.0/src/django_supabase/auth/models.py

@@ -0,0 +1,36 @@
+from django.contrib.auth.models import AbstractUser
+from django.db import models
+
+class SupabaseUser(AbstractUser):
+    """
+    Extended user model to store Supabase-specific data
+    """
+    supabase_id = models.UUIDField(unique=True, null=True, blank=True, db_index=True)
+    phone = models.CharField(max_length=32, blank=True)
+    display_name = models.CharField(max_length=150, blank=True)
+    avatar_url = models.URLField(blank=True)
+    aud = models.CharField(max_length=64, blank=True)
+    role = models.CharField(max_length=64, blank=True)
+    provider = models.CharField(max_length=64, blank=True)
+    providers = models.JSONField(default=list, blank=True)
+    app_metadata = models.JSONField(default=dict, blank=True)
+    user_metadata = models.JSONField(default=dict, blank=True)
+    metadata = models.JSONField(default=dict, blank=True)
+    identities = models.JSONField(default=list, blank=True)
+    email_confirmed_at = models.DateTimeField(null=True, blank=True)
+    phone_confirmed_at = models.DateTimeField(null=True, blank=True)
+    last_sign_in_at = models.DateTimeField(null=True, blank=True)
+    supabase_created_at = models.DateTimeField(null=True, blank=True)
+    supabase_updated_at = models.DateTimeField(null=True, blank=True)
+    is_anonymous = models.BooleanField(default=False)
+    is_sso_user = models.BooleanField(default=False)
+    banned_until = models.DateTimeField(null=True, blank=True)
+
+    class Meta:
+        db_table = 'auth_user'  # Keep Django's default table name
+        swappable = 'AUTH_USER_MODEL'
+
+    @property
+    def name(self):
+        return self.display_name or self.get_full_name() or self.username
+