docs: add the Markdown reference adapter by gewenyu99 · Pull Request #1182 · PostHog/posthog-python

gewenyu99 · 2026-11-04T19:42:33Z

💡 Motivation and Context

We have a wave of breaking changes with new major versions for most SDKs. References are now read mostly by bots, not humans, and the HogRef format is heavy. This generates the reference as Markdown from the doc comments.

bin/docs_scripts/generate_markdown.py renders each member with griffe2md, a new dev dependency, and groups them by capability. It writes references/posthog-python-<major>.md, and posthog-python-reference.md for the released major.
docs/capabilities.json maps each symbol to its sdk-specs capability, so the doc comments stay as they are. Generation fails on a stale entry, an unknown capability, or an unmapped client method.
Some docstrings get field docs.

💚 How did you test it?

ruff, the mypy baseline and make public_api_check pass. pytest posthog/test: 6085 pass, and 3 fork tests fail only in the full run on macOS.
The pages went through a local Strapi, fetched from GitHub, into a local posthog.com build.

📝 Checklist

All commits are signed (see Commit signing)
I reviewed the submitted code.
I added tests to verify the changes.
I updated the docs if needed.
No breaking change or entry added to the changelog.

If releasing new changes

Ran sampo add to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Claude Code (Opus 5.5), directed by Vincent.

Merge order

PostHog/squeak-strapi#260, then deploy Strapi
Strapi's logs show the sync ran and wrote nothing, and a local posthog.com build against production Strapi is unchanged
feat(docs): build SDK reference Markdown from Strapi as docs pages posthog.com#21971
The posthog-python stack, in order, with the 8.0 release: docs: add the Markdown reference adapter #1182 → docs: generate the 7.x Markdown reference #1183 → docs: generate the experimental 8 reference and migration page #1184 → docs: generate the Markdown reference on release and remove HogRef generation #1185 (this PR)
Strapi's daily sync (06:00 UTC) has run, and /docs/libraries/python/reference is live
[Waiting on posthog-python#1182–#1185] docs(python): link the Python nav to the Markdown reference posthog.com#21973
After every SDK has moved: remove HogRef from posthog.com, Strapi (its cron task and data field) and the SDK repos (their JSON files)

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-11-04T19:45:29Z

posthog-python Compliance Report

Date: 2026-11-06T00:33:02.233638+00:00
Duration: 259884ms

✅ All Tests Passed!

121/121 tests passed

Capture_V1 Tests

✅ 95/95 tests passed

View Details

Test	Status	Duration
Endpoint And Method.Targets V1 Endpoint	✅	516ms
Endpoint And Method.Does Not Use Legacy Endpoints	✅	512ms
Required Headers.Has Authorization Bearer Header	✅	510ms
Required Headers.Has Content Type Json	✅	511ms
Required Headers.Has Posthog Sdk Info Format	✅	511ms
Required Headers.Has Posthog Attempt Header	✅	510ms
Required Headers.Has Posthog Request Id	✅	511ms
Required Headers.Has Posthog Request Timestamp	✅	511ms
Required Headers.Has User Agent	✅	511ms
Body Format.Body Has Created At And Batch	✅	511ms
Body Format.No Api Key In Body	✅	510ms
Body Format.No Sent At In Body	✅	511ms
Event Format.Event Has Required Root Fields	✅	511ms
Event Format.Event Uuid Is Valid	✅	510ms
Event Format.Event Timestamp Is Rfc3339	✅	511ms
Event Format.Non Utc Event Timestamp Is Converted To Utc	✅	524ms
Event Format.Distinct Id Is String	✅	510ms
Event Format.Distinct Id At Root Not Properties	✅	510ms
Event Format.Custom Properties Preserved	✅	511ms
Event Format.Set Properties Preserved	✅	511ms
Event Format.Set Once Properties Preserved	✅	510ms
Event Format.Groups Properties Preserved	✅	511ms
Event Format.Sdk Generates Uuid If Not Provided	✅	510ms
Event Format.Event Has Required Root Fields Batch	✅	514ms
Event Format.Event Uuid Is Valid Batch	✅	515ms
Event Format.Event Timestamp Is Rfc3339 Batch	✅	514ms
Event Format.Distinct Id Is String Batch	✅	513ms
Event Format.Distinct Id At Root Not Properties Batch	✅	514ms
Event Format.Custom Properties Preserved Batch	✅	514ms
Event Format.Set Properties Preserved Batch	✅	514ms
Event Format.Set Once Properties Preserved Batch	✅	515ms
Event Format.Groups Properties Preserved Batch	✅	513ms
Event Format.Sdk Generates Uuid If Not Provided Batch	✅	514ms
Batch Behavior.Multiple Events In Single Batch	✅	518ms
Batch Behavior.Batch Envelope Smoke	✅	515ms
Batch Behavior.Flush With No Events Sends Nothing	✅	508ms
Batch Behavior.Flush At Triggers Batch	✅	1012ms
Batch Behavior.Created At Reflects Batch Creation Time	✅	511ms
Deduplication.Generates Unique Uuids	✅	519ms
Deduplication.Different Events Same Content Different Uuids	✅	513ms
Deduplication.Preserves Uuid On Retry	✅	6520ms
Deduplication.Preserves Timestamp On Retry	✅	6520ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	6519ms
Deduplication.No Duplicate Events In Batch	✅	518ms
Header Behavior On Retry.Attempt Header Starts At One	✅	511ms
Header Behavior On Retry.Attempt Header Increments On Retry	✅	13527ms
Header Behavior On Retry.Request Id Preserved On Retry	✅	6515ms
Header Behavior On Retry.Different Requests Have Different Request Ids	✅	3019ms
Header Behavior On Retry.Request Timestamp Changes On Retry	✅	6520ms
Response Format Validation.Success Response Has Uuid Keyed Results	✅	512ms
Response Format Validation.Success Response Has Ok For Each Event	✅	514ms
Response Format Validation.Success No Retry After When All Ok	✅	514ms
Response Format Validation.Success Retry After Present When Retry Events	✅	1517ms
Response Format Validation.Success No Retry After When Drop Only	✅	512ms
Response Format Validation.Response Echoes Request Id	✅	511ms
Retry Behavior.Retries On 408	✅	6515ms
Retry Behavior.Retries On 500	✅	6520ms
Retry Behavior.Retries On 503	✅	8519ms
Retry Behavior.Retries On 504	✅	6521ms
Retry Behavior.Retryable Errors Have Retry After	✅	3515ms
Retry Behavior.Respects Retry After On Retryable Error	✅	11523ms
Retry Behavior.Does Not Retry On 400	✅	2514ms
Retry Behavior.Does Not Retry On 401	✅	2513ms
Retry Behavior.Does Not Retry On 402	✅	2514ms
Retry Behavior.Does Not Retry On 413	✅	2512ms
Retry Behavior.Does Not Retry On 415	✅	2514ms
Retry Behavior.Non Retryable Errors Have No Retry After	✅	2514ms
Retry Behavior.Implements Backoff	✅	22536ms
Retry Behavior.Max Retries Respected	✅	22536ms
Partial Batch Handling.Handles 200 Full Success	✅	2511ms
Partial Batch Handling.Handles 200 With All Ok	✅	3518ms
Partial Batch Handling.Does Not Retry Dropped Events	✅	3518ms
Partial Batch Handling.Does Not Retry Limited Events	✅	3515ms
Partial Batch Handling.Prunes Ok Events On Partial Retry	✅	6522ms
Partial Batch Handling.Prunes Dropped Events On Partial Retry	✅	6523ms
Partial Batch Handling.Retries Only Retry Events From Partial	✅	6523ms
Partial Batch Handling.Partial Retry Preserves Uuids	✅	6522ms
Partial Batch Handling.Partial Retry Attempt Header Increments	✅	6519ms
Partial Batch Handling.Partial Retry Request Id Preserved	✅	6523ms
Partial Batch Handling.Respects Retry After On Partial	✅	8518ms
Partial Batch Handling.Unknown Result Treated As Terminal	✅	3516ms
Partial Batch Handling.Mixed Ok Drop Limited No Retry	✅	3520ms
Compression.Sends Gzip Content Encoding	✅	511ms
Compression.No Content Encoding When Disabled	✅	510ms
Compression.Compressed Body Is Decompressible	✅	510ms
Error Handling.Does Not Retry On Unknown 4Xx	✅	2513ms
Event Options.Cookieless Mode Override	✅	510ms
Event Options.Disable Skew Correction Override	✅	511ms
Event Options.Process Person Profile Override	✅	511ms
Event Options.Product Tour Id Override	✅	510ms
Event Options.Unset Options Omitted	✅	511ms
Event Options.Options Override In Batch	✅	514ms
Geoip And Historical Migration.Geoip Disable Injected Into Properties	✅	510ms
Geoip And Historical Migration.Historical Migration Set In Body	✅	511ms
Geoip And Historical Migration.Historical Migration Absent By Default	✅	511ms

Capture_Ai Tests

✅ 5/5 tests passed

View Details

Test	Status	Duration
Routing.Capture Ai Posts To Ai Endpoint	✅	511ms
Routing.Capture Does Not Reroute Ai Named Events	✅	511ms
Identity.Capture Ai Event Has Uuid	✅	511ms
Identity.Capture Ai Keeps Supplied Uuid	✅	510ms
Timestamp Format.Non Utc Event Timestamp Is Converted To Utc	✅	511ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	12ms
Request Payload.Flags Request Uses V4 Query Param	✅	9ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	9ms
Request Payload.Flags Request Omits Authorization Header	✅	9ms
Request Payload.Token In Flags Body Matches Init	✅	8ms
Request Payload.Groups Round Trip	✅	9ms
Request Payload.Groups Default To Empty Object	✅	8ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	9ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	9ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	9ms
Request Lifecycle.No Flags Request On Init Alone	✅	3ms
Request Lifecycle.No Flags Request On Normal Capture	✅	509ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	15ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	9ms
Retry Behavior.Retries Flags On 502	✅	313ms
Retry Behavior.Retries Flags On 504	✅	314ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	512ms

Feature_Flags_Local_Evaluation Tests

✅ 4/4 tests passed

View Details

Test	Status	Duration
Versioned Boolean Matching.Matching Version Missing	✅	67ms
Versioned Boolean Matching.Matching Version 1	✅	65ms
Versioned Boolean Matching.Matching Version 2	✅	65ms
Versioned Boolean Matching.Version Only Reload 1 2 1 2 Missing	✅	33ms

posthog

PostHog Review · Standard · reviewed d811ca2: 6 Should fix, 1 Consider.

This is the only automatic review while this pull request is a draft. Comment @posthog review to review new changes sooner. Otherwise, a review of the new changes runs when you mark it ready for review.

See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.

Drops the Node renderer, its tests, the page check and the sdk-specs module. The generated pages are unchanged byte for byte. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…nt matter Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Replaces the 539-line renderer with griffe2md, a dev dependency. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-11-05T15:52:44Z

SDK performance: posthog-python

Benchmarks completed. No changes flagged for review.

Flags require at least a 5% change in the median and all six pairs agreeing on direction. This is a noise filter, not proof of a performance change or a CI gate.

View all results

Test	Measurement	Before PR	With PR	Change	Assessment
Capture and deliver events (32-byte payload, burst) Shard: capture	Managed heap after settling	—	—	—	unavailable; base: unsupported; head: unsupported; base: CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.; head: CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Managed heap after settling	—	—	—	unavailable; base: unsupported; head: unsupported; base: CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.; head: CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.
Capture and deliver events (32-byte payload, steady) Shard: capture	Managed heap after settling	—	—	—	unavailable; base: unsupported; head: unsupported; base: CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.; head: CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Managed heap after settling	—	—	—	unavailable; base: unsupported; head: unsupported; base: CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.; head: CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.
Queue an event (32-byte payload) Shard: capture	Allocated memory per operation	—	—	—	unavailable; base: unsupported; head: unsupported; base: Background preparation has no public completion boundary before flush; see capture.drain for full-pipeline allocations.; head: Background preparation has no public completion boundary before flush; see capture.drain for full-pipeline allocations.
Queue an event (32-byte payload) Shard: capture	Allocations per operation	—	—	—	unavailable; base: unsupported; head: unsupported; base: Background preparation has no public completion boundary before flush; see capture.drain for full-pipeline allocations.; head: Background preparation has no public completion boundary before flush; see capture.drain for full-pipeline allocations.
Queue an event (4,096-byte payload) Shard: capture	Allocated memory per operation	—	—	—	unavailable; base: unsupported; head: unsupported; base: Background preparation has no public completion boundary before flush; see capture.drain for full-pipeline allocations.; head: Background preparation has no public completion boundary before flush; see capture.drain for full-pipeline allocations.
Queue an event (4,096-byte payload) Shard: capture	Allocations per operation	—	—	—	unavailable; base: unsupported; head: unsupported; base: Background preparation has no public completion boundary before flush; see capture.drain for full-pipeline allocations.; head: Background preparation has no public completion boundary before flush; see capture.drain for full-pipeline allocations.
Evaluate 1,000 flags under concurrent load Shard: flags-memory	Managed heap after settling	—	—	—	unavailable; base: unsupported; head: unsupported; base: CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.; head: CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.
Refresh 1,000 flag definitions Shard: flags-memory	Managed heap after settling	—	—	—	unavailable; base: unsupported; head: unsupported; base: CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.; head: CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.
Capture and deliver events (32-byte payload, burst) Shard: capture	Allocated memory per operation	113.54 KiB/op	113.54 KiB/op	<0.1% less memory	Not flagged
Capture and deliver events (32-byte payload, burst) Shard: capture	Allocations per operation	1,096.62 count/op	1,096.58 count/op	<0.1% fewer	Not flagged
Capture and deliver events (32-byte payload, burst) Shard: capture	Time per operation	69.66 µs/op	72.55 µs/op	4.2% more time	Not flagged
Capture and deliver events (32-byte payload, burst) Shard: capture	Idle process memory (RSS)	36 MiB	36 MiB	<0.1% less memory	Not flagged
Capture and deliver events (32-byte payload, burst) Shard: capture	Observed peak process memory (RSS)	37.74 MiB	37.75 MiB	<0.1% more memory	Not flagged
Capture and deliver events (32-byte payload, burst) Shard: capture	Process memory after settling (RSS)	37.74 MiB	37.75 MiB	<0.1% more memory	Not flagged
Capture and deliver events (32-byte payload, burst) Shard: capture	Process CPU time per operation	70.08 µs/op	73.68 µs/op	5.1% more time	Not flagged
Capture and deliver events (32-byte payload, burst) Shard: capture	Lifetime peak process memory (RSS)	39.55 MiB	39.55 MiB	No observed change	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Allocated memory per operation	166.1 KiB/op	166.1 KiB/op	<0.1% less memory	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Allocations per operation	1,089.59 count/op	1,089.58 count/op	<0.1% fewer	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Time per operation	100.37 µs/op	103.64 µs/op	3.3% more time	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Idle process memory (RSS)	40.84 MiB	40.85 MiB	<0.1% more memory	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Observed peak process memory (RSS)	45.93 MiB	45.95 MiB	<0.1% more memory	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Process memory after settling (RSS)	45.93 MiB	45.95 MiB	<0.1% more memory	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Process CPU time per operation	93.2 µs/op	97.24 µs/op	4.3% more time	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Lifetime peak process memory (RSS)	50.78 MiB	50.72 MiB	0.1% less memory	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Allocated memory per operation	117.68 KiB/op	117.68 KiB/op	<0.1% less memory	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Allocations per operation	1,136.58 count/op	1,136.57 count/op	<0.1% fewer	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Time per operation	81.33 µs/op	83.51 µs/op	2.7% more time	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Idle process memory (RSS)	35.98 MiB	35.94 MiB	0.1% less memory	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Observed peak process memory (RSS)	36.08 MiB	36.04 MiB	<0.1% less memory	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Process memory after settling (RSS)	36.08 MiB	36.04 MiB	<0.1% less memory	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Process CPU time per operation	78.68 µs/op	81.21 µs/op	3.2% more time	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Lifetime peak process memory (RSS)	39.55 MiB	39.55 MiB	No observed change	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Allocated memory per operation	170.57 KiB/op	170.57 KiB/op	<0.1% more memory	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Allocations per operation	1,129.47 count/op	1,129.48 count/op	<0.1% more	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Time per operation	114.89 µs/op	106.19 µs/op	7.6% less time	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Idle process memory (RSS)	40.64 MiB	40.74 MiB	0.2% more memory	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Observed peak process memory (RSS)	40.64 MiB	40.75 MiB	0.3% more memory	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Process memory after settling (RSS)	40.64 MiB	40.75 MiB	0.3% more memory	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Process CPU time per operation	109.17 µs/op	99.39 µs/op	9% less time	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Lifetime peak process memory (RSS)	41 MiB	40.97 MiB	<0.1% less memory	Not flagged
Queue an event (32-byte payload) Shard: capture	Caller-thread CPU time per operation	54.73 µs/op	46.44 µs/op	15.1% less time	Not flagged
Queue an event (32-byte payload) Shard: capture	Time per operation	55.4 µs/op	46.44 µs/op	16.2% less time	Not flagged
Queue an event (4,096-byte payload) Shard: capture	Caller-thread CPU time per operation	47.27 µs/op	46.55 µs/op	1.5% less time	Not flagged
Queue an event (4,096-byte payload) Shard: capture	Time per operation	47.27 µs/op	47.63 µs/op	0.8% more time	Not flagged
Evaluate all 10 flags Shard: flags-scaling	Allocated memory per operation	200.98 KiB/op	200.98 KiB/op	No observed change	Not flagged
Evaluate all 10 flags Shard: flags-scaling	Allocations per operation	2,339.33 count/op	2,339.33 count/op	No observed change	Not flagged
Evaluate all 10 flags Shard: flags-scaling	Time per operation	65.51 µs/op	65.47 µs/op	<0.1% less time	Not flagged
Evaluate all 10 flags Shard: flags-scaling	Process CPU time per operation	65.51 µs/op	65.47 µs/op	<0.1% less time	Not flagged
Evaluate all 100 flags Shard: flags-scaling	Allocated memory per operation	1.93 MiB/op	1.93 MiB/op	No observed change	Not flagged
Evaluate all 100 flags Shard: flags-scaling	Allocations per operation	23,013.56 count/op	23,013.56 count/op	No observed change	Not flagged
Evaluate all 100 flags Shard: flags-scaling	Time per operation	639.24 µs/op	632.58 µs/op	1% less time	Not flagged
Evaluate all 100 flags Shard: flags-scaling	Process CPU time per operation	639.32 µs/op	632.38 µs/op	1.1% less time	Not flagged
Evaluate all 1,000 flags Shard: flags-scaling	Allocated memory per operation	19.24 MiB/op	19.24 MiB/op	No observed change	Not flagged
Evaluate all 1,000 flags Shard: flags-scaling	Allocations per operation	229,654.94 count/op	229,654.94 count/op	No observed change	Not flagged
Evaluate all 1,000 flags Shard: flags-scaling	Time per operation	6.33 ms/op	6.39 ms/op	1% more time	Not flagged
Evaluate all 1,000 flags Shard: flags-scaling	Process CPU time per operation	6.33 ms/op	6.39 ms/op	1% more time	Not flagged
Evaluate 1,000 flags under concurrent load Shard: flags-memory	Idle process memory (RSS)	41.62 MiB	42.13 MiB	1.2% more memory	Not flagged
Evaluate 1,000 flags under concurrent load Shard: flags-memory	Observed peak process memory (RSS)	41.89 MiB	42.43 MiB	1.3% more memory	Not flagged
Evaluate 1,000 flags under concurrent load Shard: flags-memory	Process memory after settling (RSS)	41.89 MiB	42.43 MiB	1.3% more memory	Not flagged
Evaluate 1,000 flags under concurrent load Shard: flags-memory	Lifetime peak process memory (RSS)	42.46 MiB	42.55 MiB	0.2% more memory	Not flagged
Refresh 1,000 flag definitions Shard: flags-memory	Idle process memory (RSS)	42.08 MiB	42.07 MiB	<0.1% less memory	Not flagged
Refresh 1,000 flag definitions Shard: flags-memory	Observed peak process memory (RSS)	42.13 MiB	42.16 MiB	<0.1% more memory	Not flagged
Refresh 1,000 flag definitions Shard: flags-memory	Process memory after settling (RSS)	41.51 MiB	42.14 MiB	1.5% more memory	Not flagged
Refresh 1,000 flag definitions Shard: flags-memory	Lifetime peak process memory (RSS)	42.49 MiB	42.57 MiB	0.2% more memory	Not flagged
Evaluate one boolean flag Shard: flags-single	Allocated memory per operation	15.05 KiB/op	15.05 KiB/op	No observed change	Not flagged
Evaluate one boolean flag Shard: flags-single	Allocations per operation	173.76 count/op	173.76 count/op	No observed change	Not flagged
Evaluate one boolean flag Shard: flags-single	Time per operation	13.96 µs/op	14.07 µs/op	0.8% more time	Not flagged
Evaluate one boolean flag Shard: flags-single	Process CPU time per operation	13.96 µs/op	14.07 µs/op	0.8% more time	Not flagged
Evaluate a cohort-filtered flag Shard: flags-single	Allocated memory per operation	23.12 KiB/op	23.12 KiB/op	No observed change	Not flagged
Evaluate a cohort-filtered flag Shard: flags-single	Allocations per operation	270.27 count/op	270.27 count/op	No observed change	Not flagged
Evaluate a cohort-filtered flag Shard: flags-single	Time per operation	21.55 µs/op	21.68 µs/op	0.6% more time	Not flagged
Evaluate a cohort-filtered flag Shard: flags-single	Process CPU time per operation	21.55 µs/op	21.68 µs/op	0.6% more time	Not flagged
Evaluate a flag (early match) Shard: flags-single	Allocated memory per operation	35.71 KiB/op	35.71 KiB/op	No observed change	Not flagged
Evaluate a flag (early match) Shard: flags-single	Allocations per operation	387.27 count/op	387.27 count/op	No observed change	Not flagged
Evaluate a flag (early match) Shard: flags-single	Time per operation	27.79 µs/op	27.62 µs/op	0.6% less time	Not flagged
Evaluate a flag (early match) Shard: flags-single	Process CPU time per operation	27.78 µs/op	27.62 µs/op	0.6% less time	Not flagged
Evaluate a flag (late match) Shard: flags-single	Allocated memory per operation	53.59 KiB/op	53.59 KiB/op	No observed change	Not flagged
Evaluate a flag (late match) Shard: flags-single	Allocations per operation	576.27 count/op	576.27 count/op	No observed change	Not flagged
Evaluate a flag (late match) Shard: flags-single	Time per operation	38.75 µs/op	38.49 µs/op	0.7% less time	Not flagged
Evaluate a flag (late match) Shard: flags-single	Process CPU time per operation	38.75 µs/op	38.48 µs/op	0.7% less time	Not flagged
Evaluate a flag (no match) Shard: flags-single	Allocated memory per operation	52.14 KiB/op	52.14 KiB/op	No observed change	Not flagged
Evaluate a flag (no match) Shard: flags-single	Allocations per operation	556.77 count/op	556.77 count/op	No observed change	Not flagged
Evaluate a flag (no match) Shard: flags-single	Time per operation	35 µs/op	34.93 µs/op	0.2% less time	Not flagged
Evaluate a flag (no match) Shard: flags-single	Process CPU time per operation	35 µs/op	34.93 µs/op	0.2% less time	Not flagged
Evaluate a property-filtered flag Shard: flags-single	Allocated memory per operation	17.84 KiB/op	17.84 KiB/op	No observed change	Not flagged
Evaluate a property-filtered flag Shard: flags-single	Allocations per operation	198.27 count/op	198.27 count/op	No observed change	Not flagged
Evaluate a property-filtered flag Shard: flags-single	Time per operation	16.64 µs/op	16.73 µs/op	0.5% more time	Not flagged
Evaluate a property-filtered flag Shard: flags-single	Process CPU time per operation	16.64 µs/op	16.73 µs/op	0.5% more time	Not flagged
Evaluate a regex-filtered flag Shard: flags-single	Allocated memory per operation	19.23 KiB/op	19.23 KiB/op	No observed change	Not flagged
Evaluate a regex-filtered flag Shard: flags-single	Allocations per operation	210.77 count/op	210.77 count/op	No observed change	Not flagged
Evaluate a regex-filtered flag Shard: flags-single	Time per operation	17.66 µs/op	17.97 µs/op	1.8% more time	Not flagged
Evaluate a regex-filtered flag Shard: flags-single	Process CPU time per operation	17.66 µs/op	17.97 µs/op	1.8% more time	Not flagged
Evaluate a rollout flag Shard: flags-single	Allocated memory per operation	14.04 KiB/op	14.04 KiB/op	No observed change	Not flagged
Evaluate a rollout flag Shard: flags-single	Allocations per operation	160.76 count/op	160.76 count/op	No observed change	Not flagged
Evaluate a rollout flag Shard: flags-single	Time per operation	13.15 µs/op	13.12 µs/op	0.2% less time	Not flagged
Evaluate a rollout flag Shard: flags-single	Process CPU time per operation	13.15 µs/op	13.12 µs/op	0.2% less time	Not flagged
Evaluate a multivariate flag Shard: flags-single	Allocated memory per operation	15.21 KiB/op	15.21 KiB/op	No observed change	Not flagged
Evaluate a multivariate flag Shard: flags-single	Allocations per operation	177.77 count/op	177.77 count/op	No observed change	Not flagged
Evaluate a multivariate flag Shard: flags-single	Time per operation	14.62 µs/op	14.75 µs/op	0.9% more time	Not flagged
Evaluate a multivariate flag Shard: flags-single	Process CPU time per operation	14.62 µs/op	14.75 µs/op	0.9% more time	Not flagged

Values are medians of paired measurements. Not flagged does not mean unchanged. Unavailable means a measurement could not be provided, not zero. Estimated allocation measurements retain their instrumentation uncertainty. RSS measures the whole process, not just SDK allocations; observed peaks are sampled checkpoints. Paired ranges in the diagnostics describe variability, not confidence intervals.

Each shard uses its own runner; compare Before PR against With PR within a row, not across shards.

Compared 5febc73aa74b38376a9d9cac895552686cefaca2 → fb0019a4672524fc384b9e45b716dad528016662.

Full report and diagnostics

102 metric rows; 102 rows shown in all results. Omitted or shortened data remain in comparison.json, including per-runner environments, resource limits, measurement methods, samples and checkpoints.

posthog

PostHog Review · Standard · reviewed ebbc5b4: 2 Should fix.

dustinbyrne

I independently reproduced the existing annotation-leakage and coroutine-marker findings with the locked renderer. Consider correcting both and adding focused output tests before publishing the new reference. These are reference-output issues, not SDK runtime regressions. One optional schema-completeness suggestion is inline.

AI-assisted review.

griffe2md 1.5.1's signature template gives an unannotated parameter the previous parameter's annotation, so Client(...) showed `debug: str = False`. It also drops `async`. Swap its format_signature filter for griffe's own Function.signature(), prefixed with `async` for coroutines. Also document OptionalSetArgs and CodeEmailArgs in Types, since set, set_once and Emails.send reference them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The posthog-capability lines showed in IDE hover help. The docstrings read as they do on main again, Category sections included, and the generator drops those sections from the reference. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Covers the two output bugs review reproduced: unannotated parameters getting the previous parameter's annotation, and coroutines missing async. Also checks the keyword-only marker. griffe and griffe2md join the test extra so CI runs them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Client(...) listed _use_ai_lane and _enable_multimodal_capture. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…s name - Summary tables keep a docstring's first paragraph, not its first line. - A Returns section is one return value, even when its description wraps. - A constructor's signature reads `Client(...)`, not `__init__(...)`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

- The context example tags with `tag`, since `tag_context` doesn't exist. - The `capture_exception` example passes `distinct_id` by keyword, since it's keyword-only. - Two reST `Example::` blocks become Markdown, which the reference renders. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs: add the Markdown reference adapter

d811ca2

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

gewenyu99 self-assigned this Nov 4, 2026

This was referenced Nov 4, 2026

docs: generate the 7.x Markdown reference #1183

Open

docs: generate the experimental 8 reference and migration page #1184

Open

posthog Bot reviewed Nov 4, 2026

View reviewed changes

docs: render the reference in one Python script

b5a6328

Drops the Node renderer, its tests, the page check and the sdk-specs module. The generated pages are unchanged byte for byte. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

gewenyu99 added this pull request to stack #1186 November 4, 2026 20:15

gewenyu99 and others added 2 commits November 4, 2026 17:00

docs: write the latest reference as its own file, with the site's fro…

7c20b46

…nt matter Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs: leave indexing to the site

bdfa218

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

gewenyu99 and others added 2 commits November 4, 2026 18:07

docs: render the reference with griffe2md

23e61f0

Replaces the 539-line renderer with griffe2md, a dev dependency. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge main into markdown-reference-adapter

ebbc5b4

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

gewenyu99 marked this pull request as ready for review November 5, 2026 16:10

gewenyu99 requested a review from a team as a code owner November 5, 2026 16:10

posthog Bot reviewed Nov 5, 2026

View reviewed changes

Comment thread bin/docs_scripts/generate_markdown.py Resolved

Comment thread bin/docs_scripts/generate_markdown.py Resolved

dustinbyrne reviewed Nov 5, 2026

View reviewed changes

Comment thread bin/docs_scripts/generate_markdown.py Resolved

dustinbyrne requested a review from a team November 5, 2026 19:07

gewenyu99 and others added 3 commits November 5, 2026 14:26

docs: list v1's context option methods in SDK utils

47f7b75

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

turnipdabeets approved these changes Nov 5, 2026

View reviewed changes

Comment thread bin/docs_scripts/generate_markdown.py Resolved

gewenyu99 requested a review from dustinbyrne November 5, 2026 20:49

gewenyu99 and others added 2 commits November 5, 2026 16:12

docs: leave private parameters out of reference signatures

72316e6

Client(...) listed _use_ai_lane and _enable_multimodal_capture. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

gewenyu99 mentioned this pull request Nov 6, 2026

fix(docs): render the Markdown SDK references as plain Markdown, not MDX PostHog/posthog.com#22037

Open

9 tasks

Navigation Menu

Repository navigation

docs: add the Markdown reference adapter - #1182

docs: add the Markdown reference adapter#1182
gewenyu99 wants to merge 13 commits into
mainfrom
markdown-reference-adapter

gewenyu99 commented Nov 4, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Nov 4, 2026 •

edited

Loading

Uh oh!

posthog Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Nov 5, 2026 •

edited

Loading

Uh oh!

posthog Bot left a comment

Uh oh!

Uh oh!

Uh oh!

dustinbyrne left a comment

Uh oh!

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

gewenyu99 commented Nov 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

💡 Motivation and Context

💚 How did you test it?

📝 Checklist

If releasing new changes

🤖 Agent context

Merge order

Uh oh!

github-actions Bot commented Nov 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

posthog-python Compliance Report

✅ All Tests Passed!

Capture_V1 Tests

Capture_Ai Tests

Feature_Flags Tests

Feature_Flags_Local_Evaluation Tests

Uh oh!

posthog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Nov 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

SDK performance: posthog-python

Uh oh!

posthog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dustinbyrne left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gewenyu99 commented Nov 4, 2026 •

edited

Loading

github-actions Bot commented Nov 4, 2026 •

edited

Loading

github-actions Bot commented Nov 5, 2026 •

edited

Loading