Add Transformers.py

README.md

@@ -1,2 +1,40 @@
 # discord-presence-tracker
+A discord bot to track discord presence activity. It can be used, for example, as *played in different games* hours counter.
 
+## Commands
+Notes:
+- `total <something>` usually means just sum for numeric values in output.
+- `SPFR` short from *Show Position For Requested* mean in output we should show position in rating for a requested item.
+- `period`, `SPFR` should be preserved between redirects
+
+
+1. `/stats <User | None> <Game | None>` Gives information about hours spent in games for given user per games
+or in specified game.  
+   - Output: `Game name, spent hours`.  
+   - Features: Pagination, total hours, total hours for page, period.
+   - Redirects: `Game name` -> `/top_games 'Game name'` (or /top_players?).
+
+2. `/top_players <Game name | None>` Gives information about users who spent the most time
+in games or in a selected game.  
+    - Output: `User name, spent hours`
+    - Features: Pagination, total hours, total hours for page, period, SPFR (user by default).
+    - Redirects: `User name` -> `/stats 'User name'`.
+
+3. `/top_games` Gives information about most played games.
+    - Output: `Game name, spent hours` (NB: spent hours by all players)
+    - Features: Pagination, total hours, total hours for page, period, SPFR (No default, optional)
+    - Redirects: `Game name` -> `/top_players 'Game name'`.
+
+4. `/game_sessions ((<User | None) | (Game name | None))` Gives raw information about game sessions.
+   - Output: `User name, start time, end time, diff, activity name`
+   - Features: Pagination, total count of sessions, total count of sessions for page, period
+   - Redirects: None
+
+## Aspects to consider
+### End user security
+- User might want to restrict who are able to view his activity
+- User might want to forbid collecting of his presence data
+- User might want to delete collected data about him
+- User might want to download his collected presence data
+
+It's possible to fingerprint user's machines activity start time

Transformers.py

@@ -0,0 +1,23 @@
+import discord
+from datetime import datetime
+from datetime_utils import to_unix
+from loguru import logger
+
+
+class DateTransformer(discord.app_commands.Transformer):
+    """
+    Converts date as 2022-12-24 to unix timestamp
+    """
+
+    async def transform(self, interaction: discord.Interaction, value: str, /) -> int:
+        logger.trace(f'Converting {value} to unix timestamp')
+
+        date_format = "%Y-%m-%d"
+
+        try:
+            date = to_unix(datetime.strptime(value, date_format))
+            return date
+
+        except Exception:
+            logger.opt(exception=True).warning(f"Failed to parse to datetime {value!r}")
+            raise