Basic group analytics support (#44)

* Make setup instructions work

* Add basic group analytics support to library

* Resolve formatting issues

Author: macobo

posthog/__init__.py

@@ -26,6 +26,7 @@ def capture(
     context=None,  # type: Optional[Dict]
     timestamp=None,  # type: Optional[datetime.datetime]
     message_id=None,  # type: Optional[str]
+    groups=None,  # type: Optional[Dict]
 ):
     # type: (...) -> None
     """
@@ -38,10 +39,14 @@ def capture(
 
     Optionally you can submit
     - `properties`, which can be a dict with any information you'd like to add
+    - `groups`, which is a dict of group type -> group key mappings
 
     For example:
     ```python
+    posthog.capture('distinct id', 'opened app')
     posthog.capture('distinct id', 'movie played', {'movie_id': '123', 'category': 'romcom'})
+
+    posthog.capture('distinct id', 'purchase', groups={'company': 'id:5'})
     ```
     """
     _proxy(
@@ -52,11 +57,12 @@ def capture(
         context=context,
         timestamp=timestamp,
         message_id=message_id,
+        groups=groups,
     )
 
 
 def identify(
-    distinct_id,  # type: str,
+    distinct_id,  # type: str
     properties=None,  # type: Optional[Dict]
     context=None,  # type: Optional[Dict]
     timestamp=None,  # type: Optional[datetime.datetime]
@@ -154,9 +160,39 @@ def set_once(
     )
 
 
-def group(*args, **kwargs):
-    """Send a group call."""
-    _proxy("group", *args, **kwargs)
+def group_identify(
+    group_type,  # type: str
+    group_key,  # type: str
+    properties=None,  # type: Optional[Dict]
+    context=None,  # type: Optional[Dict]
+    timestamp=None,  # type: Optional[datetime.datetime]
+    message_id=None,  # type: Optional[str]
+):
+    # type: (...) -> None
+    """
+    Set properties on a group
+
+     A `set_once` call requires
+     - `group_type` type of your group
+     - `group_key` unique identifier of the group
+     - `properties` with a dict with any key: value pairs
+
+     For example:
+     ```python
+     posthog.group_identify('company', 5, {
+         'employees': 11,
+     })
+     ```
+    """
+    _proxy(
+        "group_identify",
+        group_type=group_type,
+        group_key=group_key,
+        properties=properties,
+        context=context,
+        timestamp=timestamp,
+        message_id=message_id,
+    )
 
 
 def alias(

posthog/client.py

@@ -120,7 +120,9 @@ def identify(self, distinct_id=None, properties=None, context=None, timestamp=No
 
         return self._enqueue(msg)
 
-    def capture(self, distinct_id=None, event=None, properties=None, context=None, timestamp=None, message_id=None):
+    def capture(
+        self, distinct_id=None, event=None, properties=None, context=None, timestamp=None, message_id=None, groups=None
+    ):
         properties = properties or {}
         context = context or {}
         require("distinct_id", distinct_id, ID_TYPES)
@@ -136,6 +138,10 @@ def capture(self, distinct_id=None, event=None, properties=None, context=None, t
             "messageId": message_id,
         }
 
+        if groups:
+            require("groups", groups, dict)
+            msg["properties"]["$groups"] = groups
+
         return self._enqueue(msg)
 
     def set(self, distinct_id=None, properties=None, context=None, timestamp=None, message_id=None):
@@ -172,6 +178,30 @@ def set_once(self, distinct_id=None, properties=None, context=None, timestamp=No
 
         return self._enqueue(msg)
 
+    def group_identify(
+        self, group_type=None, group_key=None, properties=None, context=None, timestamp=None, message_id=None
+    ):
+        properties = properties or {}
+        context = context or {}
+        require("group_type", group_type, ID_TYPES)
+        require("group_key", group_key, ID_TYPES)
+        require("properties", properties, dict)
+
+        msg = {
+            "event": "$groupidentify",
+            "properties": {
+                "$group_type": group_type,
+                "$group_key": group_key,
+                "$group_set": properties,
+            },
+            "distinct_id": "${}_{}".format(group_type, group_key),
+            "timestamp": timestamp,
+            "context": context,
+            "messageId": message_id,
+        }
+
+        return self._enqueue(msg)
+
     def alias(self, previous_id=None, distinct_id=None, context=None, timestamp=None, message_id=None):
         context = context or {}
 

posthog/test/test_client.py

@@ -91,6 +91,17 @@ def test_advanced_capture(self):
         self.assertEqual(msg["properties"]["$lib_version"], VERSION)
         self.assertEqual(msg["messageId"], "messageId")
         self.assertEqual(msg["distinct_id"], "distinct_id")
+        self.assertTrue("$groups" not in msg["properties"])
+
+    def test_groups_capture(self):
+        success, msg = self.client.capture(
+            "distinct_id",
+            "test_event",
+            groups={"company": "id:5", "instance": "app.posthog.com"},
+        )
+
+        self.assertTrue(success)
+        self.assertEqual(msg["properties"]["$groups"], {"company": "id:5", "instance": "app.posthog.com"})
 
     def test_basic_identify(self):
         client = self.client
@@ -179,6 +190,46 @@ def test_advanced_set_once(self):
         self.assertEqual(msg["messageId"], "messageId")
         self.assertEqual(msg["distinct_id"], "distinct_id")
 
+    def test_basic_group_identify(self):
+        success, msg = self.client.group_identify("organization", "id:5")
+
+        self.assertTrue(success)
+        self.assertEqual(msg["event"], "$groupidentify")
+        self.assertEqual(msg["distinct_id"], "$organization_id:5")
+        self.assertEqual(
+            msg["properties"],
+            {
+                "$group_type": "organization",
+                "$group_key": "id:5",
+                "$group_set": {},
+                "$lib": "posthog-python",
+                "$lib_version": VERSION,
+            },
+        )
+        self.assertTrue(isinstance(msg["timestamp"], str))
+        self.assertTrue(isinstance(msg["messageId"], str))
+
+    def test_advanced_group_identify(self):
+        success, msg = self.client.group_identify(
+            "organization", "id:5", {"trait": "value"}, {"ip": "192.168.0.1"}, datetime(2014, 9, 3), "messageId"
+        )
+
+        self.assertTrue(success)
+        self.assertEqual(msg["event"], "$groupidentify")
+        self.assertEqual(msg["distinct_id"], "$organization_id:5")
+        self.assertEqual(
+            msg["properties"],
+            {
+                "$group_type": "organization",
+                "$group_key": "id:5",
+                "$group_set": {"trait": "value"},
+                "$lib": "posthog-python",
+                "$lib_version": VERSION,
+            },
+        )
+        self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00+00:00")
+        self.assertEqual(msg["context"]["ip"], "192.168.0.1")
+
     def test_basic_alias(self):
         client = self.client
         success, msg = client.alias("previousId", "distinct_id")

setup.py

@@ -22,7 +22,7 @@
         "isort",
         "pre-commit",
     ],
-    "test": ["mock>=2.0.0", "freezegun==0.3.15", "pylint", "flake8", "coverage"],
+    "test": ["mock>=2.0.0", "freezegun==0.3.15", "pylint", "flake8", "coverage", "pytest"],
     "sentry": ["sentry-sdk", "django"],
 }