python-otelio 0.0.1__py3-none-any.whl

otelio/__init__.py

@@ -0,0 +1,32 @@
+"""
+Otelio — a small OpenTelemetry + Loguru toolkit for Python services.
+
+Import surface kept intentionally small: bootstrap once with ``init_otelio``,
+then use ``otel_span`` / helpers anywhere in the codebase.
+"""
+
+from .bootstrap import init_otelio
+from .helpers import (
+    otel_add_event,
+    otel_context_from_headers,
+    otel_get_all_baggage,
+    otel_get_baggage,
+    otel_inject_headers,
+    otel_set_attributes,
+    otel_set_baggage,
+)
+from .tracing import otel_current_span, otel_get_tracer, otel_span
+
+__all__ = [
+    "init_otelio",
+    "otel_add_event",
+    "otel_context_from_headers",
+    "otel_current_span",
+    "otel_get_all_baggage",
+    "otel_get_baggage",
+    "otel_get_tracer",
+    "otel_inject_headers",
+    "otel_set_attributes",
+    "otel_set_baggage",
+    "otel_span",
+]

otelio/bootstrap.py

@@ -0,0 +1,65 @@
+"""One-call wiring: providers, processors, the Loguru bridge, and shutdown."""
+
+import atexit
+from collections.abc import Mapping
+from typing import Any
+
+from loguru import logger
+from opentelemetry import trace
+from opentelemetry._logs import set_logger_provider
+from opentelemetry.sdk._logs import LoggerProvider
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from .config import Settings, load_settings
+from .exporters import build_log_exporter, build_span_exporter
+from .logging import setup_loguru
+
+
+def init_otelio(
+    service_name: str,
+    service_version: str,
+    environment: str | None = None,
+    resource_attributes: Mapping[str, Any] | None = None,
+) -> Settings:
+    """
+    Initialise tracing + logging once at process start; returns the resolved settings.
+
+    Pass ``resource_attributes`` to stamp extra resource-level attributes (e.g.
+    ``service.namespace``, ``service.instance.id``, ``cloud.region``) onto every span
+    and log this process emits. The canonical ``service.name`` / ``service.version`` /
+    ``deployment.environment`` keys always win, so they cannot be clobbered here.
+
+    Registers an :mod:`atexit` hook that flushes Loguru and shuts the providers down
+    so buffered spans/logs are exported on a clean exit.
+    """
+    s = load_settings(service_name, service_version, environment)
+
+    resource = Resource.create(
+        {
+            **(resource_attributes or {}),
+            "service.name": s.service_name,
+            "service.version": s.service_version,
+            "deployment.environment": s.environment,
+        }
+    )
+
+    tracer_provider = TracerProvider(resource=resource)
+    tracer_provider.add_span_processor(BatchSpanProcessor(build_span_exporter(s)))
+    trace.set_tracer_provider(tracer_provider)
+
+    logger_provider = LoggerProvider(resource=resource)
+    logger_provider.add_log_record_processor(BatchLogRecordProcessor(build_log_exporter(s)))
+    set_logger_provider(logger_provider)
+
+    setup_loguru(logger_provider)
+
+    def _shutdown() -> None:
+        logger.complete()
+        tracer_provider.shutdown()
+        logger_provider.shutdown()
+
+    atexit.register(_shutdown)
+    return s

otelio/config.py

@@ -0,0 +1,32 @@
+"""Settings for otelio, resolved from environment variables with sane defaults."""
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Resolved telemetry configuration for one service."""
+
+    service_name: str
+    service_version: str
+    environment: str
+    target: str  # "otlp" | "azure"
+    otlp_endpoint: str
+    azure_conn_str: str | None
+
+
+def load_settings(
+    service_name: str,
+    service_version: str,
+    environment: str | None = None,
+) -> Settings:
+    """Build :class:`Settings`, letting environment variables override the args."""
+    return Settings(
+        service_name=os.getenv("OTEL_SERVICE_NAME", service_name),
+        service_version=service_version,
+        environment=environment or os.getenv("DEPLOYMENT_ENVIRONMENT", "local"),
+        target=os.getenv("OTELIO_TARGET", "otlp").lower(),  # local -> otlp/signoz
+        otlp_endpoint=os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317"),
+        azure_conn_str=os.getenv("APPLICATIONINSIGHTS_CONNECTION_STRING"),
+    )

otelio/exporters.py

@@ -0,0 +1,41 @@
+"""
+Span and log exporter factories.
+
+The backend-specific SDKs are imported lazily so a project only needs the deps
+for the target it actually uses (``otlp`` for SigNoz, ``azure`` for App Insights).
+"""
+
+from opentelemetry.sdk._logs.export import LogRecordExporter
+from opentelemetry.sdk.trace.export import SpanExporter
+
+from .config import Settings
+
+
+def build_span_exporter(s: Settings) -> SpanExporter:
+    """Return the span exporter for the configured target."""
+    if s.target == "azure":
+        from azure.monitor.opentelemetry.exporter import (  # noqa: PLC0415 (optional dep)
+            AzureMonitorTraceExporter,
+        )
+
+        return AzureMonitorTraceExporter(connection_string=s.azure_conn_str)
+    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (  # noqa: PLC0415
+        OTLPSpanExporter,
+    )
+
+    return OTLPSpanExporter(endpoint=s.otlp_endpoint)
+
+
+def build_log_exporter(s: Settings) -> LogRecordExporter:
+    """Return the log-record exporter for the configured target."""
+    if s.target == "azure":
+        from azure.monitor.opentelemetry.exporter import (  # noqa: PLC0415 (optional dep)
+            AzureMonitorLogExporter,
+        )
+
+        return AzureMonitorLogExporter(connection_string=s.azure_conn_str)
+    from opentelemetry.exporter.otlp.proto.grpc._log_exporter import (  # noqa: PLC0415
+        OTLPLogExporter,
+    )
+
+    return OTLPLogExporter(endpoint=s.otlp_endpoint)

otelio/helpers.py

@@ -0,0 +1,84 @@
+"""Context propagation and attribute/event helpers for working with spans."""
+
+from collections.abc import Mapping
+from typing import Any
+
+from opentelemetry import baggage
+from opentelemetry.context import Context, attach, get_current
+from opentelemetry.propagate import extract, inject
+from opentelemetry.trace import Span
+
+from .tracing import otel_current_span
+
+# ---- propagation (W3C traceparent + baggage) ----
+
+
+def otel_inject_headers(headers: dict[str, str] | None = None) -> dict[str, str]:
+    """Inject the current trace context into ``headers`` (adds ``traceparent``)."""
+    headers = headers if headers is not None else {}
+    inject(headers)
+    return headers
+
+
+def otel_context_from_headers(headers: Mapping[str, str]) -> Context:
+    """Extract a trace context from inbound ``headers``; pass to ``span(context=...)``."""
+    return extract(headers)
+
+
+# ---- baggage (cross-service key/values, ride the `baggage` header) ----
+
+
+def otel_set_baggage(items: Mapping[str, str]) -> object:
+    """
+    Put key/value pairs into baggage so they propagate to every downstream hop.
+
+    Mirrors :func:`otel_set_attributes` — pass a mapping object. Unlike span
+    attributes (local to one service), baggage rides the W3C ``baggage`` header
+    through every downstream hop, so it is ideal for cross-cutting IDs such as
+    ``tenant.id`` / ``request.id`` / ``user.id``.
+
+    Baggage is sent in plaintext to every downstream service — **never put secrets
+    or PII in it**, and keep entries small (it is header weight on every call).
+
+    Baggage does not become span attributes automatically; copy what you want onto
+    a span with :func:`otel_set_attributes` (e.g. via :func:`otel_get_all_baggage`).
+
+    Attaches the updated context as current and returns a detach token. In a
+    request-scoped flow (e.g. FastAPI middleware) keep the token and call
+    ``opentelemetry.context.detach(token)`` when the request ends so baggage does
+    not leak into the next request handled on the same context.
+    """
+    ctx = get_current()
+    for key, value in items.items():
+        ctx = baggage.set_baggage(key, value, context=ctx)
+    return attach(ctx)
+
+
+def otel_get_baggage(key: str) -> str | None:
+    """Return a single baggage value from the current context, or ``None``."""
+    value = baggage.get_baggage(key)
+    return None if value is None else str(value)
+
+
+def otel_get_all_baggage() -> dict[str, str]:
+    """Return all baggage entries in the current context as a plain dict."""
+    return {key: str(value) for key, value in baggage.get_all().items()}
+
+
+# ---- attributes / events ----
+
+
+def otel_set_attributes(attributes: Mapping[str, Any], span: Span | None = None) -> None:
+    """Set attributes on the current span (or ``span``) when it is recording."""
+    span = span or otel_current_span()
+    if span and span.is_recording():
+        span.set_attributes(dict(attributes))
+
+
+def otel_add_event(
+    name: str, attributes: Mapping[str, Any] | None = None, span: Span | None = None
+) -> None:
+    """Add a timestamped event to the current span (or ``span``) when recording."""
+    span = span or otel_current_span()
+    if span and span.is_recording():
+        span.add_event(name, attributes=dict(attributes or {}))

otelio/logging.py

@@ -0,0 +1,97 @@
+"""
+Bridge Loguru into the OpenTelemetry logs pipeline.
+
+Loguru stays the single logging API for the app; every record is mirrored to an
+OTel ``LoggingHandler`` (so logs are exported and correlated to the active span)
+while a patcher stamps ``trace_id`` / ``span_id`` onto the console line.
+"""
+
+import logging
+import sys
+from typing import TYPE_CHECKING
+
+from loguru import logger
+from opentelemetry import trace
+from opentelemetry.context import attach, detach
+from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+from opentelemetry.trace import (
+    NonRecordingSpan,
+    SpanContext,
+    TraceFlags,
+    set_span_in_context,
+)
+
+if TYPE_CHECKING:
+    from loguru import Message
+
+_LOGURU_TO_STD = {
+    "TRACE": 5,
+    "DEBUG": 10,
+    "INFO": 20,
+    "SUCCESS": 25,
+    "WARNING": 30,
+    "ERROR": 40,
+    "CRITICAL": 50,
+}
+
+
+def _trace_patcher(record: dict) -> None:
+    ctx = trace.get_current_span().get_span_context()
+    if ctx and ctx.trace_id:
+        record["extra"]["trace_id"] = format(ctx.trace_id, "032x")
+        record["extra"]["span_id"] = format(ctx.span_id, "016x")
+    else:
+        record["extra"]["trace_id"] = "-"
+        record["extra"]["span_id"] = "-"
+
+
+def setup_loguru(
+    logger_provider: LoggerProvider,
+    console_level: str = "INFO",
+    export_level: str = "DEBUG",
+) -> None:
+    """Reconfigure Loguru with a console sink and an OTel-export sink."""
+    otel_handler = LoggingHandler(level=logging.NOTSET, logger_provider=logger_provider)
+
+    def _otel_sink(message: "Message") -> None:
+        r = message.record
+        std = logging.LogRecord(
+            name=r["name"] or "otelio",
+            level=_LOGURU_TO_STD.get(r["level"].name, 20),
+            pathname=r["file"].path,
+            lineno=r["line"],
+            msg=r["message"],
+            args=(),
+            exc_info=r["exception"],  # loguru's (type, value, tb) namedtuple
+            func=r["function"],
+        )
+        # enqueue=True runs this on Loguru's writer thread, where the OTel
+        # contextvar is empty — so re-attach the span context the patcher
+        # captured (on the originating thread) before emitting, otherwise the
+        # exported record loses its trace_id/span_id.
+        tid = r["extra"].get("trace_id")
+        sid = r["extra"].get("span_id")
+        token = None
+        if tid and tid != "-":
+            span_ctx = SpanContext(
+                trace_id=int(tid, 16),
+                span_id=int(sid, 16),
+                is_remote=False,
+                trace_flags=TraceFlags(TraceFlags.SAMPLED),
+            )
+            token = attach(set_span_in_context(NonRecordingSpan(span_ctx)))
+        try:
+            otel_handler.emit(std)  # backend; span context attached here
+        finally:
+            if token is not None:
+                detach(token)
+
+    logger.remove()  # drop loguru's default stderr sink
+    logger.configure(patcher=_trace_patcher)
+    logger.add(
+        sys.stderr,
+        level=console_level,
+        format="<green>{time:HH:mm:ss.SSS}</green> | {level: <8} | "
+        "trace={extra[trace_id]} | {name}:{line} - {message}",
+    )
+    logger.add(_otel_sink, level=export_level, enqueue=True)

otelio/tracing.py

@@ -0,0 +1,46 @@
+"""Span creation: a ``span()`` context manager plus low-level span access."""
+
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from typing import Any
+
+from opentelemetry import trace
+from opentelemetry.context import Context
+from opentelemetry.trace import Span, SpanKind, Status, StatusCode, Tracer
+
+_TRACER_NAME = "otelio"
+
+
+def otel_get_tracer() -> Tracer:
+    """Return the shared otelio tracer."""
+    return trace.get_tracer(_TRACER_NAME)
+
+
+def otel_current_span() -> Span:
+    """Return the span active in the current context (a no-op span if none)."""
+    return trace.get_current_span()
+
+
+@contextmanager
+def otel_span(
+    name: str,
+    attributes: Mapping[str, Any] | None = None,
+    kind: SpanKind = SpanKind.INTERNAL,
+    context: Context | None = None,
+) -> Iterator[Span]:
+    """
+    Start ``name`` as the current span; records and re-raises any exception.
+
+    Pass ``context`` (from :func:`otel_context_from_headers`) to continue an
+    inbound distributed trace.
+    """
+    tracer = otel_get_tracer()
+    with tracer.start_as_current_span(name, context=context, kind=kind) as s:
+        if attributes:
+            s.set_attributes(dict(attributes))
+        try:
+            yield s
+        except Exception as e:
+            s.record_exception(e)
+            s.set_status(Status(StatusCode.ERROR, str(e)))
+            raise

python_otelio-0.0.1.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: python-otelio
+Version: 0.0.1
+Summary: Otelio: OpenTelemetry + Loguru toolkit for Python services
+Project-URL: Homepage, https://github.com/code4mk/python-otelio
+Project-URL: Source, https://github.com/code4mk/python-otelio
+Project-URL: Changelog, https://github.com/code4mk/python-otelio/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/code4mk/python-otelio
+Project-URL: Bug Tracker, https://github.com/code4mk/python-otelio/issues
+Author-email: Mostafa Kamal <hiremostafa@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: code4mk,logging,loguru,observability,opentelemetry,otel,python,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: opentelemetry-api==1.40.*
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc==1.40.*
+Requires-Dist: opentelemetry-sdk==1.40.*
+Provides-Extra: azure
+Requires-Dist: azure-monitor-opentelemetry-exporter>=1.0.0b53; extra == 'azure'
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.0.270; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# otelio
+
+> Python OpenTelemetry + Loguru toolkit
+
+A small, batteries-included **OpenTelemetry + [Loguru](https://github.com/Delgan/loguru)**
+toolkit for Python services. Call `init_otelio(...)` once at startup and you get **traces**
+and **logs** that are automatically correlated by `trace_id` / `span_id`, exported over
+**OTLP/gRPC** (SigNoz, Grafana, Jaeger, any OTLP collector) or to **Azure Application
+Insights** — switchable with a single environment variable, no code changes.
+
+[![PyPI](https://img.shields.io/pypi/v/python-otelio.svg)](https://pypi.org/project/python-otelio/)
+[![Python](https://img.shields.io/pypi/pyversions/python-otelio.svg)](https://pypi.org/project/python-otelio/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
+
+## Features
+
+- **One call to wire everything** — `init_otelio(...)` sets up the tracer + logger
+  providers, the Loguru bridge, and a clean-shutdown flush hook.
+- **Logs correlate to spans automatically** — keep using Loguru; every record is stamped
+  with the active `trace_id` / `span_id` and exported.
+- **Backend-agnostic** — OTLP/gRPC or Azure App Insights via the `OTELIO_TARGET` env var.
+  Exporter SDKs are imported lazily, so you only install what you use.
+- **Cross-service tracing built in** — W3C `traceparent` + `baggage` propagation helpers so
+  one request shows up as a single connected trace across service boundaries.
+- **Tiny surface** — eleven well-documented functions, nothing to configure in code.
+
+## Install
+
+```bash
+pip install python-otelio                # core + OTLP/gRPC exporter
+pip install "python-otelio[azure]"       # also the Azure Application Insights exporter
+```
+
+Requires Python 3.10+. The distribution is named **`python-otelio`** on PyPI but imports
+as **`otelio`** (`from otelio import ...`).
+
+## Quick start
+
+```python
+from otelio import init_otelio, otel_span, otel_set_attributes
+from loguru import logger
+
+# 1. Bootstrap once, at process start (before anything emits telemetry).
+init_otelio(service_name="my-service", service_version="1.0.0")
+
+# 2. Log with Loguru as usual — records are stamped with the active span.
+logger.info("service started")
+
+# 3. Wrap units of work in spans; exceptions are recorded and re-raised.
+with otel_span("handle_request", attributes={"route": "/search"}):
+    otel_set_attributes({"result.count": 12})
+```
+
+## Configuration
+
+All configuration is via environment variables.
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `OTELIO_TARGET` | `otlp` | `otlp` (any OTLP/gRPC collector) or `azure` (App Insights). |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4317` | OTLP/gRPC collector endpoint (target `otlp`). |
+| `APPLICATIONINSIGHTS_CONNECTION_STRING` | — | App Insights connection string (target `azure`). |
+| `OTEL_SERVICE_NAME` | the `service_name` arg | Overrides the service name. |
+| `DEPLOYMENT_ENVIRONMENT` | `local` | Set as the `deployment.environment` resource attribute. |
+
+```bash
+# OTLP collector (SigNoz, Grafana, Jaeger, ...)
+export OTELIO_TARGET=otlp
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+
+# Azure Application Insights
+export OTELIO_TARGET=azure
+export APPLICATIONINSIGHTS_CONNECTION_STRING="InstrumentationKey=...;IngestionEndpoint=..."
+export DEPLOYMENT_ENVIRONMENT=production
+```
+
+## Public API (`from otelio import ...`)
+
+| Symbol | Purpose |
+| --- | --- |
+| `init_otelio(service_name, service_version, environment=None, resource_attributes=None)` | Bootstrap tracing + logging once at startup. `resource_attributes` adds extra resource-level keys to every span + log. Returns the resolved `Settings`. |
+| `otel_span(name, attributes=None, kind=SpanKind.INTERNAL, context=None)` | Context manager that starts a span, records exceptions, and re-raises. |
+| `otel_current_span()` | The span active in the current context. |
+| `otel_get_tracer()` | The shared `otelio` tracer. |
+| `otel_inject_headers(headers=None)` | Inject the current trace context + baggage into an outbound header dict. |
+| `otel_context_from_headers(headers)` | Extract a trace context (+ baggage) from inbound headers; pass to `otel_span(context=...)`. |
+| `otel_set_baggage(items)` | Put a mapping of key/values into baggage so they propagate downstream. Returns a detach token. |
+| `otel_get_baggage(key)` | Read one baggage value from the current context (or `None`). |
+| `otel_get_all_baggage()` | Read all baggage entries as a plain `dict`. |
+| `otel_set_attributes(attributes, span=None)` | Set attributes on the current span, or `span` if given (guards `is_recording()`). |
+| `otel_add_event(name, attributes=None, span=None)` | Add a timestamped event to the current span, or `span` if given. |
+
+## Context propagation across services
+
+`otelio` carries the W3C `traceparent` + `baggage` headers automatically, so one request
+shows up as a single connected trace across service boundaries:
+
+```python
+import httpx
+from opentelemetry.trace import SpanKind
+from otelio import otel_inject_headers, otel_context_from_headers, otel_span
+
+# Outbound — inject context into the request headers
+with otel_span("call_downstream", kind=SpanKind.CLIENT):
+    headers = otel_inject_headers({"Authorization": token})
+    resp = httpx.post(url, headers=headers, json=payload)
+
+# Inbound — continue the caller's trace
+ctx = otel_context_from_headers(request.headers)
+with otel_span("serve_request", kind=SpanKind.SERVER, context=ctx):
+    ...
+```
+
+## Documentation
+
+See the full [usage guide](https://github.com/code4mk/python-otelio/blob/main/docs/usage.md)
+for bootstrapping, spans, correlated logging, context propagation, baggage, and a complete
+FastAPI example.
+
+## License
+
+[MIT](LICENSE) © code4mk

python_otelio-0.0.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+otelio/__init__.py,sha256=kNm1onGialyL4bf_gkhBGhErtnHRQGRfvBYClNkRsv8,800
+otelio/bootstrap.py,sha256=PZbP9cI9xFcthASoBCDqSTi1Z3JUFeGg-fFjXayZhvU,2344
+otelio/config.py,sha256=OxcKId-8CaONpc5HgrwzJjxWhe_2WPhX4GfsT9teWPc,1057
+otelio/exporters.py,sha256=JWheVBFfhhjJWWKAlotzG4MSuSlLECR6chV421g3cuw,1435
+otelio/helpers.py,sha256=fNciSTwdcZMNA8G1ZPVbV-ncuoDnE3KkI4qKmuYOmG8,3248
+otelio/logging.py,sha256=-aNmlt0cJLVYD9Z5e8XKim42MjdWiRYudKhdzQdAOhQ,3184
+otelio/tracing.py,sha256=bMwUvByAYdUyOBUlF9Z5LKIHjx3j_cinPQz_QP2JDDE,1382
+python_otelio-0.0.1.dist-info/METADATA,sha256=TsaSfRUFbAptWoHu0y5bnpRIEvt8D-p3Pih1sfd-pRc,7414
+python_otelio-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+python_otelio-0.0.1.dist-info/licenses/LICENSE,sha256=VJxb9K5BrmXV5gu6vuCc2NmzPQNq-PLJW32BjUD26pE,1064
+python_otelio-0.0.1.dist-info/RECORD,,

python_otelio-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

python_otelio-0.0.1.dist-info/licenses/LICENSE

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