Init reference doc generation #280

gewenyu99 · 2025-07-08T21:31:16Z

👋 Helloooo, it's time for some basic reference doc generation for Python.

For now, we document:

client class and all methods
module level methods
types where possible

Generation script

The specs will be compiled when you run uv run python docs/generate_json_schemas.py

Automatic generation

This is out of scope for now. Instead, we'll be manually adding this and pinning versions to the Posthog.com repo for a while before we worry about automating anything.

I want to wait until :

we generate a few of these and feed reasonably confident
decide if these specs are going to be versioned or we always use latest version
replicate this per our Q3 goal for a few more SDKs (we might decide to change the schema/etc.)

Basically I think automating this early is going to be painful for now

greptile-apps

PR Summary

Introduces reference documentation generation for the Python SDK with a focus on comprehensive API documentation for client methods, module functions, and types.

Added docs/generate_json_schemas.py to create structured JSON documentation with proper error handling and docstring parsing
Added docs/doc_constant.py defining documentation generation constants like type exclusions and parsing patterns
Enhanced docstrings in posthog/contexts.py and posthog/__init__.py with standardized formats including Args, Examples, and Categories
Improved client method documentation in posthog/client.py with organized categories and proper type hints

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

greptile-apps · 2025-07-08T21:31:43Z

.gitignore

@@ -18,3 +18,4 @@ posthog-analytics
 pyrightconfig.json
 .env
 .DS_Store
+posthog-python-references.json


style: Add newline at end of file to follow Git best practices

greptile-apps · 2025-07-08T21:31:47Z

docs/generate_json_schemas.py

+def analyze_parameter(param: inspect.Parameter, docstring: str = "") -> dict:
+    """Analyze a function parameter and return its documentation."""
+    # Determine if parameter is optional (has default value)
+    is_optional = param.default == inspect.Parameter.empty


logic: Logic error in is_optional determination - currently returns True when parameter has no default (should be opposite)

Suggested change

is_optional = param.default == inspect.Parameter.empty

is_optional = param.default != inspect.Parameter.empty

greptile-apps · 2025-07-08T21:31:47Z

docs/doc_constant.py

+
+# Types that are built-in to Python and don't need to be documented
+NO_DOCS_TYPES = [
+    "Client",


logic: 'Client' probably shouldn't be in NO_DOCS_TYPES since it's a core SDK class that needs documentation

greptile-apps · 2025-07-08T21:31:47Z

docs/generate_json_schemas.py

+                type_info = analyze_type(obj)
+                types_list.append(type_info)
+            except Exception as e:
+                print(f"Error analyzing type {name}: {e}")


style: Exception in type analysis should add type name to noDocsTypes instead of just printing error

Suggested change

type_info = analyze_type(obj)

types_list.append(type_info)

except Exception as e:

print(f"Error analyzing type {name}: {e}")

type_info = analyze_type(obj)

types_list.append(type_info)

except Exception as e:

print(f"Error analyzing type {name}: {e}")

NO_DOCS_TYPES.append(name)

greptile-apps · 2025-07-08T21:31:48Z

docs/doc_constant.py

+    "examples_section": r'Examples:\s*\n(.*?)(?=\n\s*\n\s*Category:|\Z)',
+    "args_section": r'Args:\s*\n(.*?)(?=\n\s*\n\s*Examples:|\n\s*\n\s*Details:|\n\s*\n\s*Category:|\Z)',
+    "details_section": r'Details:\s*\n(.*?)(?=\n\s*\n\s*Examples:|\n\s*\n\s*Category:|\Z)',
+    "category_section": r'Category:\s*\n\s*(.+?)\s*(?:\n|$)',


logic: These regex patterns don't handle nested sections properly. Consider using a more robust parsing approach or adding negative lookaheads to prevent incorrect matches

greptile-apps · 2025-07-08T21:31:49Z

docs/doc_constant.py

+    "filename": "posthog-python-references.json",
+    "indent": 2


style: Add a path variable for output directory instead of just filename to make the output location configurable

greptile-apps · 2025-07-08T21:31:54Z

posthog/__init__.py

 def capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str]:
    """
-    Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up.
-
-    A `capture` call requires
-    - `event name` to specify the event
-    - We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on.
-
-    Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.
+    Capture anything a user does within your system.

-    For example:
-    ```python
-    # Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)
-    with posthog.new_context():
-        # Associate this context with some user, by distinct_id
-        posthog.identify_context('some user')
-
-        # Capture an event, associated with the context-level distinct ID ('some user')
-        posthog.capture('movie started')
-
-        # Capture an event associated with some other user (overriding the context-level distinct ID)
-        posthog.capture('movie joined', distinct_id='some-other-user')
-
-        # Capture an event with some properties
-        posthog.capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})
-
-        # Capture an event with some properties
-        posthog.capture('purchase', properties={'product_id': '123', 'category': 'romcom'})
-        # Capture an event with some associated group
-        posthog.capture('purchase', groups={'company': 'id:5'})
-
-        # Adding a tag to the current context will cause it to appear on all subsequent events
-        posthog.tag_context('some-tag', 'some-value')
-
-        posthog.capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict
-    ```
+    Args:
+        event: The event name to specify the event


style: Parameter 'event' is described in Args section but the rest of the optional parameters from OptionalCaptureArgs are not documented

Suggested change

def capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str]:

"""

Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up.

A `capture` call requires

- `event name` to specify the event

- We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on.

Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.

Capture anything a user does within your system.

For example:

```python

# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)

with posthog.new_context():

# Associate this context with some user, by distinct_id

posthog.identify_context('some user')

# Capture an event, associated with the context-level distinct ID ('some user')

posthog.capture('movie started')

# Capture an event associated with some other user (overriding the context-level distinct ID)

posthog.capture('movie joined', distinct_id='some-other-user')

# Capture an event with some properties

posthog.capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})

# Capture an event with some properties

posthog.capture('purchase', properties={'product_id': '123', 'category': 'romcom'})

# Capture an event with some associated group

posthog.capture('purchase', groups={'company': 'id:5'})

# Adding a tag to the current context will cause it to appear on all subsequent events

posthog.tag_context('some-tag', 'some-value')

posthog.capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict

```

Args:

event: The event name to specify the event

def capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str]:

"""

Capture anything a user does within your system.

Args:

event: The event name to specify the event

**kwargs: Optional arguments including:

distinct_id: Unique identifier for the user

properties: Dict of event properties

timestamp: When the event occurred

groups: Dict of group types and IDs

disable_geoip: Whether to disable GeoIP lookup

greptile-apps · 2025-07-08T21:31:55Z

posthog/__init__.py

+        ```python
+        # Set event properties
+        from posthog import capture
+        capture(
+            "distinct_id_of_the_user",
+            "user_signed_up",
+            {
+                "login_type": "email",
+                "is_free_trial": "true"
+            }
+        )
+        ```


logic: Example code incorrectly shows 'distinct_id_of_the_user' and 'user_signed_up' as first two args, but capture() requires event name first

Suggested change

```python

# Set event properties

from posthog import capture

capture(

"distinct_id_of_the_user",

"user_signed_up",

{

"login_type": "email",

"is_free_trial": "true"

}

)

```

```python

# Set event properties

from posthog import capture

capture(

"user_signed_up",

distinct_id="distinct_id_of_the_user",

properties={

"login_type": "email",

"is_free_trial": "true"

}

)

greptile-apps · 2025-07-08T21:31:56Z

posthog/__init__.py

+        ```python
+        # Set person properties
+        from posthog import capture
+        capture(
+            'distinct_id',
+            event='event_name',
+            properties={
+                '$set': {'name': 'Max Hedgehog'},
+                '$set_once': {'initial_url': '/blog'}
+            }
+        )
+        ```


logic: Example for 'set' function incorrectly uses capture() instead of set(). The example is misleading.

Suggested change

```python

# Set person properties

from posthog import capture

capture(

'distinct_id',

event='event_name',

properties={

'$set': {'name': 'Max Hedgehog'},

'$set_once': {'initial_url': '/blog'}

}

)

```

```python

# Set person properties

from posthog import set

set(

distinct_id='distinct_id',

properties={

'name': 'Max Hedgehog',

'initial_url': '/blog'

}

)

greptile-apps · 2025-07-08T21:32:16Z

posthog/client.py

        """
-        Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely
-        depending on whether local evaluation is enabled and the flag can be locally evaluated.
-
-        This also captures the $feature_flag_called event unless send_feature_flag_events is False.
+        Get a FeatureFlagResult object
        """


style: Method docstring is too minimal. Should include Args section and return type details like other methods for consistency.

Suggested change

"""

Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely

depending on whether local evaluation is enabled and the flag can be locally evaluated.

This also captures the $feature_flag_called event unless send_feature_flag_events is False.

Get a FeatureFlagResult object

"""

"""

Get a FeatureFlagResult object.

Args:

key: The feature flag key.

distinct_id: The distinct ID of the user.

groups: A dictionary of group information.

person_properties: A dictionary of person properties.

group_properties: A dictionary of group properties.

only_evaluate_locally: Whether to only evaluate locally.

send_feature_flag_events: Whether to send feature flag events.

disable_geoip: Whether to disable GeoIP for this request.

Returns:

Optional[FeatureFlagResult]: The feature flag result or None if disabled/not found.

"""

rafaeelaudibert · 2025-07-08T21:46:47Z

posthog/__init__.py

-        posthog.capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict
-    ```
+    Args:
+        event: The event name to specify the event


Like greptile suggested, what about the hidden kwargs?

rafaeelaudibert · 2025-07-08T21:48:30Z

posthog/__init__.py

    _proxy("flush")


 def join():
-    """Block program until the client clears the queue"""
+    """
+    Block program until the client clears the queue.


We should probably add something here saying that you should most likely be using shutdown rather than using join directly, and this is a function you'll use in exceptional situations only

YES I missed join, only had it for flush. Thanks for the reminder

flush can be used in isolation - think guaranteeing you flush all events before a job finishes running, the job runner will keep running, so shutdown doesn't make sense, but we might want events to be 100% sent

rafaeelaudibert · 2025-07-08T21:49:14Z

posthog/client.py

-        depending on whether local evaluation is enabled and the flag can be locally evaluated.
-
-        This also captures the $feature_flag_called event unless send_feature_flag_events is False.
+        Get a FeatureFlagResult object


This one isnt following your proposed structure

Do you mean that this is different from other methods here or different form the JS doc comment structure.

If the latter,
This is a good point to discuss, this is closer to google style python doc strings. I think a part of this was to keep this closer to:

what we already use (latest doc strings by olly follows closer to google stype doc strings)

what is native to this language.

I think it would look pretty wild to have ts/jsdoc in python code

But I think you mean the former :P I think I missed a few methods 😆

The former, yeah, this is just a string, there's no structure like there are for the other methods :)

uv.lock

rafaeelaudibert · 2025-07-08T21:50:25Z

docs/doc_constant.py

+DOC_DEFAULTS = {
+    "showDocs": True,
+    "releaseTag": "public",
+    "return_type_void": "void",


Should this be None like the bot is suggesting?

Yah probably, this is a left over from the TS specs. void isn't a thing here

rafaeelaudibert · 2025-07-08T21:51:44Z

docs/doc_constant.py

We have an RFC that states we should use the bin folder for scripts. Can you add that there instead? I'd be happy with a bin/docs executable, and then maybe a bin/docs folder with your helper scripts. How does that sound?

I'm looking for the RFC and can link it to you if I find it

PostHog/meta#309

Yes ofc, let me go through suggestions. thanks as always for sitting through reviews of code like this, my eyes started watering near the end of this.

Init spec generation

5673e6e

gewenyu99 requested a review from a team July 8, 2025 21:31

greptile-apps bot reviewed Jul 8, 2025

View reviewed changes

rafaeelaudibert reviewed Jul 8, 2025

View reviewed changes

gewenyu99 and others added 3 commits July 8, 2025 19:53

Discard changes to uv.lock

8f92776

Refactor to /bin, run ruff format

2598e98

void doesn't exist in python

3764b41

	is_optional = param.default == inspect.Parameter.empty
	is_optional = param.default != inspect.Parameter.empty

-        """
-        Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely
-        depending on whether local evaluation is enabled and the flag can be locally evaluated.
-        This also captures the $feature_flag_called event unless send_feature_flag_events is False.
-        Get a FeatureFlagResult object
-        """
+        """
+        Get a FeatureFlagResult object.
+        Args:
+            key: The feature flag key.
+            distinct_id: The distinct ID of the user.
+            groups: A dictionary of group information.
+            person_properties: A dictionary of person properties.
+            group_properties: A dictionary of group properties.
+            only_evaluate_locally: Whether to only evaluate locally.
+            send_feature_flag_events: Whether to send feature flag events.
+            disable_geoip: Whether to disable GeoIP for this request.
+        Returns:
+            Optional[FeatureFlagResult]: The feature flag result or None if disabled/not found.
+        """

Init reference doc generation #280

Are you sure you want to change the base?

Init reference doc generation #280

Conversation

gewenyu99 commented Jul 8, 2025

Generation script

Automatic generation

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

PR Summary

Uh oh!

greptile-apps bot Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jul 8, 2025

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!

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!

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!