# Copyright 2025 Softwell S.r.l.
# Licensed under the Apache License, Version 2.0
"""Avatar — user identity with tags and extensible Bag data.
An Avatar is the authenticated user's profile within a session. It carries
the identity string, authorization tags, and arbitrary key-value data stored
in a Bag. Created by SessionMiddleware from the auth result, or directly via
``Avatar(identity, tags, data)``.
"""
from __future__ import annotations
from typing import Any
from genro_bag import Bag
__all__ = ["Avatar"]
[docs]
class Avatar:
"""User identity with tags and extensible data (Bag).
Attributes:
_identity: User identifier (username, email, etc.).
_tags: Authorization tags (roles/permissions).
_data: Extensible user data as Bag.
"""
__slots__ = ("_identity", "_tags", "_data")
[docs]
def __init__(
self,
identity: str = "anonymous",
tags: list[str] | None = None,
auth: dict[str, Any] | None = None,
) -> None:
"""Initialize avatar.
Args:
identity: User identifier (ignored if auth is provided).
tags: Authorization tags (ignored if auth is provided).
auth: Auth dict — if provided, identity and tags are extracted from it.
"""
if auth is not None:
self._identity = str(auth.get("identity", "unknown"))
self._tags = list(auth.get("tags", []))
else:
self._identity = identity
self._tags = tags or []
self._data = Bag()
@property
def identity(self) -> str:
"""User identifier."""
return self._identity
@property
def tags(self) -> list[str]:
"""Authorization tags."""
return self._tags
@property
def data(self) -> Bag:
"""Extensible user data as Bag."""
return self._data
if __name__ == "__main__":
pass