add docs

Author: tizz98

clerk/client.py

@@ -4,12 +4,14 @@
 
 import aiohttp
 
-__all__ = ["Client", "Service"]
-
 from clerk.errors import ClerkAPIException
 
+__all__ = ["Client", "Service"]
+
 
 class Client:
+    """An API client for the clerk.dev API"""
+
     def __init__(
         self, token: str, base_url: str = "https://api.clerk.dev/v1/", timeout_seconds: float = 30.0
     ) -> None:

clerk/clients.py

@@ -9,14 +9,17 @@ class ClientsService(Service):
     verify_endpoint = endpoint + "/verify"
 
     async def list(self) -> List[types.Client]:
+        """Retrieve a list of all clients"""
         async with self._client.get(self.endpoint) as r:
             return [types.Client.parse_obj(s) for s in await r.json()]
 
     async def get(self, client_id: str) -> types.Client:
+        """Retrieve a client by its id"""
         async with self._client.get(f"{self.endpoint}/{client_id}") as r:
             return types.Client.parse_obj(await r.json())
 
     async def verify(self, token: str) -> types.Client:
+        """Verify a token and return its associated client, if valid"""
         request = types.VerifyRequest(token=token)
 
         async with self._client.post(self.verify_endpoint, data=request.json()) as r:

clerk/sessions.py

@@ -8,18 +8,22 @@ class SessionsService(Service):
     endpoint = "sessions"
 
     async def list(self) -> List[types.Session]:
+        """Retrieve a list of all sessions"""
         async with self._client.get(self.endpoint) as r:
             return [types.Session.parse_obj(s) for s in await r.json()]
 
     async def get(self, session_id: str) -> types.Session:
+        """Retrieve a session by its id"""
         async with self._client.get(f"{self.endpoint}/{session_id}") as r:
             return types.Session.parse_obj(await r.json())
 
     async def revoke(self, session_id: str) -> types.Session:
+        """Revoke a session by its id"""
         async with self._client.post(f"{self.endpoint}/{session_id}/revoke") as r:
             return types.Session.parse_obj(await r.json())
 
     async def verify(self, session_id: str, token: str) -> types.Session:
+        """Verify a session by its id and a given token"""
         request = types.VerifyRequest(token=token)
 
         async with self._client.post(

clerk/users.py

@@ -8,18 +8,22 @@ class UsersService(Service):
     endpoint = "users"
 
     async def list(self) -> List[types.User]:
+        """Retrieve a list of all users"""
         async with self._client.get(self.endpoint) as r:
             return [types.User.parse_obj(s) for s in await r.json()]
 
     async def get(self, user_id: str) -> types.User:
+        """Retrieve a user by their id"""
         async with self._client.get(f"{self.endpoint}/{user_id}") as r:
             return types.User.parse_obj(await r.json())
 
     async def delete(self, user_id: str) -> types.DeleteUserResponse:
+        """Delete a user by their id"""
         async with self._client.delete(f"{self.endpoint}/{user_id}") as r:
             return types.DeleteUserResponse.parse_obj(await r.json())
 
     async def update(self, user_id: str, request: types.UpdateUserRequest) -> types.User:
+        """Update a user by their id"""
         async with self._client.patch(
             f"{self.endpoint}/{user_id}", data=request.json(exclude_unset=True)
         ) as r:

clerk/verification.py

@@ -6,6 +6,10 @@
 
 class VerificationService(Service):
     async def verify(self, session_token: str, session_id: Optional[str] = None) -> types.Session:
+        """Verify a session token and return the associated session, if any.
+
+        If a session_id is not passed then the client's last active session is returned.
+        """
         if not session_id:
             client = await self._client.clients.verify(session_token)
             if not client.last_active_session_id: