From 313b3da53e69265680c7ee7bdb9bf0b73938d7c7 Mon Sep 17 00:00:00 2001 From: Elliot <3186037+elliot-100@users.noreply.github.com> Date: Mon, 15 Jul 2024 13:12:39 +0100 Subject: [PATCH] Docs: Revised README and minor docstring improvements --- README.md | 70 ++++++++++++++------------------- britishcycling_clubs/manager.py | 18 ++++----- britishcycling_clubs/profile.py | 6 +-- 3 files changed, 41 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 838332a..66a059b 100644 --- a/README.md +++ b/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. + + diff --git a/britishcycling_clubs/manager.py b/britishcycling_clubs/manager.py index 5a8ffcb..efa0c64 100644 --- a/britishcycling_clubs/manager.py +++ b/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`." ) diff --git a/britishcycling_clubs/profile.py b/britishcycling_clubs/profile.py index c6718f8..bd8913c 100644 --- a/britishcycling_clubs/profile.py +++ b/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}/"