Add comprehensive ruff linting configuration

Build on the ruff formatting added in #157 by adding full linting
with select = ["ALL"] per our strict Python guide. This enforces
all ruff rules with explicit, documented exclusions for rules that
are inappropriate for the existing codebase.

Changes:
- Add [tool.ruff.lint] config to pyproject.toml with select = ["ALL"]
- Add per-file-ignores for test, demo, and docs files
- Add isort config with known-first-party = ["mixpanel"]
- Add pydocstyle convention = "google"
- Add ruff check step to CI workflow
- Add .pre-commit-config.yaml with ruff format + lint hooks
- Add pre-commit to dev dependencies
- Modernize type annotations (Dict -> dict, List -> list)
- Add from __future__ import annotations to flags modules
- Convert logging f-strings to lazy %s formatting
- Add module-level loggers replacing root logger calls
- Fix docstring formatting (blank lines, punctuation)
- Fix true/false comparisons (== True -> is True)
- Fix raise-without-from in exception handler
- Extract f-strings from exception constructors
- Various small fixes (SIM102, SIM118, UP030, C408, etc.)

Author: jaredmixpanel

.github/workflows/test.yml

@@ -14,6 +14,8 @@ jobs:
       uses: astral-sh/setup-uv@v5
     - name: Check formatting
       run: uvx ruff format --check .
+    - name: Check linting
+      run: uvx ruff check .
 
   test:
     runs-on: ubuntu-24.04

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.10
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [--fix]

demo/local_flags.py

@@ -1,8 +1,8 @@
-import os
 import asyncio
-import mixpanel
 import logging
 
+import mixpanel
+
 logging.basicConfig(level=logging.INFO)
 
 # Configure your project token, the feature flag  to test, and user context to evaluate.

demo/remote_flags.py

@@ -1,7 +1,8 @@
 import asyncio
-import mixpanel
 import logging
 
+import mixpanel
+
 logging.basicConfig(level=logging.INFO)
 
 # Configure your project token, the feature flag to test, and user context to evaluate.

demo/subprocess_consumer.py

@@ -1,7 +1,7 @@
 import multiprocessing
 import random
 
-from mixpanel import Mixpanel, BufferedConsumer
+from mixpanel import BufferedConsumer, Mixpanel
 
 """
 As your application scales, it's likely you'll want to
@@ -23,7 +23,7 @@
 """
 
 
-class QueueWriteConsumer(object):
+class QueueWriteConsumer:
     def __init__(self, queue):
         self.queue = queue
 

docs/conf.py

@@ -1,11 +1,10 @@
-# -*- coding: utf-8 -*-
 import sys
-import os
+from pathlib import Path
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath(".."))
+# documentation root, use Path.resolve() to make it absolute, like shown here.
+sys.path.insert(0, str(Path("..").resolve()))
 
 extensions = [
     "sphinx.ext.autodoc",

mixpanel/__init__.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 """This is the official Mixpanel client library for Python.
 
 Mixpanel client libraries allow for tracking events and setting properties on
@@ -20,12 +19,11 @@
 import logging
 import time
 import uuid
+from typing import Optional
 
 import requests
-from requests.auth import HTTPBasicAuth
 import urllib3
-
-from typing import Optional
+from requests.auth import HTTPBasicAuth
 
 from .flags.local_feature_flags import LocalFeatureFlagsProvider
 from .flags.remote_feature_flags import RemoteFeatureFlagsProvider
@@ -98,7 +96,7 @@ def _make_insert_id(self):
 
     @property
     def local_flags(self) -> LocalFeatureFlagsProvider:
-        """Get the local flags provider if configured for it"""
+        """Get the local flags provider if configured for it."""
         if self._local_flags_provider is None:
             raise MixpanelException(
                 "No local flags provider initialized. Pass local_flags_config to constructor."
@@ -107,7 +105,7 @@ def local_flags(self) -> LocalFeatureFlagsProvider:
 
     @property
     def remote_flags(self) -> RemoteFeatureFlagsProvider:
-        """Get the remote flags provider if configured for it"""
+        """Get the remote flags provider if configured for it."""
         if self._remote_flags_provider is None:
             raise MixpanelException(
                 "No remote_flags_config was passed to the consttructor"
@@ -182,7 +180,6 @@ def import_data(
         for `more details
         <https://developer.mixpanel.com/reference/events#import-events>`__.
         """
-
         if api_secret is None:
             logger.warning(
                 "api_key will soon be removed from mixpanel-python; please use api_secret instead."
@@ -242,8 +239,7 @@ def alias(self, alias_id, original, meta=None):
         sync_consumer.send("events", json_dumps(event, cls=self._serializer))
 
     def merge(self, api_key, distinct_id1, distinct_id2, meta=None, api_secret=None):
-        """
-        Merges the two given distinct_ids.
+        """Merges the two given distinct_ids.
 
         :param str api_key: (DEPRECATED) Your Mixpanel project's API key.
         :param str distinct_id1: The first distinct_id to merge.
@@ -587,7 +583,7 @@ def group_delete(self, group_key, group_id, meta=None):
         )
 
     def group_update(self, message, meta=None):
-        """Send a generic group profile update
+        """Send a generic group profile update.
 
         :param dict message: the message to send
 
@@ -626,20 +622,18 @@ async def __aexit__(self, exc_type, exc_val, exc_tb):
             await self._remote_flags_provider.__aexit__(exc_type, exc_val, exc_tb)
 
 
-class MixpanelException(Exception):
+class MixpanelException(Exception):  # noqa: N818
     """Raised by consumers when unable to send messages.
 
     This could be caused by a network outage or interruption, or by an invalid
     endpoint passed to :meth:`.Consumer.send`.
     """
 
-    pass
 
+class Consumer:
+    """A consumer that sends an HTTP request directly to the Mixpanel service.
 
-class Consumer(object):
-    """
-    A consumer that sends an HTTP request directly to the Mixpanel service, one
-    per call to :meth:`~.send`.
+    One per call to :meth:`~.send`.
 
     :param str events_url: override the default events API endpoint
     :param str people_url: override the default people API endpoint
@@ -674,10 +668,10 @@ def __init__(
     ):
         # TODO: With next major version, make the above args kwarg-only, and reorder them.
         self._endpoints = {
-            "events": events_url or "https://{}/track".format(api_host),
-            "people": people_url or "https://{}/engage".format(api_host),
-            "groups": groups_url or "https://{}/groups".format(api_host),
-            "imports": import_url or "https://{}/import".format(api_host),
+            "events": events_url or f"https://{api_host}/track",
+            "people": people_url or f"https://{api_host}/engage",
+            "groups": groups_url or f"https://{api_host}/groups",
+            "imports": import_url or f"https://{api_host}/import",
         }
 
         self._verify_cert = verify_cert
@@ -717,11 +711,8 @@ def send(self, endpoint, json_message, api_key=None, api_secret=None):
             The *api_secret* parameter.
         """
         if endpoint not in self._endpoints:
-            raise MixpanelException(
-                'No such endpoint "{0}". Valid endpoints are one of {1}'.format(
-                    endpoint, self._endpoints.keys()
-                )
-            )
+            msg = f'No such endpoint "{endpoint}". Valid endpoints are one of {self._endpoints.keys()}'
+            raise MixpanelException(msg)
 
         self._write_request(
             self._endpoints[endpoint], json_message, api_key, api_secret
@@ -759,22 +750,19 @@ def _write_request(self, request_url, json_message, api_key=None, api_secret=Non
         try:
             response_dict = response.json()
         except ValueError:
-            raise MixpanelException(
-                "Cannot interpret Mixpanel server response: {0}".format(response.text)
-            )
+            msg = f"Cannot interpret Mixpanel server response: {response.text}"
+            raise MixpanelException(msg) from None
 
         if response_dict["status"] != 1:
-            raise MixpanelException(
-                "Mixpanel error: {0}".format(response_dict["error"])
-            )
+            raise MixpanelException("Mixpanel error: {}".format(response_dict["error"]))
 
         return True  # <- TODO: remove return val with major release.
 
 
-class BufferedConsumer(object):
-    """
-    A consumer that maintains per-endpoint buffers of messages and then sends
-    them in batches. This can save bandwidth and reduce the total amount of
+class BufferedConsumer:
+    """A consumer that maintains per-endpoint buffers of messages and then sends them in batches.
+
+    This can save bandwidth and reduce the total amount of
     time required to post your events to Mixpanel.
 
     :param int max_size: number of :meth:`~.send` calls for a given endpoint to
@@ -857,18 +845,15 @@ def send(self, endpoint, json_message, api_key=None, api_secret=None):
             The *api_key* parameter.
         """
         if endpoint not in self._buffers:
-            raise MixpanelException(
-                'No such endpoint "{0}". Valid endpoints are one of {1}'.format(
-                    endpoint, self._buffers.keys()
-                )
-            )
+            msg = f'No such endpoint "{endpoint}". Valid endpoints are one of {self._buffers.keys()}'
+            raise MixpanelException(msg)
 
         if not isinstance(api_key, tuple):
             api_key = (api_key, api_secret)
 
         buf = self._buffers[endpoint]
         buf.append(json_message)
-        # Fixme: Don't stick these in the instance.
+        # TODO: Don't stick these in the instance.
         self._api_key = api_key
         self._api_secret = api_secret
         if len(buf) >= self._max_size:
@@ -880,15 +865,15 @@ def flush(self):
         :raises MixpanelException: if the server is unreachable or any buffered
             message cannot be processed
         """
-        for endpoint in self._buffers.keys():
+        for endpoint in self._buffers:
             self._flush_endpoint(endpoint)
 
     def _flush_endpoint(self, endpoint):
         buf = self._buffers[endpoint]
 
         while buf:
             batch = buf[: self._max_size]
-            batch_json = "[{0}]".format(",".join(batch))
+            batch_json = "[{}]".format(",".join(batch))
             try:
                 self._consumer.send(endpoint, batch_json, api_key=self._api_key)
             except MixpanelException as orig_e: