feat: prep for 6.0.0, bunch of breaking changes #273

oliverb123 · 2025-06-24T10:19:24Z

This change:

Makes distinct_id an optional argument to most event-capturing functions
Changes the order of arguments to most event-capturing functions
Uses kwargs to make it impossible to upgrade to 6.0.0 without modifying how you call these functions
Changes these functions to return the UUID of the captured event, rather than the event contents
Deletes identify, page and screen - identify is set with a misleading name, page and screen are just capture
Deletes unmaintained exception-capture integrations (users should prefer the general purpose django middleware, and we should prefer to build general purpose integrations)

Generally, the goal of this PR is to move the python SDK towards a place where we can use it as the "template" for all server-side SDKs - focusing on semantic scope based state management, simplified interfaces, and reducing how much we expose the internals of our libraries, reducing the cost of future refactoring and improvements to our users. It's the culmination of the previous PR's I've made re: nested contexts, context-based identity and session management, etc.

greptile-apps

PR Summary

Major overhaul of the PostHog Python SDK for version 6.0.0, focusing on simplifying the API and improving maintainability through scope-based state management.

Removal of identify, page, and screen functions in favor of more semantically accurate alternatives (set and capture)
Changed all event-capturing functions to return event UUIDs instead of event contents
Made distinct_id optional and moved to kwargs in event-capturing functions
Removed unmaintained exception-capture integrations in favor of general-purpose Django middleware
Enforced breaking changes through kwargs-only parameters to ensure intentional upgrades

_{20 files reviewed, 6 comments}
_{Edit PR Review Bot Settings | Greptile}

posthog/utils.py

posthog/test/test_before_send.py

posthog/test/test_client.py

posthog/__init__.py

posthog/client.py

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

This reverts commit da395dd.

oliverb123 · 2025-06-24T11:32:30Z

Tagged recent reviewers on this code, as well as ET.

daibhin · 2025-06-24T12:35:27Z

CHANGELOG.md

Might be worth adding a migration guide somewhere telling people the main things needed to migrate from v4 / v5 to v6

daibhin · 2025-06-24T12:37:38Z

CHANGELOG.md

+This release contains a number of major breaking changes:
+- feat: make distinct_id an optional parameter in posthog.capture and related functions
+- feat: make capture and related functions return `Optional[str]`, which is the UUID of the sent event, if it was sent
+- fix: remove `identify` (prefer `posthog.set()`), and `page` and `screen` (prefer `posthog.capture()`)


What's the thinking behind removing these methods?

I get identify is pretty pointless because it doesn't actually persist across captures in the same way it does for the JS Web SDK. Can't you set the user id with contexts now? I'm guess that's the better way than setting the distcint_id on every capture

Worth keeping the page method so that people don't have to familiarize themselves with the $pageview property? Screen I'm less concerned with because it doesn't really make sense on the web and is only used in the mobile SDKs afaik

Yeah, identify is removed because it's semantically confusing - we should push people towards identifying at the context level always.

Re: page, my impression is pageview is generally captured by the frontend?

Several people prefer to use a backend-only instrumentation, this being a framework integration for a non-SPA website (e.g: only django/flask views - not using our utilities) or doing it all themselves on their backend.

I think that using context + capture is enough for them; it is also a more focused API, so I personally prefer it.

posthog/exception_integrations/django.py

daibhin · 2025-06-24T12:47:02Z

posthog/exception_integrations/django.py

-            "ip": headers.get("X-Forwarded-For"),
-            "user_agent": headers.get("User-Agent"),
-            "traceparent": traceparent,
-            "$request_path": self.request.path,


Same with ip, user agent and request path. Should we be adding them to the Django integration or are they there already?

request path is set as $current_url. Ip, user_agent and traceparent aren't set by the middleware currently. Re: should we be adding them, I guess probably? I can do so in a follow up PR.

posthog/exception_integrations/django.py

lricoy

LGTM and I like the direction 😄

I tried the bits I am most aware of locally and they are working nicely.

Just left some comments for context.

hpouillot

I added few comments but it looks good to me. There is also a comment saying proxy methods have not been used in 5-6 months, and I think you capture signature will not be used with the recommended way of using posthog. Might be a good opportunity to clean them ?

hpouillot · 2025-06-24T12:58:17Z

posthog/test/test_before_send.py

+                before_send=my_before_send,
+                sync_mode=True,
+            )
+            msg_uuid = client.capture("user1", "test_event", {"original": "value"})


shouldn't we change this capture call ?

Change it to what? The client object itself already supported optional distinct IDs (it already being a keyword arg), so only the proxy functions needed to change.

Sorry I got confused, the proxy method and the client method don't have the same signature. Proxy capture method accepts event as first argument while client method takes the distinct_id ?

Switched to using Unpack[TypedDict] based kwargs everywhere it seemed to make sense

posthog/__init__.py

posthog/client.py

daibhin · 2025-06-24T16:33:35Z

posthog/exception_integrations/django.py

-
-            self.capture_exception_fn(sys.exc_info(), extra_props)
-
-        signals.got_request_exception.connect(_got_request_exception)


Are we sure the exceptions this previously caught are handled by the try / catch in the new_context scope?

The right way to intercept exceptions on requests is using the middleware, not django signals. If someone has the middleware in their middleware stack, and hasn't disabled exception capture in it, it'll catch their exceptions.

Our regular autocapture still works the same way, to be clear

daibhin

Looks reasonable. I assume you've tested it and are happy. Just a changelog / section in the readme about the upgrade steps would be great

hpouillot · 2025-06-26T14:47:29Z

posthog/scopes.py

    """
-    Add a tag to the current context.
+    Add a tag to the current context. All tags are added as properties to any event, including exceptions, captured
+    within the context.


greptile-apps bot reviewed Jun 24, 2025

View reviewed changes

oliverb123 and others added 5 commits June 24, 2025 13:47

alright

68fdfa5

fix exports

b41b911

Update posthog/test/test_before_send.py

ca29138

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

Update posthog/__init__.py

71b9ff3

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

Update posthog/__init__.py

88b0a9a

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

oliverb123 force-pushed the err/fix-arguments branch from bf80320 to 88b0a9a Compare June 24, 2025 10:47

oliverb123 added 6 commits June 24, 2025 14:08

fix tests after rebase

dd218ee

update examples

0015fce

update mypy baseline

da395dd

Revert "update mypy baseline"

5a4e12d

This reverts commit da395dd.

try again

1755727

whatever

fcfb9c7

oliverb123 requested review from a team, daibhin, hpouillot, lricoy and rafaeelaudibert June 24, 2025 11:32

daibhin reviewed Jun 24, 2025

View reviewed changes

lricoy approved these changes Jun 24, 2025

View reviewed changes

hpouillot reviewed Jun 24, 2025

View reviewed changes

daibhin reviewed Jun 24, 2025

View reviewed changes

daibhin and others added 7 commits June 24, 2025 17:47

request user

fca65f7

fix middleware

462497b

getattr is_authenticated

eaa1e18

allow using custom client for exception capture

f256e19

update comments

c057bf0

fix circular import

7fb1484

type arguments, use TypedDict

7de2ef3

oliverb123 requested review from daibhin and hpouillot June 26, 2025 13:07

oliverb123 added 6 commits June 26, 2025 16:08

fix setup

fec4925

mypy

a2b4bf5

whoops

1ec0c33

ok

757ace5

further mypy

3ca6019

mypy sync

1c1c528

daibhin approved these changes Jun 26, 2025

View reviewed changes

hpouillot reviewed Jun 26, 2025

View reviewed changes

hpouillot approved these changes Jun 26, 2025

View reviewed changes

docs and fixes

572f08a

oliverb123 merged commit 37bd301 into master Jun 27, 2025
7 checks passed

oliverb123 deleted the err/fix-arguments branch June 27, 2025 11:57


		self.capture_exception_fn(sys.exc_info(), extra_props)

		signals.got_request_exception.connect(_got_request_exception)

feat: prep for 6.0.0, bunch of breaking changes #273

feat: prep for 6.0.0, bunch of breaking changes #273

Uh oh!

Conversation

oliverb123 commented Jun 24, 2025

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

PR Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

oliverb123 commented Jun 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lricoy Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lricoy left a comment

Choose a reason for hiding this comment

Uh oh!

hpouillot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

daibhin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

lricoy Jun 24, 2025 •

edited

Loading