neutronium 0.1.0__tar.gz

neutronium-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gaussian Holdings, LLC
+
+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.

neutronium-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: neutronium
+Version: 0.1.0
+Summary: Framework-agnostic Python utilities: text, time, iterables, structured logging, telemetry primitives, and more.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gaussian/neutronium
+Project-URL: Issues, https://github.com/gaussian/neutronium/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: text
+Requires-Dist: inflection; extra == "text"
+Provides-Extra: time
+Requires-Dist: python-dateutil; extra == "time"
+Provides-Extra: memory
+Requires-Dist: psutil; extra == "memory"
+Requires-Dist: pympler; extra == "memory"
+Requires-Dist: objgraph; extra == "memory"
+Provides-Extra: aws
+Requires-Dist: boto3>=1.36; extra == "aws"
+Requires-Dist: requests>=2.23; extra == "aws"
+Requires-Dist: ec2-metadata; extra == "aws"
+Provides-Extra: xpath
+Requires-Dist: lxml; extra == "xpath"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api; extra == "otel"
+Provides-Extra: profiling
+Requires-Dist: line_profiler; extra == "profiling"
+Dynamic: license-file
+
+# neutronium
+
+Framework-agnostic Python utilities, extracted from Gaussian's internal
+infrastructure. No Django, no web framework, no cloud SDK in the base install —
+everything third-party is an optional extra.
+
+```sh
+pip install neutronium              # base: zero dependencies
+pip install neutronium[text]        # inflection-backed pluralize/singularize
+pip install neutronium[xpath]       # lxml-backed HTML/XPath helpers
+```
+
+## What's inside
+
+| Module | What it gives you |
+|---|---|
+| `neutronium.utils.text` | Text normalization, slugs, tokenization, pluralize/singularize |
+| `neutronium.utils.time` | Timezone-aware datetime helpers |
+| `neutronium.utils.iterable` | Chunking, grouping, flattening, dict utilities |
+| `neutronium.utils.template_context` | Pure template-variable extraction and context building |
+| `neutronium.utils.json_patch` | RFC-6901 JSON pointer / merge-patch primitives |
+| `neutronium.utils.hash` | `blake2b` content hashing helpers |
+| `neutronium.utils.schema` | JSON-schema → default-dict |
+| `neutronium.utils.xpath` | lxml HTML parsing + link extraction (`[xpath]`) |
+| `neutronium.utils.email` | Canonical email normalization |
+| `neutronium.utils.{aws,ssm}` | EC2/ECS instance metadata + SSM parameter fetch (`[aws]`) |
+| `neutronium.utils.{print,params,profiling,memory,url_credentials}` | Assorted small utilities |
+| `neutronium.threads.thread_simple` | Minimal threading helpers |
+| `neutronium.telemetry` | Request-context vars, `RequestFacts`, pluggable sinks |
+| `neutronium.logging` | JSON / dev-console log formatters and context filters |
+
+## Optional extras
+
+`text`, `time`, `aws`, `memory`, `xpath`, `otel`, `profiling` — install only what you use.
+
+- `aws` → `boto3`, `requests`, `ec2-metadata` (for `neutronium.utils.aws` / `ssm`)
+
+## Development
+
+```sh
+uv sync --group dev
+uv run pytest
+```
+
+## License
+
+MIT © Gaussian Holdings, LLC

neutronium-0.1.0/README.md

@@ -0,0 +1,47 @@
+# neutronium
+
+Framework-agnostic Python utilities, extracted from Gaussian's internal
+infrastructure. No Django, no web framework, no cloud SDK in the base install —
+everything third-party is an optional extra.
+
+```sh
+pip install neutronium              # base: zero dependencies
+pip install neutronium[text]        # inflection-backed pluralize/singularize
+pip install neutronium[xpath]       # lxml-backed HTML/XPath helpers
+```
+
+## What's inside
+
+| Module | What it gives you |
+|---|---|
+| `neutronium.utils.text` | Text normalization, slugs, tokenization, pluralize/singularize |
+| `neutronium.utils.time` | Timezone-aware datetime helpers |
+| `neutronium.utils.iterable` | Chunking, grouping, flattening, dict utilities |
+| `neutronium.utils.template_context` | Pure template-variable extraction and context building |
+| `neutronium.utils.json_patch` | RFC-6901 JSON pointer / merge-patch primitives |
+| `neutronium.utils.hash` | `blake2b` content hashing helpers |
+| `neutronium.utils.schema` | JSON-schema → default-dict |
+| `neutronium.utils.xpath` | lxml HTML parsing + link extraction (`[xpath]`) |
+| `neutronium.utils.email` | Canonical email normalization |
+| `neutronium.utils.{aws,ssm}` | EC2/ECS instance metadata + SSM parameter fetch (`[aws]`) |
+| `neutronium.utils.{print,params,profiling,memory,url_credentials}` | Assorted small utilities |
+| `neutronium.threads.thread_simple` | Minimal threading helpers |
+| `neutronium.telemetry` | Request-context vars, `RequestFacts`, pluggable sinks |
+| `neutronium.logging` | JSON / dev-console log formatters and context filters |
+
+## Optional extras
+
+`text`, `time`, `aws`, `memory`, `xpath`, `otel`, `profiling` — install only what you use.
+
+- `aws` → `boto3`, `requests`, `ec2-metadata` (for `neutronium.utils.aws` / `ssm`)
+
+## Development
+
+```sh
+uv sync --group dev
+uv run pytest
+```
+
+## License
+
+MIT © Gaussian Holdings, LLC

neutronium-0.1.0/neutronium/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

neutronium-0.1.0/neutronium/logging/filters.py

@@ -0,0 +1,55 @@
+import logging
+
+try:
+    from opentelemetry import trace
+except ImportError:
+    trace = None  # OpenTelemetry not installed
+
+from neutronium.telemetry.context import (
+    client_ip_var,
+    enterprise_id_var,
+    request_id_var,
+    user_id_var,
+)
+
+
+def _trace_id_hex(ctx) -> str:
+    """Convert an OTel trace ID integer to hex string."""
+    return format(ctx.trace_id, "032x")
+
+
+def _span_id_hex(ctx) -> str:
+    """Convert an OTel span ID integer to hex string."""
+    return format(ctx.span_id, "016x")
+
+
+class ContextFilter(logging.Filter):
+    """
+    Logging filter that injects request context and OpenTelemetry/X-Ray IDs into log records.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        # App context from contextvars
+        record.request_id = request_id_var.get()
+        record.user_id = user_id_var.get()
+        record.client_ip = client_ip_var.get()
+        record.enterprise_id = enterprise_id_var.get()
+
+        # OTel / X-Ray context (trace_id, span_id)
+        if trace:
+            ctx = trace.get_current_span().get_span_context()
+            if ctx.is_valid:
+                record.trace_id = _trace_id_hex(ctx)
+                record.span_id = _span_id_hex(ctx)
+                record.trace_sampled = bool(ctx.trace_flags.sampled)
+            else:
+                record.trace_id = None
+                record.span_id = None
+                record.trace_sampled = None
+        else:
+            # OpenTelemetry not installed, skip trace context
+            record.trace_id = None
+            record.span_id = None
+            record.trace_sampled = None
+
+        return True

neutronium-0.1.0/neutronium/logging/formatters.py

@@ -0,0 +1,129 @@
+import json
+import logging
+import os
+from datetime import datetime, timezone
+from uuid import UUID
+
+SERVICE_NAME = os.environ.get("OTEL_SERVICE_NAME")
+
+
+def _json_default(obj):
+    """Handle JSON serialization of non-standard types."""
+    if isinstance(obj, UUID):
+        return str(obj)
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+class JsonFormatter(logging.Formatter):
+    """JSON formatter with ordered fields and null value omission."""
+
+    # Maps record attribute names to JSON output field names
+    CONTEXT_FIELDS = {
+        "request_id": "request_id",
+        "client_ip": "client_ip",
+        "user_id": "user.id",
+        "enterprise_id": "enterprise.id",
+        "trace_id": "trace_id",
+        "span_id": "span_id",
+        "trace_sampled": "trace.sampled",
+        # HTTP request fields from AccessLogMiddleware
+        "http.method": "http.method",
+        "http.path": "http.path",
+        "http.route": "http.route",
+        "http.status_code": "http.status_code",
+        "http.user_agent": "http.user_agent",
+        "duration_ms": "duration_ms",
+        "user.is_privileged": "user.is_privileged",
+        "django.view": "django.view",
+    }
+
+    def format(self, record: logging.LogRecord) -> str:
+        # Build payload with explicit field ordering
+        payload = {
+            "timestamp": datetime.fromtimestamp(
+                record.created, tz=timezone.utc
+            ).isoformat(),
+            "level": record.levelname.lower(),
+            "message": record.getMessage(),
+            "logger": record.name,
+        }
+
+        if SERVICE_NAME:
+            payload["service.name"] = SERVICE_NAME
+
+        # Add context fields (injected by ContextFilter)
+        for attr, output_name in self.CONTEXT_FIELDS.items():
+            value = getattr(record, attr, None)
+            if value is not None:
+                payload[output_name] = value
+
+        # Include structured exception info if present
+        if record.exc_info:
+            exc_type, exc_value, _ = record.exc_info
+            if exc_type is not None:
+                payload["error.type"] = exc_type.__name__
+            if exc_value is not None:
+                payload["error.message"] = str(exc_value)
+            payload["error.stack_trace"] = self.formatException(record.exc_info)
+
+        # Include stack_info if requested (e.g., logger.info("msg", stack_info=True))
+        if record.stack_info:
+            payload["stack_info"] = self.formatStack(record.stack_info)
+
+        return json.dumps(payload, default=_json_default)
+
+
+class DevConsoleFormatter(logging.Formatter):
+    """Human-readable formatter for local development."""
+
+    # Standard LogRecord attributes to exclude when looking for extra fields
+    _STANDARD_ATTRS = frozenset(
+        {
+            "name",
+            "msg",
+            "args",
+            "created",
+            "filename",
+            "funcName",
+            "levelname",
+            "levelno",
+            "lineno",
+            "module",
+            "msecs",
+            "pathname",
+            "process",
+            "processName",
+            "thread",
+            "threadName",
+            "exc_info",
+            "exc_text",
+            "stack_info",
+            "message",
+            "relativeCreated",
+            "taskName",
+        }
+    )
+
+    def format(self, record: logging.LogRecord) -> str:
+        base = f"[{record.levelname}] {record.getMessage()} ({record.pathname}:{record.lineno})"
+
+        # Collect extra fields (anything not in standard LogRecord attributes)
+        extras = {
+            k: v
+            for k, v in record.__dict__.items()
+            if k not in self._STANDARD_ATTRS and not k.startswith("_")
+        }
+
+        if extras:
+            extra_str = " ".join(f"{k}={v!r}" for k, v in extras.items())
+            base = f"{base} | {extra_str}"
+
+        # Include exception info if present
+        if record.exc_info:
+            base = f"{base}\n{self.formatException(record.exc_info)}"
+
+        # Include stack_info if requested (e.g., logger.info("msg", stack_info=True))
+        if record.stack_info:
+            base = f"{base}\n{self.formatStack(record.stack_info)}"
+
+        return base

neutronium-0.1.0/neutronium/telemetry/__init__.py

@@ -0,0 +1,19 @@
+from .context import (
+    clear_request_context,
+    client_ip_var,
+    enterprise_id_var,
+    request_id_var,
+    set_request_context,
+    user_id_var,
+)
+from .facts import RequestFacts
+
+__all__ = [
+    "request_id_var",
+    "user_id_var",
+    "client_ip_var",
+    "enterprise_id_var",
+    "set_request_context",
+    "clear_request_context",
+    "RequestFacts",
+]

neutronium-0.1.0/neutronium/telemetry/context.py

@@ -0,0 +1,32 @@
+from contextvars import ContextVar
+
+request_id_var: ContextVar[str | None] = ContextVar("request_id", default=None)
+user_id_var: ContextVar[str | None] = ContextVar("user_id", default=None)
+client_ip_var: ContextVar[str | None] = ContextVar("client_ip", default=None)
+enterprise_id_var: ContextVar[str | None] = ContextVar("enterprise_id", default=None)
+
+
+def set_request_context(
+    *,
+    request_id: str | None = None,
+    user_id: str | None = None,
+    client_ip: str | None = None,
+    enterprise_id: str | None = None,
+) -> None:
+    """Set request context variables for logging."""
+    if request_id is not None:
+        request_id_var.set(str(request_id))
+    if user_id is not None:
+        user_id_var.set(str(user_id))
+    if client_ip is not None:
+        client_ip_var.set(str(client_ip))
+    if enterprise_id is not None:
+        enterprise_id_var.set(str(enterprise_id))
+
+
+def clear_request_context() -> None:
+    """Clear all request context variables."""
+    request_id_var.set(None)
+    user_id_var.set(None)
+    client_ip_var.set(None)
+    enterprise_id_var.set(None)

neutronium-0.1.0/neutronium/telemetry/facts.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RequestFacts:
+    """
+    Immutable container for request telemetry data.
+    Collected by RequestTelemetryMiddleware and passed to all configured sinks.
+    """
+
+    # Request identification
+    request_id: str | None = None
+
+    # Enterprise context (from X-ENTERPRISE-ID header)
+    enterprise_id: str | None = None
+
+    # User context
+    user_id: int | None = None
+    user_is_authenticated: bool = False
+    user_is_staff: bool = False
+
+    # HTTP request info
+    method: str = ""
+    host: str = ""
+    path: str = ""
+    route: str | None = None
+    view_name: str | None = None
+
+    # Response info
+    status_code: int | None = None
+
+    # Timing
+    duration_ms: int | None = None
+
+    # Client info
+    client_ip: str | None = None
+    user_agent: str = ""

neutronium-0.1.0/neutronium/telemetry/sinks/__init__.py

@@ -0,0 +1,4 @@
+from .access_log import AccessLogSink
+from .base import TelemetrySink
+
+__all__ = ["TelemetrySink", "AccessLogSink"]

neutronium-0.1.0/neutronium/telemetry/sinks/access_log.py

@@ -0,0 +1,40 @@
+import logging
+
+from neutronium.telemetry.facts import RequestFacts
+
+audit_logger = logging.getLogger("app.audit.request")
+
+
+class AccessLogSink:
+    """
+    Sink that logs authenticated HTTP requests to the audit logger.
+
+    Replicates the behavior of the legacy AccessLogMiddleware:
+    - Only logs authenticated requests
+    - Uses the same log message and extra fields
+    - Writes to 'app.audit.request' logger
+    """
+
+    def emit(self, facts: RequestFacts) -> None:
+        """
+        Log authenticated request to the audit logger.
+
+        Only logs if the request was from an authenticated user,
+        matching the behavior of the original AccessLogMiddleware.
+        """
+        if not facts.user_is_authenticated:
+            return
+
+        audit_logger.info(
+            "Authenticated HTTP request",
+            extra={
+                "http.method": facts.method,
+                "http.path": facts.path,
+                "http.route": facts.route,
+                "http.status_code": facts.status_code,
+                "http.user_agent": facts.user_agent[:512] if facts.user_agent else "",
+                "duration_ms": facts.duration_ms,
+                "user.is_privileged": facts.user_is_staff,
+                "django.view": facts.view_name,
+            },
+        )

neutronium-0.1.0/neutronium/telemetry/sinks/base.py

@@ -0,0 +1,23 @@
+from typing import Protocol
+
+from neutronium.telemetry.facts import RequestFacts
+
+
+class TelemetrySink(Protocol):
+    """
+    Protocol defining the interface for request telemetry sinks.
+
+    Sinks receive RequestFacts after each request and can process them
+    in various ways (logging, analytics, metrics, etc.).
+
+    Each sink should be independent and not know about other sinks.
+    """
+
+    def emit(self, facts: RequestFacts) -> None:
+        """
+        Process the request telemetry data.
+
+        Args:
+            facts: Immutable container with all request telemetry data.
+        """
+        ...

neutronium-0.1.0/neutronium/threads/thread_simple.py

@@ -0,0 +1,72 @@
+import threading
+
+
+class SimpleThread(threading.Thread):
+    result = None
+
+    def __init__(self, func, run_sync=False, *args, **kwargs):
+        super().__init__()
+        self.kwargs = kwargs
+        # for kwarg in kwargs.items():
+        #     setattr(self, kwarg[0], kwarg[1])
+        self.func = func
+        self.run_sync = run_sync
+        self.exception = None
+
+    def start(self):
+        # Allow for override to run synchronously...
+        if self.run_sync:
+            self.run()
+        else:
+            super().start()
+
+    def run(self):
+        try:
+            self.result = self.func(**self.kwargs)
+        except Exception as e:
+            self.exception = e
+
+    def get_result(self):
+        if not self.run_sync:
+            self.join()
+        return self.result
+
+
+class SimpleThreadManager:
+
+    def __init__(self, pass_through_exceptions=False):
+        self.threads = []
+        self.results_list = []
+        self.results_total = 0
+        self.pass_through_exceptions = pass_through_exceptions
+
+    def start_thread(self, simple_thread):
+        """
+        Add thread to the threads list and start it running.
+        :param simple_thread:
+        :type: SimpleThread
+        :return:
+        """
+        simple_thread.start()
+        self.threads.append(simple_thread)
+
+    def wait_return_results_as_list(self):
+        for thread in self.threads:
+            result = thread.get_result()
+            if thread.exception and self.pass_through_exceptions:
+                raise thread.exception
+            if result is not None:
+                if isinstance(result, (list, set)):
+                    self.results_list += result
+                else:
+                    self.results_list.append(result)
+        self.threads = []
+        return self.results_list
+
+    def wait_return_results_as_total(self):
+        for thread in self.threads:
+            result = thread.get_result()
+            if result:
+                self.results_total += result
+        self.threads = []
+        return self.results_total

neutronium-0.1.0/neutronium/utils/aws.py

@@ -0,0 +1,60 @@
+def get_instance_metadata():
+    import os
+    from dataclasses import dataclass
+
+    @dataclass
+    class InstanceMetadata:
+        private_ipv4: str | None = None
+        region: str | None = None
+
+    env_region = os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION")
+
+    ecs_metadata_uri = os.environ.get("ECS_CONTAINER_METADATA_URI_V4")
+    if ecs_metadata_uri:
+        try:
+            import requests
+
+            r = requests.get(f"{ecs_metadata_uri}/task", timeout=2)
+            r.raise_for_status()
+            task = r.json()
+
+            private_ip = None
+            for c in task.get("Containers", []):
+                for n in c.get("Networks", []):
+                    ipv4s = n.get("IPv4Addresses") or []
+                    if ipv4s:
+                        private_ip = ipv4s[0]
+                        break
+                if private_ip:
+                    break
+
+            region = env_region
+            if not region:
+                task_arn = task.get("TaskARN") or ""
+                parts = task_arn.split(":")
+                if len(parts) > 2:
+                    region = parts[2]  # arn:aws:ecs:REGION:...
+
+            return InstanceMetadata(private_ipv4=private_ip, region=region)
+        except Exception:
+            pass
+
+    try:
+        from ec2_metadata import ec2_metadata
+
+        rel = os.environ.get("AWS_CONTAINER_CREDENTIALS_RELATIVE_URI")
+        if rel:
+            ec2_metadata.SERVICE_URL = f"169.254.170.2{rel}"
+            ec2_metadata.DYNAMIC_URL = ec2_metadata.SERVICE_URL + "dynamic/"
+            ec2_metadata.METADATA_URL = ec2_metadata.SERVICE_URL + "meta-data/"
+            ec2_metadata.USERDATA_URL = ec2_metadata.SERVICE_URL + "user-data/"
+
+        region = getattr(ec2_metadata, "region", None) or env_region
+        return InstanceMetadata(
+            private_ipv4=getattr(ec2_metadata, "private_ipv4", None),
+            region=region,
+        )
+    except Exception:
+        pass
+
+    return InstanceMetadata(region=env_region)

neutronium-0.1.0/neutronium/utils/email.py

@@ -0,0 +1,23 @@
+def get_canonical_email(email=None):
+    """
+    :param email:
+    :return: Returns the lowercase canonical email without `+` or `.` characters.
+    """
+
+    if not email:
+        return None
+
+    # Convert email to lowercase
+    email = email.lower()
+
+    delimited_email = email.split('@')
+    domain = delimited_email[-1]
+
+    # Get the significand of an email address (removing any extra @'s)
+    significand = ''.join(delimited_email[0:-1])
+
+    # Strip substring from first `+` to the `@`
+    if '+' in significand:
+        significand = significand[0:significand.find('+')]
+
+    return '@'.join([significand, domain])