understand-py 0.1.0__py3-none-any.whl

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/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/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/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)
+

understand/fields.py

@@ -0,0 +1,210 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+import hashlib
+import platform
+import sys
+from typing import Any, Callable, Dict, Mapping, Optional
+
+from .collector import DataCollector
+from .config import UnderstandConfig
+from .tokens import TokenProvider
+
+
+@dataclass
+class RequestContext:
+    path: Optional[str] = None
+    method: Optional[str] = None
+    query: Mapping[str, Any] = field(default_factory=dict)
+    body: Mapping[str, Any] = field(default_factory=dict)
+    client_ip: Optional[str] = None
+    server_ip: Optional[str] = None
+    user_agent: Optional[str] = None
+    host: Optional[str] = None
+    origin: Optional[str] = None
+    session_id: Optional[str] = None
+    session: Mapping[str, Any] = field(default_factory=dict)
+    user_id: Optional[Any] = None
+    route_name: Optional[str] = None
+
+
+class FieldProvider:
+    def __init__(
+        self,
+        config: Optional[UnderstandConfig] = None,
+        token_provider: Optional[TokenProvider] = None,
+        data_collector: Optional[DataCollector] = None,
+    ) -> None:
+        self.config = config or UnderstandConfig()
+        self.token_provider = token_provider or TokenProvider()
+        self.data_collector = data_collector or DataCollector()
+        self.request_context: Optional[RequestContext] = None
+        self._providers: Dict[str, Callable[..., Any]] = {}
+
+    def extend(self, name: str, provider: Callable[..., Any]) -> None:
+        self._providers[name] = provider
+
+    def __getattr__(self, name: str) -> Any:
+        if name in self._providers:
+            return self._providers[name]
+        raise AttributeError(name)
+
+    def set_request_context(self, request_context: Optional[RequestContext]) -> None:
+        self.request_context = request_context
+
+    def resolve_values(
+        self,
+        callbacks: Mapping[str, Callable[[Mapping[str, Any]], Any]],
+        log: Mapping[str, Any],
+    ) -> Dict[str, Any]:
+        data: Dict[str, Any] = {}
+        for field_name, callback in callbacks.items():
+            try:
+                data[field_name] = callback(log)
+            except Exception:
+                data[field_name] = None
+        return data
+
+    def get_session_id(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[str]:
+        if not self.request_context or not self.request_context.session_id:
+            return None
+        return hashlib.sha1(self.request_context.session_id.encode("utf-8")).hexdigest()
+
+    def get_request_id(self, _log: Optional[Mapping[str, Any]] = None) -> str:
+        return self.token_provider.get_token()
+
+    def get_process_identifier(self, _log: Optional[Mapping[str, Any]] = None) -> str:
+        return self.get_request_id()
+
+    def get_user_id(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[Any]:
+        if not self.request_context:
+            return None
+        return self.request_context.user_id
+
+    def get_environment(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[str]:
+        return self.config.environment
+
+    def get_url(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[str]:
+        if not self.request_context or self.request_context.path is None:
+            return None
+        path = self.request_context.path
+        return path if path.startswith("/") else "/" + path
+
+    def get_request_method(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[str]:
+        if not self.request_context:
+            return None
+        return self.request_context.method
+
+    def get_route_name(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[str]:
+        if not self.request_context:
+            return None
+        return self.request_context.route_name
+
+    def get_from_session(self, key: str) -> Optional[Any]:
+        if not self.request_context:
+            return None
+        return self.request_context.session.get(key)
+
+    def get_query_string_array(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[Dict[str, Any]]:
+        if not self.config.query_string_enabled:
+            return None
+        if not self.request_context:
+            return None
+        return self._parse_request_mapping(self.request_context.query)
+
+    def get_request_body_data(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[Dict[str, Any]]:
+        if not self.config.request_body_enabled:
+            return None
+        if not self.request_context:
+            return None
+        if self.request_context.method and self.request_context.method.upper() in {"GET", "HEAD"}:
+            return None
+        return self._parse_request_mapping(self.request_context.body)
+
+    def get_post_data_array(self, log: Optional[Mapping[str, Any]] = None) -> Optional[Dict[str, Any]]:
+        return self.get_request_body_data(log)
+
+    def get_client_ip(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[str]:
+        return self.request_context.client_ip if self.request_context else None
+
+    def get_server_ip(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[str]:
+        return self.request_context.server_ip if self.request_context else None
+
+    def get_client_user_agent(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[str]:
+        return self.request_context.user_agent if self.request_context else None
+
+    def get_host(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[str]:
+        return self.request_context.host if self.request_context else None
+
+    def get_origin(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[str]:
+        return self.request_context.origin if self.request_context else None
+
+    def get_python_version(self, _log: Optional[Mapping[str, Any]] = None) -> str:
+        return platform.python_version()
+
+    def get_logger_version(self, _log: Optional[Mapping[str, Any]] = None) -> str:
+        from . import __version__
+
+        return __version__
+
+    def get_console(self, _log: Optional[Mapping[str, Any]] = None) -> bool:
+        return True
+
+    def get_command(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[str]:
+        return " ".join(sys.argv) if sys.argv else None
+
+    def get_artisan_command_name(self, log: Optional[Mapping[str, Any]] = None) -> Optional[str]:
+        return self.get_command(log)
+
+    def get_sql_queries(self, _log: Optional[Mapping[str, Any]] = None) -> Optional[Any]:
+        if not self.config.sql_enabled:
+            return None
+        queries = self.data_collector.get_by_key("sql_queries")
+        if not queries:
+            return None
+
+        result = []
+        for query in queries:
+            query_dict = dict(query)
+            bindings = list(query_dict.pop("bindings", []))
+            if self.config.sql_bindings:
+                query_dict["query"] = self._merge_bindings(str(query_dict.get("query", "")), bindings)
+            result.append(query_dict)
+        return result
+
+    def get_group_id(self, log: Mapping[str, Any]) -> str:
+        parts = []
+        for field_name in ("class", "file", "line", "code"):
+            value = log.get(field_name)
+            if field_name == "code" and (not value or value == "0"):
+                continue
+            parts.append("" if value is None else str(value))
+        return hashlib.sha1("#".join(parts).encode("utf-8")).hexdigest()
+
+    def _parse_request_mapping(self, mapping: Mapping[str, Any]) -> Dict[str, Any]:
+        parsed: Dict[str, Any] = {}
+        for key, value in mapping.items():
+            try:
+                parsed[key] = self._parse_request_field_value(key, value)
+            except Exception:
+                parsed[key] = "[handler error]"
+        return parsed
+
+    def _parse_request_field_value(self, key: str, value: Any) -> Any:
+        if key in self.config.hidden_fields:
+            return "[value hidden]"
+        if isinstance(value, (str, int, float, bool)) or value is None:
+            return value
+        if isinstance(value, (list, tuple, dict, set)):
+            return repr(value)
+        return value.__class__.__name__
+
+    def _merge_bindings(self, query: str, bindings: Any) -> str:
+        for value in bindings:
+            if isinstance(value, datetime):
+                binding = value.strftime("%Y-%m-%d %H:%M:%S")
+            elif isinstance(value, bool):
+                binding = "1" if value else "0"
+            else:
+                binding = str(value)
+            query = query.replace("?", binding, 1)
+        return query

understand/handlers.py

@@ -0,0 +1,69 @@
+import json
+import subprocess
+from typing import Any, Callable, Dict, Optional
+from urllib import request
+
+from .config import UnderstandConfig
+
+
+class BaseHandler:
+    def __init__(self, config: Optional[UnderstandConfig] = None) -> None:
+        self.config = config or UnderstandConfig()
+
+    def handle(self, request_data: Dict[str, Any]) -> Any:
+        payload = json.dumps(request_data, default=str)
+        response = self.send(payload)
+        return self.parse_response(response)
+
+    def send(self, data: str) -> Optional[str]:
+        raise NotImplementedError
+
+    def get_endpoint(self) -> str:
+        return "/".join([self.config.api_url.rstrip("/"), str(self.config.token or "")])
+
+    def parse_response(self, response: Optional[str]) -> Any:
+        if response is None:
+            return None
+        if response == "":
+            return None
+        return json.loads(response)
+
+
+class SyncHandler(BaseHandler):
+    def send(self, data: str) -> Optional[str]:
+        req = request.Request(
+            self.get_endpoint(),
+            data=data.encode("utf-8"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "User-Agent": "Understand Python SDK.",
+            },
+        )
+        kwargs = {"timeout": self.config.timeout}
+        if self.config.ssl_ca_bundle:
+            kwargs["cafile"] = self.config.ssl_ca_bundle
+        with request.urlopen(req, **kwargs) as response:
+            return response.read().decode("utf-8")
+
+
+class AsyncHandler(BaseHandler):
+    def send(self, data: str) -> None:
+        if len(data) >= 2_000_000:
+            return None
+
+        subprocess.Popen(
+            ["curl", "-X", "POST", "-d", data, self.get_endpoint()],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        return None
+
+
+class CallbackHandler(BaseHandler):
+    def __init__(self, callback: Callable[[str], Optional[str]], config: Optional[UnderstandConfig] = None) -> None:
+        super().__init__(config)
+        self.callback = callback
+
+    def send(self, data: str) -> Optional[str]:
+        return self.callback(data)

understand/integrations/__init__.py

@@ -0,0 +1 @@
+

understand/integrations/logging.py

@@ -0,0 +1,35 @@
+import logging
+import sys
+from typing import Optional
+
+from ..config import UnderstandConfig
+from ..logger import UnderstandLogger
+
+
+class UnderstandLoggingHandler(logging.Handler):
+    def __init__(self, understand_logger: UnderstandLogger, level: int = logging.NOTSET) -> None:
+        super().__init__(level)
+        self.understand_logger = understand_logger
+
+    @classmethod
+    def from_config(cls, config: Optional[UnderstandConfig] = None) -> "UnderstandLoggingHandler":
+        return cls(UnderstandLogger.from_config(config or UnderstandConfig.from_env()))
+
+    def emit(self, record: logging.LogRecord) -> None:
+        context = {
+            "logger_name": record.name,
+            "module": record.module,
+            "pathname": record.pathname,
+            "lineno": record.lineno,
+        }
+        level = record.levelname.lower()
+
+        exc_info = record.exc_info
+        if exc_info is True:
+            exc_info = sys.exc_info()
+
+        if exc_info and exc_info[1]:
+            self.understand_logger.exception(exc_info[1], level=level, context=context)
+            return
+
+        self.understand_logger.log(record.getMessage(), level=level, context=context)

understand/logger.py

@@ -0,0 +1,162 @@
+import time
+from typing import Any, Dict, Mapping, Optional
+
+from .collector import DataCollector
+from .config import UnderstandConfig
+from .encoder import ExceptionEncoder
+from .fields import FieldProvider
+from .handlers import AsyncHandler, BaseHandler, SyncHandler
+from .tokens import TokenProvider
+
+
+class UnderstandLogger:
+    def __init__(
+        self,
+        config: Optional[UnderstandConfig] = None,
+        field_provider: Optional[FieldProvider] = None,
+        handler: Optional[BaseHandler] = None,
+        encoder: Optional[ExceptionEncoder] = None,
+    ) -> None:
+        self.config = config or UnderstandConfig()
+        self.field_provider = field_provider or FieldProvider(
+            config=self.config,
+            token_provider=TokenProvider(),
+            data_collector=DataCollector(),
+        )
+        self.handler = handler or self._handler_from_config(self.config)
+        if getattr(self.handler, "config", None) is None:
+            self.handler.config = self.config
+        else:
+            self.handler.config = self.config
+        self.encoder = encoder or ExceptionEncoder(self.config)
+
+    @classmethod
+    def from_config(
+        cls,
+        config: Optional[UnderstandConfig] = None,
+        handler: Optional[BaseHandler] = None,
+    ) -> "UnderstandLogger":
+        return cls(config=config or UnderstandConfig.from_env(), handler=handler)
+
+    def log(
+        self,
+        message: Any,
+        level: str = "error",
+        context: Optional[Mapping[str, Any]] = None,
+        additional: Optional[Mapping[str, Any]] = None,
+        custom_fields: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        if not self._can_deliver(level, message, context):
+            return False
+
+        log = dict(message) if isinstance(message, Mapping) else {"message": message}
+        log["message"] = self._format_message(log.get("message"))
+        log["level"] = level
+        log.setdefault("tags", ["python_log"])
+        if context:
+            log["context"] = dict(context)
+
+        event = self._prepare(log, additional or self.event_meta_fields(), custom_fields or {})
+        return self._send(event)
+
+    def error(self, message: Any, level: str = "error", context: Optional[Mapping[str, Any]] = None) -> Any:
+        return self.log(message, level=level, context=context)
+
+    def reset_context(self) -> None:
+        self.field_provider.token_provider.generate()
+        self.field_provider.data_collector.reset()
+
+    def exception(
+        self,
+        exception: BaseException,
+        level: str = "error",
+        context: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        if not self._can_deliver(level, exception, context):
+            return False
+
+        log = self.encoder.exception_to_dict(exception)
+        log["level"] = level
+        log["tags"] = ["py_error_log"]
+        if context:
+            log["context"] = dict(context)
+        event = self._prepare(log, self.error_meta_fields(), {})
+        return self._send(event)
+
+    def event_meta_fields(self) -> Dict[str, Any]:
+        return {
+            "session_id": self.field_provider.get_session_id,
+            "request_id": self.field_provider.get_request_id,
+            "user_id": self.field_provider.get_user_id,
+            "env": self.field_provider.get_environment,
+            "url": self.field_provider.get_url,
+            "route": self.field_provider.get_route_name,
+            "method": self.field_provider.get_request_method,
+            "client_ip": self.field_provider.get_client_ip,
+            "server_ip": self.field_provider.get_server_ip,
+        }
+
+    def error_meta_fields(self) -> Dict[str, Any]:
+        return {
+            "session_id": self.field_provider.get_session_id,
+            "request_id": self.field_provider.get_request_id,
+            "group_id": self.field_provider.get_group_id,
+            "user_id": self.field_provider.get_user_id,
+            "env": self.field_provider.get_environment,
+            "url": self.field_provider.get_url,
+            "route": self.field_provider.get_route_name,
+            "method": self.field_provider.get_request_method,
+            "query_string_data": self.field_provider.get_query_string_array,
+            "request_body_data": self.field_provider.get_request_body_data,
+            "client_ip": self.field_provider.get_client_ip,
+            "server_ip": self.field_provider.get_server_ip,
+            "user_agent": self.field_provider.get_client_user_agent,
+            "host": self.field_provider.get_host,
+            "origin": self.field_provider.get_origin,
+            "python_version": self.field_provider.get_python_version,
+            "sql_queries": self.field_provider.get_sql_queries,
+            "console": self.field_provider.get_console,
+            "command": self.field_provider.get_command,
+            "logger_version": self.field_provider.get_logger_version,
+        }
+
+    def _prepare(
+        self,
+        log: Dict[str, Any],
+        additional: Mapping[str, Any],
+        custom_fields: Mapping[str, Any],
+    ) -> Dict[str, Any]:
+        data = self.field_provider.resolve_values(additional, log)
+        if custom_fields:
+            data["custom"] = self.field_provider.resolve_values(custom_fields, log)
+        event = dict(data)
+        event.update(log)
+        event.setdefault("timestamp", round(time.time() * 1000))
+        return event
+
+    def _send(self, event: Dict[str, Any]) -> Any:
+        try:
+            return self.handler.handle(event)
+        except Exception:
+            return False
+
+    def _can_deliver(self, level: str, message: Any, context: Optional[Mapping[str, Any]]) -> bool:
+        if not self.config.enabled:
+            return False
+        if level in self.config.ignored_logs:
+            return False
+        if self.config.log_filter and self.config.log_filter(level, message, context or {}):
+            return False
+        return True
+
+    def _format_message(self, message: Any) -> str:
+        if isinstance(message, bool):
+            return "1" if message else "0"
+        return str(message)
+
+    def _handler_from_config(self, config: UnderstandConfig) -> BaseHandler:
+        if config.handler == "async":
+            return AsyncHandler(config)
+        if config.handler == "sync":
+            return SyncHandler(config)
+        raise ValueError("understand handler misconfiguration: " + str(config.handler))

understand/tokens.py

@@ -0,0 +1,15 @@
+import uuid
+
+
+class TokenProvider:
+    def __init__(self) -> None:
+        self._token = ""
+        self.generate()
+
+    def get_token(self) -> str:
+        return self._token
+
+    def generate(self) -> str:
+        self._token = str(uuid.uuid4())
+        return self._token
+

understand_py-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+understand/__init__.py,sha256=Rr0q4VNH2ZOoWOfetBM0PY4LzxH0zLYbJA-S9kkzXwA,606
+understand/collector.py,sha256=w7lJnTvAJ3t2BY9DL-Dg9rC_Atp6WSepbA-ri7753nk,729
+understand/config.py,sha256=cTkGPrDjhmWNiGET4a9K-hTshCwlLbSo3dbZ8gkSAZQ,3047
+understand/encoder.py,sha256=fzNp5Q4bUkEdVTppvhLIkaK8ZGWx4LbotEY1oufyB0k,3623
+understand/fields.py,sha256=oJmPQ1IRaKfRMItULBn6wWnYf5XMm_nWG9XPONdGcJU,8459
+understand/handlers.py,sha256=bH9vD-_F82wYytFha4GrBWf-rzMeau79FaLm9Cwz1uk,2163
+understand/logger.py,sha256=q0a4lZmnm0bNKkgco9xayAYYvZ1gmlg0HjJU8eO-Efg,6411
+understand/tokens.py,sha256=XWCgHaHtSW7kr714P-tI9uvHVtqtlYBzvSRXlBfTWjg,276
+understand/integrations/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+understand/integrations/logging.py,sha256=u4tuoc-vUuhEiqJUn0A-_zG5a9dOQDOaF_CcAySjpes,1185
+understand_py-0.1.0.dist-info/licenses/LICENSE,sha256=NHJ7d9VWCwf75SOiL_AGi1HTW-YP0Uc61tuv91OFoow,1067
+understand_py-0.1.0.dist-info/METADATA,sha256=1_ir5-AYjmGZl1Khczgr2kuk3dI3ZAzJF0yIy6x_Gu0,5115
+understand_py-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+understand_py-0.1.0.dist-info/top_level.txt,sha256=8YPA5IZJjDAFG-Xw_Qv2E-1_HJSIzbsXSvD4hughEh4,11
+understand_py-0.1.0.dist-info/RECORD,,

understand_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

understand_py-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+understand