fix: bugs in example apps

basics/fastapi/app/main.py

@@ -3,7 +3,6 @@
 from contextlib import asynccontextmanager
 from pathlib import Path
 
-import posthog
 from fastapi import FastAPI, Request
 from fastapi.responses import HTMLResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
@@ -13,6 +12,7 @@
 from app.database import SessionLocal, init_db
 from app.middleware import PostHogMiddleware
 from app.models import User
+from app.posthog_client import posthog
 from app.routers import api, main
 
 settings = get_settings()
@@ -25,12 +25,6 @@
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     """Application lifespan events for startup/shutdown."""
-    # Startup: Initialize PostHog
-    if not settings.posthog_disabled:
-        posthog.api_key = settings.posthog_project_token
-        posthog.host = settings.posthog_host
-        posthog.debug = settings.debug
-
     # Initialize database and seed default user
     init_db()
     db = SessionLocal()
@@ -47,9 +41,8 @@ async def lifespan(app: FastAPI):
 
     yield
 
-    # Shutdown: Flush PostHog events
-    if not settings.posthog_disabled:
-        posthog.flush()
+    # Shutdown: Gracefully close PostHog client
+    posthog.shutdown()
 
 
 app = FastAPI(

basics/fastapi/app/middleware.py

@@ -6,7 +6,9 @@
 from http.cookies import SimpleCookie
 from typing import Callable, Optional
 
-from posthog import identify_context, new_context, tag
+from posthog import identify_context, tag
+
+from app.posthog_client import posthog
 
 from app.config import get_settings
 from app.database import SessionLocal
@@ -34,9 +36,9 @@ async def __call__(self, scope, receive, send):
 
         user = self._get_user_from_scope(scope)
 
-        with new_context():
+        with posthog.new_context():
             if user:
-                identify_context(user.email)
+                identify_context(str(user.id))
                 tag("email", user.email)
                 tag("is_staff", user.is_staff)
 

basics/fastapi/app/posthog_client.py

@@ -0,0 +1,29 @@
+"""PostHog client initialization using the documented Posthog() constructor.
+
+Creates a shared client instance that routes and middleware import from.
+@see https://posthog.com/docs/libraries/python
+"""
+
+from posthog import Posthog
+
+from app.config import get_settings
+
+settings = get_settings()
+
+# Initialize PostHog using the documented constructor pattern.
+# This creates a client instance that all routes and middleware share.
+# @see https://posthog.com/docs/libraries/python
+if not settings.posthog_disabled:
+    posthog = Posthog(
+        settings.posthog_project_token,
+        host=settings.posthog_host,
+        debug=settings.debug,
+        enable_exception_autocapture=True,
+    )
+else:
+    # Create a disabled client so imports don't break
+    posthog = Posthog(
+        "disabled",
+        host=settings.posthog_host,
+        disabled=True,
+    )

basics/fastapi/app/routers/api.py

@@ -2,10 +2,10 @@
 
 from typing import Annotated
 
-import posthog
 from fastapi import APIRouter, Cookie, Form, Query
 from fastapi.responses import JSONResponse
-from posthog import capture
+
+from app.posthog_client import posthog
 
 from app.dependencies import RequiredUser
 
@@ -23,7 +23,7 @@ async def consider_burrito(
     safe_count = max(0, min(burrito_count, MAX_BURRITO_COUNT))
     new_count = safe_count + 1
 
-    capture("burrito_considered", properties={"total_considerations": new_count})
+    posthog.capture("burrito_considered", distinct_id=str(current_user.id), properties={"total_considerations": new_count})
 
     response = JSONResponse({"success": True, "count": new_count})
     response.set_cookie(
@@ -47,7 +47,7 @@ async def test_error(
         raise Exception("Test exception from critical operation")
     except Exception as e:
         if should_capture:
-            event_id = posthog.capture_exception(e)
+            event_id = posthog.capture_exception(e, distinct_id=str(current_user.id))
             return JSONResponse(
                 {
                     "error": "Operation failed",
@@ -83,9 +83,10 @@ async def trigger_error(
         else:
             raise Exception(error_message)
     except Exception as e:
-        posthog.capture_exception(e)
-        capture(
+        posthog.capture_exception(e, distinct_id=str(current_user.id))
+        posthog.capture(
             "error_triggered",
+            distinct_id=str(current_user.id),
             properties={"error_type": safe_error_type, "error_message": error_message},
         )
 
@@ -123,12 +124,12 @@ async def generate_activity_report(
 
     row_count = len(report_data)
 
-    capture(
+    posthog.capture(
         "report_generated",
+        distinct_id=str(current_user.id),
         properties={
             "report_type": safe_report_type,
             "row_count": row_count,
-            "username": current_user.email,
         },
     )
 

basics/fastapi/app/routers/main.py

@@ -3,11 +3,11 @@
 from pathlib import Path
 from typing import Annotated
 
-import posthog
 from fastapi import APIRouter, Cookie, Depends, Form, Request
 from fastapi.responses import HTMLResponse, RedirectResponse
 from fastapi.templating import Jinja2Templates
-from posthog import capture
+
+from app.posthog_client import posthog
 
 from app.dependencies import (
     CurrentUser,
@@ -47,13 +47,13 @@ async def login(
 
     if user:
         is_new_user = user.record_login(db)
-        posthog.identify(user.email, {"email": user.email, "is_staff": user.is_staff})
         posthog.capture(
-            user.email,
             "user_logged_in",
+            distinct_id=str(user.id),
             properties={
-                "username": user.email,
                 "is_new_user": is_new_user,
+                "$set": {"email": user.email, "is_staff": user.is_staff},
+                "$set_once": {"first_login_date": user.date_joined.isoformat()},
             },
         )
 
@@ -112,13 +112,13 @@ async def signup(
     # Create new user
     user = User.create_user(db, email=email, password=password, is_staff=False)
 
-    posthog.identify(user.email, {"email": user.email, "is_staff": user.is_staff})
     posthog.capture(
-        user.email,
         "user_signed_up",
+        distinct_id=str(user.id),
         properties={
-            "username": user.email,
             "signup_method": "form",
+            "$set": {"email": user.email, "is_staff": user.is_staff},
+            "$set_once": {"first_login_date": user.date_joined.isoformat()},
         },
     )
 
@@ -136,7 +136,7 @@ async def signup(
 @router.get("/logout")
 async def logout(current_user: RequiredUser):
     """Logout and capture event."""
-    capture("user_logged_out")
+    posthog.capture("user_logged_out", distinct_id=str(current_user.id))
 
     response = RedirectResponse(url="/", status_code=302)
     response.delete_cookie(key="session_token")
@@ -149,12 +149,12 @@ async def dashboard(
     current_user: RequiredUser,
 ):
     """Dashboard with feature flag demonstration."""
-    capture("dashboard_viewed", properties={"is_staff": current_user.is_staff})
+    posthog.capture("dashboard_viewed", distinct_id=str(current_user.id), properties={"is_staff": current_user.is_staff})
 
     # Check feature flag
     show_new_feature = posthog.feature_enabled(
         "new-dashboard-feature",
-        current_user.email,
+        str(current_user.id),
         person_properties={
             "email": current_user.email,
             "is_staff": current_user.is_staff,
@@ -163,7 +163,7 @@ async def dashboard(
 
     # Get feature flag payload
     feature_config = posthog.get_feature_flag_payload(
-        "new-dashboard-feature", current_user.email
+        "new-dashboard-feature", str(current_user.id)
     )
 
     return templates.TemplateResponse(
@@ -194,7 +194,7 @@ async def burrito(
 @router.get("/profile", response_class=HTMLResponse)
 async def profile(request: Request, current_user: RequiredUser):
     """User profile page."""
-    capture("profile_viewed")
+    posthog.capture("profile_viewed", distinct_id=str(current_user.id))
 
     return templates.TemplateResponse(
         request, "profile.html", {"current_user": current_user}
@@ -212,10 +212,10 @@ async def update_profile(
     fields_changed = current_user.update_profile(db, name=name)
 
     if fields_changed:
-        capture(
+        posthog.capture(
             "profile_updated",
+            distinct_id=str(current_user.id),
             properties={
-                "username": current_user.email,
                 "fields_changed": fields_changed,
             },
         )

basics/fastapi/requirements.txt

@@ -2,7 +2,7 @@ fastapi>=0.109.0
 uvicorn>=0.27.0
 sqlalchemy>=2.0.0
 python-dotenv>=1.0.0
-posthog>=3.0.0
+posthog>=3.7.0
 pydantic>=2.0.0
 pydantic-settings>=2.0.0
 jinja2>=3.0.0

basics/flask/app/__init__.py

@@ -1,13 +1,12 @@
 """Flask application factory."""
 
-import posthog
 from flask import Flask, g, jsonify, render_template, request
 from flask_login import current_user
-from posthog import identify_context, new_context
 from werkzeug.exceptions import HTTPException
 
 from app.config import config
 from app.extensions import db, login_manager
+from app.posthog_client import posthog
 
 
 def create_app(config_name="default"):
@@ -19,12 +18,6 @@ def create_app(config_name="default"):
     db.init_app(app)
     login_manager.init_app(app)
 
-    # Initialize PostHog
-    if not app.config["POSTHOG_DISABLED"]:
-        posthog.api_key = app.config["POSTHOG_PROJECT_TOKEN"]
-        posthog.host = app.config["POSTHOG_HOST"]
-        posthog.debug = app.config["DEBUG"]
-
     # Import models after db is initialized
     from app.models import User
 
@@ -33,8 +26,20 @@ def create_app(config_name="default"):
     def load_user(user_id):
         return User.get_by_id(user_id)
 
-    # Simple error handlers - no automatic PostHog capture
-    # Capture exceptions manually only where it makes sense (e.g., test endpoints)
+    # Error handlers with automatic PostHog exception capture
+    @app.errorhandler(Exception)
+    def handle_exception(e):
+        """Capture unhandled exceptions in PostHog for error tracking."""
+        if not isinstance(e, HTTPException):
+            posthog.capture_exception(e)
+        if isinstance(e, HTTPException) and e.code == 404:
+            if request.path.startswith('/api/'):
+                return jsonify({"error": "Not found"}), 404
+            return render_template('errors/404.html'), 404
+        if request.path.startswith('/api/'):
+            return jsonify({"error": "Internal server error"}), 500
+        return render_template('errors/500.html'), 500
+
     @app.errorhandler(404)
     def page_not_found(e):
         if request.path.startswith('/api/'):
@@ -43,6 +48,7 @@ def page_not_found(e):
 
     @app.errorhandler(500)
     def internal_server_error(e):
+        posthog.capture_exception(e)
         if request.path.startswith('/api/'):
             return jsonify({"error": "Internal server error"}), 500
         return render_template('errors/500.html'), 500

basics/flask/app/api/routes.py

@@ -1,11 +1,11 @@
 """API endpoints demonstrating PostHog integration patterns."""
 
-import posthog
 from flask import jsonify, request, session
 from flask_login import current_user, login_required
-from posthog import capture, identify_context, new_context
+from posthog import identify_context
 
 from app.api import api_bp
+from app.posthog_client import posthog
 
 
 @api_bp.route("/burrito/consider", methods=["POST"])
@@ -17,9 +17,9 @@ def consider_burrito():
     session["burrito_count"] = burrito_count
 
     # PostHog: Capture custom event
-    with new_context():
-        identify_context(current_user.email)
-        capture("burrito_considered", properties={"total_considerations": burrito_count})
+    with posthog.new_context():
+        identify_context(str(current_user.id))
+        posthog.capture("burrito_considered", properties={"total_considerations": burrito_count})
 
     return jsonify({"success": True, "count": burrito_count})
 
@@ -43,8 +43,8 @@ def test_error():
     except Exception as e:
         if should_capture:
             # Manually capture this specific exception in PostHog
-            with new_context():
-                identify_context(current_user.email)
+            with posthog.new_context():
+                identify_context(str(current_user.id))
                 event_id = posthog.capture_exception(e)
 
             return jsonify({