docs: add module docstring with quick-start example and complete PyPI metadata

- Replace one-line module docstring with comprehensive quick-start guide
  covering sync, async, and error handling usage patterns
- Add Framework :: Pydantic :: 2 and Topic classifiers to pyproject.toml
- Add keywords for PyPI discoverability
- Add project.urls section with Homepage, Repository, Documentation, Bug Tracker

sdks/implementations/python/pyproject.toml

@@ -19,7 +19,11 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Typing :: Typed",
+    "Framework :: Pydantic :: 2",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Security",
 ]
+keywords = ["stack-auth", "authentication", "sdk", "users", "teams", "python"]
 dependencies = [
     "httpx>=0.27,<1.0",
     "pyjwt[crypto]>=2.9,<3.0",
@@ -36,6 +40,12 @@ dev = [
     "pytest-cov>=5.0",
 ]
 
+[project.urls]
+Homepage = "https://github.com/stack-auth/stack"
+Repository = "https://github.com/stack-auth/stack"
+Documentation = "https://docs.stack-auth.com"
+"Bug Tracker" = "https://github.com/stack-auth/stack/issues"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/stack_auth"]
 

sdks/implementations/python/src/stack_auth/__init__.py

@@ -1,4 +1,54 @@
-"""Stack Auth Python SDK."""
+"""Stack Auth Python SDK.
+
+A type-safe Python client for the Stack Auth API, providing both
+synchronous and asynchronous interfaces for user management, team
+management, permissions, API keys, OAuth, payments, email, and more.
+
+Quick Start:
+    Install the package::
+
+        pip install stack-auth
+
+    Synchronous usage with :class:`StackServerApp`::
+
+        from stack_auth import StackServerApp
+
+        app = StackServerApp(
+            project_id="my-project-id",
+            secret_server_key="ssk_...",
+        )
+        user = app.get_user("user-123")
+        users = app.list_users(limit=10)
+        app.close()
+
+    Async usage with :class:`AsyncStackServerApp`::
+
+        from stack_auth import AsyncStackServerApp
+
+        async with AsyncStackServerApp(
+            project_id="my-project-id",
+            secret_server_key="ssk_...",
+        ) as app:
+            user = await app.get_user("user-123")
+            users = await app.list_users(limit=10)
+
+    Error handling with :class:`StackAuthError`::
+
+        from stack_auth import StackServerApp, StackAuthError, NotFoundError
+
+        app = StackServerApp(project_id="...", secret_server_key="...")
+        try:
+            user = app.create_user(primary_email="[email protected]")
+        except StackAuthError as e:
+            print(f"API error: {e}")
+
+Key Features:
+    - **Type-safe**: All responses are validated Pydantic v2 models.
+    - **Sync + Async**: Choose :class:`StackServerApp` or
+      :class:`AsyncStackServerApp` based on your application's needs.
+    - **Full API coverage**: Users, teams, permissions, sessions,
+      API keys, OAuth, payments, email, and data vault.
+"""
 
 from stack_auth._app import AsyncStackServerApp, StackServerApp
 from stack_auth._auth import (