Added docstrings

resa_padel/gestion_sports/gestion_sports_connector.py

@@ -18,6 +18,9 @@ POST_HEADERS = config.get_post_headers("gestion-sports")
 
 
 class GestionSportsConnector:
+    """
+    Handle the specific booking requests to Gestion-Sports
+    """
 
     def __init__(self, session: ClientSession, url: str):
         LOGGER.info("Initializing connection to GestionSports API")
@@ -26,24 +29,49 @@ class GestionSportsConnector:
         self.payload_builder = GestionSportsPayloadBuilder()
 
     @property
-    def connection_url(self) -> str:
+    def landing_url(self) -> str:
+        """
+        Get the URL to the landing page of Gestion-Sports
+
+        :return: the URL to the landing page
+        """
         return urljoin(self.url, "/connexion.php?")
 
     @property
     def login_url(self) -> str:
+        """
+        Get the URL to the connection login of Gestion-Sports
+
+        :return: the URL to the login page
+        """
         return urljoin(self.url, "/connexion.php?")
 
     @property
     def booking_url(self) -> str:
+        """
+        Get the URL to the booking page of Gestion-Sports
+
+        :return: the URL to the booking page
+        """
         return urljoin(self.url, "/membre/reservation.html?")
 
-    async def connect(self) -> ClientResponse:
+    async def land(self) -> ClientResponse:
+        """
+        Perform the request to the landing page in order to get the cookie PHPSESSIONID
+
+        :return: the response from the landing page
+        """
         LOGGER.info("Connecting to GestionSports API")
-        async with self.session.get(self.connection_url) as response:
+        async with self.session.get(self.landing_url) as response:
             await response.text()
             return response
 
     async def login(self, user: User, club: Club) -> ClientResponse:
+        """
+        Perform the request to the log in the user
+
+        :return: the response from the login
+        """
         payload = (
             self.payload_builder.login(user.login)
             .password(user.password)
@@ -58,6 +86,15 @@ class GestionSportsConnector:
             return response
 
     async def book(self, booking_filter: BookingFilter, club: Club) -> int | None:
+        """
+        Perform a request for each court at the same time to increase the chances to get a booking.
+        The gestion-sports backend does not allow several bookings at the same time
+        so there is no need to make each request one after the other
+
+        :param booking_filter: the booking information
+        :param club: the club where to book the court
+        :return: the booked court, or None if no court was booked
+        """
         # use asyncio to request a booking on every court
         # the gestion-sports backend is able to book only one court for a user
         bookings = await asyncio.gather(