understand-py 0.1.0__tar.gz

understand_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Understand
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

understand_py-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: understand-py
+Version: 0.1.0
+Summary: Framework-neutral Python SDK for sending logs and exceptions to Understand.io.
+Author: Understand
+License-Expression: MIT
+Keywords: understand.io,logging,errors,exceptions
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Understand Python
+
+Framework-neutral Python SDK for sending logs and exceptions to Understand.io.
+
+This package is for Python applications. It does not run inside Laravel and it
+does not reimplement the browser JavaScript SDK. Where it shares configuration
+names with the Laravel package, that is config parity only.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+python3 -m pip install understand-py
+```
+
+Or add it to `requirements.txt`:
+
+```text
+understand-py
+```
+
+## Configuration
+
+Set your Understand.io input token:
+
+```bash
+export UNDERSTAND_TOKEN="your-input-token"
+export UNDERSTAND_ENV="production"
+```
+
+Or configure it directly in code:
+
+```python
+from understand import UnderstandConfig
+
+config = UnderstandConfig(
+    token="your-input-token",
+    environment="production",
+)
+```
+
+## Basic Usage
+
+Send a log message:
+
+```python
+from understand import UnderstandConfig, UnderstandLogger
+
+logger = UnderstandLogger.from_config(
+    UnderstandConfig(token="your-input-token", environment="production")
+)
+
+logger.error("Understand.io test error", context={"source": "my-app"})
+```
+
+Capture and send an exception:
+
+```python
+from understand import UnderstandConfig, UnderstandLogger
+
+logger = UnderstandLogger.from_config(
+    UnderstandConfig(token="your-input-token", environment="production")
+)
+
+try:
+    raise RuntimeError("Payment capture failed")
+except RuntimeError as exc:
+    logger.exception(exc, context={"feature": "payments"})
+```
+
+## Stdlib Logging
+
+Attach Understand to Python's built-in `logging` package:
+
+```python
+import logging
+
+from understand import UnderstandConfig, UnderstandLogger
+from understand.integrations.logging import UnderstandLoggingHandler
+
+understand_logger = UnderstandLogger.from_config(
+    UnderstandConfig.from_env()
+)
+
+logging.getLogger().addHandler(UnderstandLoggingHandler(understand_logger))
+logging.getLogger().setLevel(logging.INFO)
+
+logging.error("This error is sent to Understand.io")
+```
+
+Exceptions logged with `exc_info=True` are sent as structured exception events:
+
+```python
+try:
+    raise ValueError("Invalid checkout amount")
+except ValueError:
+    logging.exception("Checkout failed")
+```
+
+## Request Context
+
+For web applications, attach request-like metadata before logging:
+
+```python
+from understand import RequestContext, UnderstandConfig, UnderstandLogger
+
+logger = UnderstandLogger.from_config(
+    UnderstandConfig(token="your-input-token", environment="production")
+)
+
+logger.field_provider.set_request_context(
+    RequestContext(
+        path="/checkout/payments",
+        method="POST",
+        route_name="payments.create",
+        query={"debug": "1"},
+        body={"amount": 4999, "password": "hidden automatically"},
+        client_ip="203.0.113.10",
+        user_agent="Mozilla/5.0",
+        user_id="user-123",
+        session_id="session-id",
+    )
+)
+```
+
+Fields like `password`, `password_confirmation`, `access_token`, `secret_key`,
+`token`, and `access_key` are replaced with `[value hidden]` by default.
+
+Environment variables:
+
+- `UNDERSTAND_TOKEN`
+- `UNDERSTAND_ENABLED`
+- `UNDERSTAND_API_URL`
+- `UNDERSTAND_HANDLER`
+- `UNDERSTAND_ENV`
+- `UNDERSTAND_SQL`
+- `UNDERSTAND_SQL_BINDINGS`
+- `UNDERSTAND_QUERY_STRING`
+- `UNDERSTAND_REQUEST_BODY`
+- `UNDERSTAND_POST_DATA` as a SDK config-parity alias for request body collection
+- `UNDERSTAND_HIDDEN_REQUEST_FIELDS`
+- `UNDERSTAND_SSL_CA_BUNDLE`
+
+For browser JavaScript error tracking, use the separate `understand-js` SDK.
+
+## Long-Running Workers
+
+For long-running workers, call `reset_context()` between jobs to regenerate the
+request token and clear collected data:
+
+```python
+for job in jobs:
+    logger.reset_context()
+
+    try:
+        process_job(job)
+    except Exception as exc:
+        logger.exception(exc, context={"job_id": job.id})
+```
+
+## Local Testing Without Sending Data
+
+Use `CallbackHandler` to inspect payloads without making network requests:
+
+```python
+import json
+
+from understand import CallbackHandler, UnderstandConfig, UnderstandLogger
+
+events = []
+logger = UnderstandLogger.from_config(
+    UnderstandConfig(token="test-token", environment="local"),
+    handler=CallbackHandler(lambda payload: events.append(json.loads(payload))),
+)
+
+logger.error("Local test error")
+
+print(json.dumps(events, indent=2))
+```

understand_py-0.1.0/README.md

@@ -0,0 +1,180 @@
+# Understand Python
+
+Framework-neutral Python SDK for sending logs and exceptions to Understand.io.
+
+This package is for Python applications. It does not run inside Laravel and it
+does not reimplement the browser JavaScript SDK. Where it shares configuration
+names with the Laravel package, that is config parity only.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+python3 -m pip install understand-py
+```
+
+Or add it to `requirements.txt`:
+
+```text
+understand-py
+```
+
+## Configuration
+
+Set your Understand.io input token:
+
+```bash
+export UNDERSTAND_TOKEN="your-input-token"
+export UNDERSTAND_ENV="production"
+```
+
+Or configure it directly in code:
+
+```python
+from understand import UnderstandConfig
+
+config = UnderstandConfig(
+    token="your-input-token",
+    environment="production",
+)
+```
+
+## Basic Usage
+
+Send a log message:
+
+```python
+from understand import UnderstandConfig, UnderstandLogger
+
+logger = UnderstandLogger.from_config(
+    UnderstandConfig(token="your-input-token", environment="production")
+)
+
+logger.error("Understand.io test error", context={"source": "my-app"})
+```
+
+Capture and send an exception:
+
+```python
+from understand import UnderstandConfig, UnderstandLogger
+
+logger = UnderstandLogger.from_config(
+    UnderstandConfig(token="your-input-token", environment="production")
+)
+
+try:
+    raise RuntimeError("Payment capture failed")
+except RuntimeError as exc:
+    logger.exception(exc, context={"feature": "payments"})
+```
+
+## Stdlib Logging
+
+Attach Understand to Python's built-in `logging` package:
+
+```python
+import logging
+
+from understand import UnderstandConfig, UnderstandLogger
+from understand.integrations.logging import UnderstandLoggingHandler
+
+understand_logger = UnderstandLogger.from_config(
+    UnderstandConfig.from_env()
+)
+
+logging.getLogger().addHandler(UnderstandLoggingHandler(understand_logger))
+logging.getLogger().setLevel(logging.INFO)
+
+logging.error("This error is sent to Understand.io")
+```
+
+Exceptions logged with `exc_info=True` are sent as structured exception events:
+
+```python
+try:
+    raise ValueError("Invalid checkout amount")
+except ValueError:
+    logging.exception("Checkout failed")
+```
+
+## Request Context
+
+For web applications, attach request-like metadata before logging:
+
+```python
+from understand import RequestContext, UnderstandConfig, UnderstandLogger
+
+logger = UnderstandLogger.from_config(
+    UnderstandConfig(token="your-input-token", environment="production")
+)
+
+logger.field_provider.set_request_context(
+    RequestContext(
+        path="/checkout/payments",
+        method="POST",
+        route_name="payments.create",
+        query={"debug": "1"},
+        body={"amount": 4999, "password": "hidden automatically"},
+        client_ip="203.0.113.10",
+        user_agent="Mozilla/5.0",
+        user_id="user-123",
+        session_id="session-id",
+    )
+)
+```
+
+Fields like `password`, `password_confirmation`, `access_token`, `secret_key`,
+`token`, and `access_key` are replaced with `[value hidden]` by default.
+
+Environment variables:
+
+- `UNDERSTAND_TOKEN`
+- `UNDERSTAND_ENABLED`
+- `UNDERSTAND_API_URL`
+- `UNDERSTAND_HANDLER`
+- `UNDERSTAND_ENV`
+- `UNDERSTAND_SQL`
+- `UNDERSTAND_SQL_BINDINGS`
+- `UNDERSTAND_QUERY_STRING`
+- `UNDERSTAND_REQUEST_BODY`
+- `UNDERSTAND_POST_DATA` as a SDK config-parity alias for request body collection
+- `UNDERSTAND_HIDDEN_REQUEST_FIELDS`
+- `UNDERSTAND_SSL_CA_BUNDLE`
+
+For browser JavaScript error tracking, use the separate `understand-js` SDK.
+
+## Long-Running Workers
+
+For long-running workers, call `reset_context()` between jobs to regenerate the
+request token and clear collected data:
+
+```python
+for job in jobs:
+    logger.reset_context()
+
+    try:
+        process_job(job)
+    except Exception as exc:
+        logger.exception(exc, context={"job_id": job.id})
+```
+
+## Local Testing Without Sending Data
+
+Use `CallbackHandler` to inspect payloads without making network requests:
+
+```python
+import json
+
+from understand import CallbackHandler, UnderstandConfig, UnderstandLogger
+
+events = []
+logger = UnderstandLogger.from_config(
+    UnderstandConfig(token="test-token", environment="local"),
+    handler=CallbackHandler(lambda payload: events.append(json.loads(payload))),
+)
+
+logger.error("Local test error")
+
+print(json.dumps(events, indent=2))
+```

understand_py-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "understand-py"
+version = "0.1.0"
+description = "Framework-neutral Python SDK for sending logs and exceptions to Understand.io."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  {name = "Understand"}
+]
+keywords = ["understand.io", "logging", "errors", "exceptions"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+

understand_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

understand_py-0.1.0/src/understand/__init__.py

@@ -0,0 +1,24 @@
+__version__ = "0.1.0"
+
+from .collector import DataCollector
+from .config import UnderstandConfig
+from .encoder import ExceptionEncoder
+from .fields import FieldProvider, RequestContext
+from .handlers import AsyncHandler, BaseHandler, CallbackHandler, SyncHandler
+from .logger import UnderstandLogger
+from .tokens import TokenProvider
+
+__all__ = [
+    "AsyncHandler",
+    "BaseHandler",
+    "CallbackHandler",
+    "DataCollector",
+    "ExceptionEncoder",
+    "FieldProvider",
+    "RequestContext",
+    "SyncHandler",
+    "TokenProvider",
+    "UnderstandConfig",
+    "UnderstandLogger",
+    "__version__",
+]

understand_py-0.1.0/src/understand/collector.py

@@ -0,0 +1,27 @@
+from typing import Any, Dict, List, Optional
+
+
+class DataCollector:
+    def __init__(self, limit: int = 50) -> None:
+        self._data: Dict[str, Any] = {}
+        self.limit = limit
+
+    def set_limit(self, limit: int) -> None:
+        self.limit = limit
+
+    def reset(self) -> None:
+        self._data = {}
+
+    def set(self, key: str, value: Any) -> None:
+        self._data[key] = value
+
+    def set_in_array(self, key: str, value: Any) -> None:
+        values: List[Any] = list(self._data.get(key, []))
+        if len(values) > self.limit - 1:
+            values.pop(0)
+        values.append(value)
+        self._data[key] = values
+
+    def get_by_key(self, key: str) -> Optional[Any]:
+        return self._data.get(key)
+

understand_py-0.1.0/src/understand/config.py

@@ -0,0 +1,82 @@
+from dataclasses import dataclass, field
+import os
+from pathlib import Path
+from typing import Callable, Optional, Sequence, Tuple
+
+
+DEFAULT_HIDDEN_FIELDS = (
+    "password",
+    "password_confirmation",
+    "access_token",
+    "secret_key",
+    "token",
+    "access_key",
+)
+
+
+def _parse_bool(value: Optional[str], default: bool) -> bool:
+    if value is None:
+        return default
+
+    normalized = value.strip().lower()
+    if normalized in {"1", "true", "yes", "y", "on"}:
+        return True
+    if normalized in {"0", "false", "no", "n", "off"}:
+        return False
+    return default
+
+
+def _parse_csv(value: Optional[str], default: Sequence[str]) -> Tuple[str, ...]:
+    if value is None:
+        return tuple(default)
+
+    return tuple(part.strip() for part in value.split(",") if part.strip())
+
+
+@dataclass(frozen=True)
+class UnderstandConfig:
+    token: Optional[str] = None
+    enabled: bool = True
+    api_url: str = "https://api.understand.io"
+    handler: str = "sync"
+    project_root: Path = field(default_factory=Path.cwd)
+    environment: Optional[str] = None
+    sql_enabled: bool = True
+    sql_bindings: bool = False
+    query_string_enabled: bool = True
+    request_body_enabled: bool = True
+    hidden_fields: Tuple[str, ...] = DEFAULT_HIDDEN_FIELDS
+    ignored_logs: Tuple[str, ...] = ()
+    log_filter: Optional[Callable[[str, object, object], bool]] = None
+    timeout: float = 5.0
+    stack_trace_limit: int = 100
+    ssl_ca_bundle: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "project_root", Path(self.project_root))
+        object.__setattr__(self, "hidden_fields", tuple(self.hidden_fields))
+        object.__setattr__(self, "ignored_logs", tuple(self.ignored_logs))
+
+    @classmethod
+    def from_env(cls, project_root: Optional[Path] = None) -> "UnderstandConfig":
+        request_body_value = os.environ.get("UNDERSTAND_REQUEST_BODY")
+        if request_body_value is None:
+            request_body_value = os.environ.get("UNDERSTAND_POST_DATA")
+
+        return cls(
+            token=os.environ.get("UNDERSTAND_TOKEN"),
+            enabled=_parse_bool(os.environ.get("UNDERSTAND_ENABLED"), True),
+            api_url=os.environ.get("UNDERSTAND_API_URL", "https://api.understand.io"),
+            handler=os.environ.get("UNDERSTAND_HANDLER", "sync"),
+            project_root=project_root if project_root is not None else Path.cwd(),
+            environment=os.environ.get("UNDERSTAND_ENV"),
+            sql_enabled=_parse_bool(os.environ.get("UNDERSTAND_SQL"), True),
+            sql_bindings=_parse_bool(os.environ.get("UNDERSTAND_SQL_BINDINGS"), False),
+            query_string_enabled=_parse_bool(os.environ.get("UNDERSTAND_QUERY_STRING"), True),
+            request_body_enabled=_parse_bool(request_body_value, True),
+            hidden_fields=_parse_csv(
+                os.environ.get("UNDERSTAND_HIDDEN_REQUEST_FIELDS"),
+                DEFAULT_HIDDEN_FIELDS,
+            ),
+            ssl_ca_bundle=os.environ.get("UNDERSTAND_SSL_CA_BUNDLE"),
+        )

understand_py-0.1.0/src/understand/encoder.py

@@ -0,0 +1,96 @@
+import inspect
+from pathlib import Path
+import traceback
+from types import TracebackType
+from typing import Any, Dict, Iterable, List, Optional
+
+from .config import UnderstandConfig
+
+
+class ExceptionEncoder:
+    def __init__(self, config: Optional[UnderstandConfig] = None) -> None:
+        self.config = config or UnderstandConfig()
+
+    def exception_to_dict(self, exception: BaseException) -> Dict[str, Any]:
+        if not isinstance(exception, BaseException):
+            raise TypeError("exception must be an instance of BaseException")
+
+        frames = self._traceback_to_frames(exception.__traceback__)
+        top = frames[-1] if frames else None
+        file_name = self._relative_path(top.filename) if top else None
+        line = top.lineno if top else None
+        class_name = exception.__class__.__name__
+        message = str(exception) if str(exception) else class_name
+
+        return {
+            "message": message,
+            "class": class_name,
+            "code": getattr(exception, "errno", None),
+            "file": file_name,
+            "line": line,
+            "stack": self.stack_trace_to_list(frames),
+        }
+
+    def set_current_stack_trace(self, error_log: Dict[str, Any]) -> Dict[str, Any]:
+        frames = [
+            frame
+            for frame in inspect.stack()[1 : self.config.stack_trace_limit + 1]
+            if "/understand/" not in frame.filename.replace("\\", "/")
+        ]
+        stack = self.stack_trace_to_list(frames)
+        if stack:
+            error_log["class"] = None
+            error_log["file"] = stack[0]["file"]
+            error_log["line"] = stack[0]["line"]
+        error_log["stack"] = stack
+        return error_log
+
+    def stack_trace_to_list(self, frames: Iterable[Any]) -> List[Dict[str, Any]]:
+        stack = []
+        for frame in list(frames)[-self.config.stack_trace_limit :]:
+            filename = getattr(frame, "filename", None)
+            lineno = getattr(frame, "lineno", None)
+            function = getattr(frame, "name", None) or getattr(frame, "function", None)
+            relative = self._relative_path(filename) if filename else None
+            stack.append(
+                {
+                    "class": None,
+                    "function": function,
+                    "args": [],
+                    "type": "function",
+                    "file": relative,
+                    "line": lineno,
+                    "code": self.get_code(relative, lineno),
+                }
+            )
+        return stack
+
+    def get_code(self, relative_path: Optional[str], line: Optional[int], lines_around: int = 6) -> Optional[List[Dict[str, Any]]]:
+        if not relative_path or not line:
+            return None
+
+        path = self.config.project_root / relative_path
+        try:
+            lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+        except OSError:
+            return None
+
+        start = max(1, line - lines_around)
+        end = min(len(lines), line + lines_around)
+        return [{"line": number, "code": lines[number - 1][:250].rstrip()} for number in range(start, end + 1)]
+
+    def _traceback_to_frames(self, tb: Optional[TracebackType]) -> List[traceback.FrameSummary]:
+        if tb is None:
+            return []
+        return traceback.extract_tb(tb)
+
+    def _relative_path(self, filename: Optional[str]) -> Optional[str]:
+        if filename is None:
+            return None
+
+        path = Path(filename)
+        try:
+            return str(path.resolve().relative_to(self.config.project_root.resolve()))
+        except ValueError:
+            return str(path)
+