microsoft-agents-activity 1.10.0.dev0__tar.gz → 1.10.0.dev2__tar.gz

{microsoft_agents_activity-1.10.0.dev0 → microsoft_agents_activity-1.10.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microsoft-agents-activity
-Version: 1.10.0.dev0
+Version: 1.10.0.dev2
 Summary: A protocol library for Microsoft Agents
 Author: Microsoft Corporation
 License-Expression: MIT

microsoft_agents_activity-1.10.0.dev2/VERSION.txt

@@ -0,0 +1 @@
+1.10.0.dev2

microsoft_agents_activity-1.10.0.dev2/microsoft_agents/activity/config/__init__.py

@@ -0,0 +1,39 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from ._load_configuration import load_configuration_from_env
+from .configuration import Configuration, _Configurable
+from ._configuration_protocol import _ConfigurationProtocol, _DictConfigurable
+from ._resolve import _resolve
+from ._utils import (
+    _MissingType,
+    _MISSING,
+    _get,
+    _is_missing,
+    _path as path,
+    _xpath as xpath,
+    _set,
+    _try_set,
+)
+from ._coercion import coerce_bool, coerce_int, coerce_float, _get_str
+
+__all__ = [
+    "load_configuration_from_env",
+    "Configuration",
+    "_ConfigurationProtocol",
+    "_MissingType",
+    "_MISSING",
+    "_is_missing",
+    "xpath",
+    "path",
+    "_get",
+    "_set",
+    "_try_set",
+    "_resolve",
+    "_Configurable",
+    "_DictConfigurable",
+    "coerce_bool",
+    "coerce_int",
+    "coerce_float",
+    "_get_str",
+]

microsoft_agents_activity-1.10.0.dev2/microsoft_agents/activity/config/_coercion.py

@@ -0,0 +1,281 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+"""Coercion helpers for values loaded from environment configuration.
+
+:func:`load_configuration_from_env` keeps every value as the raw string (or a
+nested ``dict``) read from the environment. Consumers that expect a bool, int or
+float must coerce explicitly: a naive ``bool("false")`` is ``True`` and would
+silently invert a flag, and ``int("5") + 1`` style math fails on values that may
+legitimately arrive as strings. These helpers centralize that coercion so every
+config consumer parses env values the same, fail-safe way.
+"""
+
+from __future__ import annotations
+
+from typing import (
+    Any,
+    Mapping,
+    overload,
+)
+
+from ._utils import (
+    _MISSING,
+    _MissingType,
+    _get,
+    _is_missing,
+)
+
+_TRUTHY = ("1", "true")
+_FALSY = ("0", "false")
+
+
+@overload
+def _handle_bool(
+    value: Any, default: None = None, name: str = "value"
+) -> bool | None: ...
+@overload
+def _handle_bool(
+    value: Any, default: bool | _MissingType = _MISSING, name: str = "value"
+) -> bool: ...
+def _handle_bool(
+    value: Any, default: bool | None | _MissingType = None, name: str = "value"
+) -> bool | None:
+    """Coerce a config value (possibly an env string) to a bool.
+
+    Environment variables always arrive as strings, so ``bool("false")`` would
+    be ``True``. Recognized truthy spellings are ``1/true`` and falsy spellings
+    are ``0/false`` (case-insensitive).
+
+    An empty/whitespace-only string or ``None`` is treated as *unset* (not as an
+    explicit ``false``). Unset values return the default, or raise if no default
+    was supplied. Unrecognized nonempty values always raise ``ValueError``.
+    Errors identify the setting without including its input value.
+    """
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return bool(value)
+    if value is not None and not _is_missing(value):
+        text = str(value).strip().lower()
+        if text in _TRUTHY:
+            return True
+        if text in _FALSY:
+            return False
+        if text:
+            raise ValueError(f"Invalid boolean for {name}")
+    if _is_missing(default):
+        raise ValueError(f"Missing boolean for {name}")
+    return default
+
+
+def coerce_bool(value: Any, default: bool | None = None, name: str = "value") -> bool:
+    """Coerce a config value (possibly an env string) to a bool.
+
+    Environment variables always arrive as strings, so ``bool("false")`` would
+    be ``True``. Recognized truthy spellings are ``1/true`` and falsy spellings
+    are ``0/false`` (case-insensitive).
+
+    An empty/whitespace-only string or ``None`` is treated as *unset* (not as an
+    explicit ``false``). Unset and unrecognized values return the default, or
+    raise ``ValueError`` if no non-None default was supplied.
+    Errors identify the setting without including its input value.
+    """
+    new_default = default if default is not None else _MISSING
+    try:
+        return _handle_bool(value, new_default, name)
+    except ValueError:
+        if default is not None:
+            return default
+        raise
+
+
+@overload
+def _handle_int(
+    value: Any, default: int | _MissingType = _MISSING, name: str = "value"
+) -> int: ...
+@overload
+def _handle_int(
+    value: Any, default: None = None, name: str = "value"
+) -> int | None: ...
+def _handle_int(
+    value: Any, default: int | None | _MissingType = None, name: str = "value"
+) -> int | None:
+    """Coerce a config value (possibly an env string) to an int.
+
+    Empty/``None`` values fall back to ``default``. Bools are treated as unset
+    (a stray ``True``/``False`` is not a meaningful count). Numeric strings such
+    as ``"5"`` or ``"5.0"`` are accepted; anything else raises ``ValueError``
+    naming the offending setting.
+    """
+    if value is None or _is_missing(value):
+        if _is_missing(default):
+            raise ValueError(f"Missing integer for {name}")
+        return default
+    if isinstance(value, bool):
+        if _is_missing(default):
+            raise ValueError(f"Missing integer for {name}")
+        return default  # TODO -> should this raise?
+    if isinstance(value, int):
+        return value
+    text = str(value).strip()
+    if not text:
+        if _is_missing(default):
+            raise ValueError(f"Missing integer for {name}")
+        return default
+    try:
+        return int(text, 10)
+    except ValueError:
+        try:
+            return int(float(text))
+        except ValueError:
+            raise ValueError(f"Invalid integer for {name}") from None
+
+
+def coerce_int(value: Any, default: int | None = None, name: str = "value") -> int:
+    """Coerce a config value (possibly an env string) to an int.
+
+    Empty/``None`` values fall back to ``default``. Bools are treated as unset
+    (a stray ``True``/``False`` is not a meaningful count). Numeric strings such
+    as ``"5"`` or ``"5.0"`` are accepted; anything else raises ``ValueError``
+    naming the offending setting.
+    """
+    new_default = default if default is not None else _MISSING
+    return _handle_int(value, new_default, name)
+
+
+@overload
+def _handle_float(
+    value: Any, default: float | _MissingType, name: str = "value"
+) -> float: ...
+@overload
+def _handle_float(
+    value: Any, default: None = None, name: str = "value"
+) -> float | None: ...
+def _handle_float(
+    value: Any, default: float | None | _MissingType = None, name: str = "value"
+) -> float | None:
+    """Coerce a config value (possibly an env string) to a float.
+
+    Empty/``None`` values fall back to ``default``. Bools are treated as unset.
+    Anything that is not parseable as a float raises ``ValueError`` naming the
+    offending setting.
+    """
+    if value is None or _is_missing(value):
+        if _is_missing(default):
+            raise ValueError(f"Missing number for {name}")
+        return default
+    if isinstance(value, bool):
+        if _is_missing(default):
+            raise ValueError(f"Missing number for {name}")
+        return default  # TODO -> should this also raise?
+    if isinstance(value, (int, float)):
+        return float(value)
+    text = str(value).strip()
+    if not text:
+        if _is_missing(default):
+            raise ValueError(f"Missing number for {name}")
+        return default
+    try:
+        return float(text)
+    except ValueError:
+        raise ValueError(f"Invalid number for {name}") from None
+
+
+def coerce_float(
+    value: Any, default: float | None = None, name: str = "value"
+) -> float:
+    """Coerce a config value (possibly an env string) to a float.
+
+    Empty/``None`` values fall back to ``default``. Bools are treated as unset.
+    Anything that is not parseable as a float raises ``ValueError`` naming the
+    offending setting.
+    """
+    new_default = default if default is not None else _MISSING
+    return _handle_float(value, new_default, name)
+
+
+def _check_key_error(value: Any, default: Any, key: str) -> None:
+    if _is_missing(value) and _is_missing(default):
+        raise KeyError(key)
+
+
+@overload
+def _handle_str(
+    value: Any, default: None = None, name: str = "value"
+) -> str | None: ...
+@overload
+def _handle_str(
+    value: Any, default: str | _MissingType = _MISSING, name: str = "value"
+) -> str: ...
+def _handle_str(
+    value: Any, default: str | None | _MissingType = None, name: str = "value"
+) -> str | None:
+    if value is None or _is_missing(value):
+        if _is_missing(default):
+            raise ValueError(f"Missing string for {name}")
+        return default
+    if isinstance(value, str):
+        return value
+    return str(value)
+
+
+def _handle_str_list(
+    value: Any, default: list[str] | None = None, name: str = "value"
+) -> list[str]:
+    if not isinstance(value, list):
+        raise ValueError(f"{name} must be a list.")
+    values = [_handle_str(val) for val in value]
+    return [val for val in values if val is not None]
+
+
+@overload
+def _get_bool(mapping: Mapping, key: str, default: bool | _MissingType) -> bool: ...
+@overload
+def _get_bool(mapping: Mapping, key: str, default: None) -> bool | None: ...
+def _get_bool(
+    mapping: Mapping, key: str, default: bool | None | _MissingType = _MISSING
+) -> bool | None:
+    val = _get(mapping, key, default=_MISSING)
+    _check_key_error(val, default, key)
+    return _handle_bool(val, default, key)
+
+
+@overload
+def _get_int(mapping: Mapping, key: str, default: int | _MissingType) -> int: ...
+@overload
+def _get_int(mapping: Mapping, key: str, default: None) -> int | None: ...
+def _get_int(
+    mapping: Mapping, key: str, default: int | None | _MissingType = _MISSING
+) -> int | None:
+    val = _get(mapping, key, default=_MISSING)
+    _check_key_error(val, default, key)
+    return _handle_int(val, default, key)
+
+
+@overload
+def _get_float(mapping: Mapping, *key: str, default: float | _MissingType) -> float: ...
+@overload
+def _get_float(mapping: Mapping, *key: str, default: None) -> float | None: ...
+def _get_float(
+    mapping: Mapping, *key: str, default: float | None | _MissingType = _MISSING
+) -> float | None:
+    if not key:
+        raise ValueError("At least one key must be provided.")
+    val = _get(mapping, *key, default=_MISSING)
+    _check_key_error(val, default, key[0])
+    return _handle_float(val, default, key[0])
+
+
+@overload
+def _get_str(mapping: Mapping, *key: str, default: str | _MissingType) -> str: ...
+@overload
+def _get_str(mapping: Mapping, *key: str, default: None) -> str | None: ...
+def _get_str(
+    mapping: Mapping, *key: str, default: str | None | _MissingType = _MISSING
+) -> str | None:
+    if not key:
+        raise ValueError("At least one key must be provided.")
+    val = _get(mapping, *key, default=_MISSING)
+    _check_key_error(val, default, key[0])
+    return _handle_str(val, default, key[0])

microsoft_agents_activity-1.10.0.dev2/microsoft_agents/activity/config/_configuration_protocol.py

@@ -0,0 +1,35 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from abc import ABC, abstractmethod
+from typing import (
+    Mapping,
+    Protocol,
+    runtime_checkable,
+)
+from typing_extensions import Self
+
+
+@runtime_checkable
+class _ConfigurationProtocol(Protocol):
+
+    @classmethod
+    def from_mapping(cls, _mapping: Mapping) -> Self: ...
+
+
+class _DictConfigurableProtocol(_ConfigurationProtocol, Protocol):
+
+    def __init__(self, data: dict, *args, **kwargs) -> None: ...
+
+    @classmethod
+    def from_mapping(cls, mapping: Mapping) -> Self: ...
+
+
+class _DictConfigurable(ABC):
+
+    @abstractmethod
+    def __init__(self, data: dict, *args, **kwargs) -> None: ...
+
+    @classmethod
+    def from_mapping(cls, mapping: Mapping) -> Self:
+        return cls(dict(mapping))

microsoft_agents_activity-1.10.0.dev2/microsoft_agents/activity/config/_constants.py

@@ -0,0 +1,5 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+_PATH_SEPARATOR = "::"
+_PATH_ANY = "*"

{microsoft_agents_activity-1.10.0.dev0 → microsoft_agents_activity-1.10.0.dev2}/microsoft_agents/activity/config/_load_configuration.py

@@ -3,7 +3,7 @@
 
 from typing import Any, Mapping
 
-from ._configure_logging import _configure_logging
+from ._logging import _configure_logging
 
 
 def load_configuration_from_env(env_vars: Mapping[str, Any]) -> dict:

microsoft_agents_activity-1.10.0.dev2/microsoft_agents/activity/config/_logging/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from ._color_formatter import ColorFormatter
+from ._load import _configure_logging
+from ._logging_configuration import _LoggingConfiguration
+
+__all__ = [
+    "ColorFormatter",
+    "_configure_logging",
+    "_LoggingConfiguration",
+]

microsoft_agents_activity-1.10.0.dev2/microsoft_agents/activity/config/_logging/_color_formatter.py

@@ -0,0 +1,42 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+import logging
+
+
+class ColorFormatter(logging.Formatter):
+    """Logging formatter that can add ANSI color based on severity."""
+
+    MAGENTA = "\033[1;35m"
+    RED = "\033[1;31m"
+    YELLOW = "\033[1;33m"
+    GREEN = "\033[1;32m"
+    BLUE = "\033[1;34m"
+    RESET = "\033[0m"
+
+    FMT = (
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s (%(filename)s:%(lineno)d)"
+    )
+
+    def __init__(
+        self,
+        use_colors: bool = True,
+    ) -> None:
+        super().__init__(fmt=self.FMT)
+        self._plain_formatter = logging.Formatter(fmt=self.FMT)
+        if not use_colors:
+            self._formatters: dict[int, logging.Formatter] = {}
+            return
+        self._formatters = {
+            logging.CRITICAL: logging.Formatter(
+                f"{self.MAGENTA}{self.FMT}{self.RESET}"
+            ),
+            logging.ERROR: logging.Formatter(f"{self.RED}{self.FMT}{self.RESET}"),
+            logging.WARNING: logging.Formatter(f"{self.YELLOW}{self.FMT}{self.RESET}"),
+            logging.INFO: logging.Formatter(f"{self.GREEN}{self.FMT}{self.RESET}"),
+            logging.DEBUG: logging.Formatter(f"{self.BLUE}{self.FMT}{self.RESET}"),
+        }
+
+    def format(self, record: logging.LogRecord) -> str:
+        formatter = self._formatters.get(record.levelno)
+        return (formatter or self._plain_formatter).format(record)

microsoft_agents_activity-1.10.0.dev2/microsoft_agents/activity/config/_logging/_constants.py

@@ -0,0 +1,20 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+import logging
+
+# in Python 3.11, we can move to using
+# logging.getLevelNamesMapping()
+_NAME_TO_LEVEL = {
+    "CRITICAL": logging.CRITICAL,
+    "FATAL": logging.FATAL,
+    "ERROR": logging.ERROR,
+    "WARN": logging.WARNING,
+    "WARNING": logging.WARNING,
+    "INFO": logging.INFO,
+    "INFORMATION": logging.INFO,  # .NET parity
+    "DEBUG": logging.DEBUG,
+    "NOTSET": logging.NOTSET,
+}
+
+_DEFAULT_NAMESPACE = "default"

microsoft_agents_activity-1.10.0.dev2/microsoft_agents/activity/config/_logging/_load.py

@@ -0,0 +1,38 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+import logging
+from typing import Mapping
+
+from ..configuration import Configuration
+from ._logging_configuration import _LoggingConfiguration
+from ._color_formatter import ColorFormatter
+from ._constants import _DEFAULT_NAMESPACE
+
+
+def _configure_logging(_config: Mapping | Configuration | _LoggingConfiguration):
+    """Configures logging based on the provided logging configuration dictionary.
+
+    :param config: A Configuration object or _LoggingConfiguration instance containing logging configuration.
+    :raises ValueError: If an invalid log level is provided in the configuration.
+    """
+
+    if isinstance(_config, Mapping):
+        config = _LoggingConfiguration.from_mapping(_config)
+    else:
+        config = _LoggingConfiguration.from_configuration(_config)
+
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(
+        ColorFormatter(use_colors=console_handler.stream.isatty())
+    )
+
+    for entry in config.log_levels:
+        if entry.namespace == _DEFAULT_NAMESPACE:
+            logger = logging.getLogger()
+        else:
+            logger = logging.getLogger(entry.namespace)
+        logger.propagate = False  # Prevent log messages from being propagated
+        logger.handlers.clear()  # Remove existing handlers to prevent duplicates
+        logger.addHandler(console_handler)
+        logger.setLevel(entry.level)

microsoft_agents_activity-1.10.0.dev2/microsoft_agents/activity/config/_logging/_logging_configuration.py

@@ -0,0 +1,57 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping
+
+from microsoft_agents.activity.errors import configuration_errors
+
+from ..configuration import Configuration, _Configurable
+from .._utils import _xpath
+from ._constants import _NAME_TO_LEVEL
+
+
+@dataclass(frozen=True)
+class _LogLevelEntry:
+    """Represents a logging level entry with a namespace and level."""
+
+    namespace: str
+    level: int
+
+    def __init__(self, namespace: str, level: str) -> None:
+        level_upper = level.upper()
+        if level_upper not in _NAME_TO_LEVEL:
+            raise ValueError(
+                configuration_errors.InvalidLoggingConfiguration.format(
+                    namespace, level
+                )
+            )
+        object.__setattr__(self, "namespace", namespace.lower())
+        object.__setattr__(self, "level", _NAME_TO_LEVEL[level_upper])
+
+
+@dataclass(frozen=True)
+class _LoggingConfiguration(_Configurable):
+    """Configuration class for logging levels."""
+
+    log_levels: list[_LogLevelEntry]
+
+    @classmethod
+    def _from_configuration(cls, config: Configuration) -> _LoggingConfiguration:
+
+        raw_log_levels = config.get(_xpath("log_level"), default={})
+        if not isinstance(raw_log_levels, Mapping):
+            raise ValueError(
+                configuration_errors.InvalidLoggingConfiguration.format(
+                    "log_levels", raw_log_levels
+                )
+            )
+        log_levels: list[_LogLevelEntry] = [
+            _LogLevelEntry(namespace, level)
+            for namespace, level in raw_log_levels.items()
+        ]
+        return cls(log_levels)

microsoft_agents_activity-1.10.0.dev2/microsoft_agents/activity/config/_resolve.py

@@ -0,0 +1,96 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import Any, Callable, Mapping
+
+from ._utils import _MISSING, _get, _parse_env_var_name, _path, _try_set
+
+
+def _expand_paths(
+    source: Mapping, path_transformer: Callable[[str], str]
+) -> dict[str, Any]:
+    expanded: dict[str, Any] = {}
+
+    def copy_value(value: Any) -> Any:
+        if isinstance(value, Mapping):
+            return _expand_paths(value, path_transformer)
+        if isinstance(value, list):
+            return [copy_value(item) for item in value]
+        return value
+
+    def populate(mapping: Mapping, parts: list[str]) -> None:
+        for key, value in mapping.items():
+            if not isinstance(key, (str, int)):
+                raise TypeError("Configuration keys must be strings or integers")
+            path = parts + [str(key)]
+            if isinstance(value, Mapping) and value:
+                populate(value, path)
+                continue
+            name = path_transformer(_path(*path))
+            existing = _get(expanded, name, default=_MISSING)
+            if isinstance(value, Mapping) and isinstance(existing, Mapping):
+                continue
+            if not _try_set(expanded, name, copy_value(value)):
+                raise ValueError(f"Conflicting configuration path {name}")
+
+    populate(source, [])
+    return expanded
+
+
+def _normalize(
+    source: Mapping, *, path_transformer: Callable[[str], str] | None = None
+) -> dict[str, Any]:
+    """Expand paths and copy containers, normalizing indexed mappings to lists."""
+    transform = path_transformer or _parse_env_var_name
+    expanded = _expand_paths(source, transform)
+
+    def convert(value: Any) -> Any:
+        if isinstance(value, dict):
+            converted = {key: convert(item) for key, item in value.items()}
+            if converted and all(key.isdecimal() for key in converted):
+                indices = sorted(converted, key=int)
+                if len({int(key) for key in indices}) != len(indices):
+                    raise ValueError("Duplicate configuration list indices")
+                return [converted[key] for key in indices]
+            return converted
+        if isinstance(value, list):
+            return [convert(item) for item in value]
+        return value
+
+    return {key: convert(value) for key, value in expanded.items()}
+
+
+def _merge(
+    defaults: dict[str, Any],
+    primary: dict[str, Any],
+    *,
+    _base_path: str = "",
+) -> dict[str, Any]:
+    """Merge owned mappings in place; primary lists replace default lists."""
+    for key, value in primary.items():
+        if key not in defaults:
+            defaults[key] = value
+            continue
+        previous = defaults[key]
+        name = _path(_base_path, key) if _base_path else key
+        if isinstance(previous, dict) and isinstance(value, dict):
+            _merge(previous, value, _base_path=name)
+        elif isinstance(previous, dict) or isinstance(value, dict):
+            raise TypeError(f"Conflicting configuration structure at {name}")
+        else:
+            defaults[key] = value
+    return defaults
+
+
+def _resolve(
+    primary: Mapping,
+    defaults: Mapping | None = None,
+    *,
+    path_transformer: Callable[[str], str] | None = None,
+) -> dict[str, Any]:
+    """Normalize each source independently, then merge with primary precedence."""
+    base = _normalize(
+        defaults if defaults is not None else {}, path_transformer=path_transformer
+    )
+    overrides = _normalize(primary, path_transformer=path_transformer)
+    return _merge(base, overrides)