Docs: Revised README and minor docstring improvements

README.md

@@ -15,7 +15,8 @@ administrators.
 
 ## Prerequisites
 
-- Credentials for a club using the Club Management Tool
+- ID for a club
+- for Club Management Tool functions, valid user credentials
 
 
 ## Installation
@@ -39,66 +40,53 @@ See also https://playwright.dev/python/docs/browsers#install-system-dependencies
 
 ## Usage
 
-### Club profile URL
-
-```
-britishcycling_clubs.club_profile_url(
-    club_id: str
-) -> str
-```
-
 ### Get info from a club's profile
 
+```python
+britishcycling_clubs.get_profile_info(club_id="123")
 ```
-britishcycling_clubs.get_profile_info(
-    club_id: str
-) -> dict[str, int | str]
-```
-Return information from the club's public profile page; doesn't require login.
-
-Specifically, return a dict with these keys and corresponding values:
+Returns a dict with these keys and values:
 
-- `"club_name"`: Club name
-- `"total_members"`: Total club members
+- `"club_name"`: Club name [str]
+- `"total_members"`: Total club members [int]
 
 Example script `example_profile_info.py` loads club ID from `config.ini` (you'll
 need to copy `config_dist.ini`, populate club ID only and rename).
 It then retrieves and prints the club name and total member count.
 
 
-### Club manager URL (via login)
-
-```
-britishcycling_clubs.club_manager_url_via_login(
-    club_id: str
-) -> str
+### Construct club's profile URL
+```python
+britishcycling_clubs.club_profile_url(club_id="123")
 ```
-URL which redirects to Club Manager URL, via login if needed.
-
 
 ### Get member counts from Club Manager
-
-```
+```python
 britishcycling_clubs.get_manager_member_counts(
-    club_id: str,
-    username: str,
-    password: str,
-    manager_page_load_delay: int = 5,
-) -> dict[str, int]:
+    club_id="123",
+    username="USERNAME",
+    password="PASSWORD",
+    manager_page_load_delay=7,
+)
 ```
-Get numbers of active, new, expired members from the club manager page.
-
-Specifically, return a dict with these keys, and values from badges on corresponding
-tabs:
+Returns a dict with these keys and values:
 
-- `"active"`: Active Club Members
-- `"expired"`: Expired Club Members
-- `"new"`: New Club Subscriptions
+- `"active"`: count of 'Active Club Members' [int]
+- `"expired"`: count of 'Expired Club Members' [int]
+- `"new"`: count of 'New Club Subscriptions' i.e. pending members [int]
 
-This takes about 10s.
+This takes about 10 s.
 
 Example script `example_manager_member_counts.py` loads club ID and credentials from
 `config.ini` (you'll need to copy `config_dist.ini`, populate and rename to 
 `config.ini`).
 It then retrieves and prints the number of active, expired and new 
 club member counts from the club's Club Manager pages. 
+
+### Construct club's Club Manager URL (via login)
+```python
+britishcycling_clubs.club_manager_url_via_login(club_id=123)
+```
+Returns URL which redirects to Club Manager URL, via login if needed.
+
+

britishcycling_clubs/manager.py

@@ -38,16 +38,16 @@ def get_manager_member_counts(
 
     Parameters
     ----------
-    club_id
+    club_id :
         From the URL used to access club pages.
 
-    username
+    username :
         Username
 
-    password
+    password :
         Password
 
-    manager_page_load_delay
+    manager_page_load_delay :
         Time (s) allowed for club manager page to load. Defaults to 5.
         Consider increasing if 'Active member count was zero' exceptions occur.
 
@@ -57,9 +57,9 @@ def get_manager_member_counts(
 
     Raises
     ------
-    `ValueError`
-        if zero 'active members' would be returned, as this probably means
-        values hadn't populated correctly.
+    `ValueError` :
+        if zero 'active members' would be returned, as it's assumed this indicates
+        an issue with data collection.
     """
     logger = logging.getLogger(__name__)
     start_time = time.time()
@@ -104,7 +104,7 @@ def club_manager_url_via_login(club_id: str) -> str:
 
     Parameters
     ----------
-    club_id
+    club_id :
         From the URL used to access club pages.
     """
     return f"{_MANAGER_VIA_LOGIN_BASE_URL}{club_id}/"
@@ -126,7 +126,7 @@ def _process_manager_member_counts(member_counts: dict[str, str]) -> MemberCount
     # 'new' will often be genuinely zero; 'expired' could be genuinely zero
     if processed_member_counts["active"] == 0:
         error_message = (
-            "Active member count was zero; assuming error. "
+            "Active member count was zero; assuming issue with data collection. "
             f"{pformat(processed_member_counts)}. "
             "Consider increasing `manager_page_load_delay`."
         )

britishcycling_clubs/profile.py

@@ -21,7 +21,7 @@ def get_profile_info(club_id: str) -> ProfileInfo:
 
     Parameters
     ----------
-    club_id
+    club_id :
         From the URL used to access club pages.
 
     Returns
@@ -30,7 +30,7 @@ def get_profile_info(club_id: str) -> ProfileInfo:
 
     Raises
     ------
-    `ValueError`
+    `ValueError` :
         if information can't be located.
     """
     profile_url = club_profile_url(club_id)
@@ -51,7 +51,7 @@ def club_profile_url(club_id: str) -> str:
 
     Parameters
     ----------
-    club_id
+    club_id :
         From the URL used to access club pages.
     """
     return f"{_PROFILE_BASE_URL}{club_id}/"