Coverage for app / backend / src / couchers / event_log.py: 100%

1from typing import Any 

2 

3from sqlalchemy.orm import Session 

4 

5from couchers.context import CouchersContext 

6from couchers.models.logging import EventLog 

7 

8 

9def log_event( 

10 context: CouchersContext, 

11 session: Session, 

12 event_type: str, 

13 /, 

14 properties: dict[str, Any], 

15 *, 

16 _override_user_id: int | None = None, 

17) -> None: 

18 """ 

19 Record an analytics event. 

20 

21 Usage: 

22 log_event(context, session, "host_request.sent", {"host_id": host.id, "nights": 3}) 

23 

24 Use _override_user_id for actions where the user is known but may not be in context 

25 (e.g. signup, token-based actions): 

26 log_event(context, session, "account.signup_completed", {...}, _override_user_id=user.id) 

27 

28 If context has no user_id and no _override_user_id is given, user_id will be None (anonymous event). 

29 

30 Event type naming convention: "noun.verbed" with dot-separated hierarchy, e.g. 

31 account.login 

32 host_request.sent 

33 host_request.accepted 

34 message.sent 

35 reference.written 

36 """ 

37 user_id = _override_user_id if _override_user_id is not None else context._user_id 

38 

39 session.add( 

40 EventLog( 

41 event_type=event_type, 

42 user_id=user_id, 

43 sofa=context._sofa, 

44 properties=properties, 

45 ) 

46 )