From e49a6c1808acf293063a1401f3f6c20ecde865fa Mon Sep 17 00:00:00 2001 From: BethanyG Date: Mon, 11 May 2026 19:17:12 -0700 Subject: [PATCH] Updated docstrings in exemplar files to use Google style. --- .../concept/black-jack/.meta/exemplar.py | 73 ++++++++++++------- .../concept/card-games/.meta/exemplar.py | 53 ++++++++++---- .../concept/cater-waiter/.meta/exemplar.py | 71 ++++++++++++------ .../.meta/exemplar.py | 65 +++++++++++------ 4 files changed, 176 insertions(+), 86 deletions(-) diff --git a/exercises/concept/black-jack/.meta/exemplar.py b/exercises/concept/black-jack/.meta/exemplar.py index 27c7a5dc07e..ae8df079c12 100644 --- a/exercises/concept/black-jack/.meta/exemplar.py +++ b/exercises/concept/black-jack/.meta/exemplar.py @@ -8,12 +8,15 @@ def value_of_card(card): """Determine the scoring value of a card. - :param card: str - given card. - :return: int - value of a given card. See below for values. + Parameters: + card (str): The given card. - 1. 'J', 'Q', or 'K' (otherwise known as "face cards") = 10 - 2. 'A' (ace card) = 1 - 3. '2' - '10' = numerical value. + Returns: + int: The value of a given card. See below for values. + + 1. 'J', 'Q', or 'K' (otherwise known as "face cards") = 10 + 2. 'A' (ace card) = 1 + 3. '2' - '10' = numerical value. """ if card in ('JQK'): @@ -31,12 +34,16 @@ def value_of_card(card): def higher_card(card_one, card_two): """Determine which card has a higher value in the hand. - :param card_one, card_two: str - cards dealt in hand. See below for values. - :return: str or tuple - resulting Tuple contains both cards if they are of equal value. + Parameters: + card_one (str): First card dealt in the hand. See below for values. + card_two (str): Second card dealt in the hand. See below for values. + + 1. 'J', 'Q', or 'K' (otherwise known as "face cards") = 10 + 2. 'A' (ace card) = 1 + 3. '2' - '10' = numerical value. - 1. 'J', 'Q', or 'K' (otherwise known as "face cards") = 10 - 2. 'A' (ace card) = 1 - 3. '2' - '10' = numerical value. + Returns: + str or tuple: The resulting Tuple contains both cards if they are of equal value. """ card_one_value = value_of_card(card_one) @@ -55,14 +62,18 @@ def higher_card(card_one, card_two): def value_of_ace(card_one, card_two): - """Calculate the most advantageous value for the ace card. + """Calculate the most advantageous value for an upcoming ace card. + + Parameters: + card_one (str): First card dealt in the hand. See below for values. + card_two (str): Second card dealt in the hand. See below for values. - :param card_one, card_two: str - card dealt. See below for values. - :return: int - either 1 or 11 value of the upcoming ace card. + 1. 'J', 'Q', or 'K' (otherwise known as "face cards") = 10 + 2. 'A' (ace card) = 11 (if already in hand) + 3. '2' - '10' = numerical value. - 1. 'J', 'Q', or 'K' (otherwise known as "face cards") = 10 - 2. 'A' (ace card) = 11 (if already in hand) - 3. '2' - '10' = numerical value. + Returns: + int: Either 1 or 11, which is the value of the upcoming ace card. """ card_one_value = 11 if card_one == 'A' else value_of_card(card_one) @@ -76,12 +87,16 @@ def value_of_ace(card_one, card_two): def is_blackjack(card_one, card_two): """Determine if the hand is a 'natural' or 'blackjack'. - :param card_one, card_two: str - card dealt. See below for values. - :return: bool - is the hand is a blackjack (two cards worth 21). + Parameters: + card_one (str): First card dealt in the hand. See below for values. + card_two (str): Second card dealt in the hand. See below for values. - 1. 'J', 'Q', or 'K' (otherwise known as "face cards") = 10 - 2. 'A' (ace card) = 11 (if already in hand) - 3. '2' - '10' = numerical value. + 1. 'J', 'Q', or 'K' (otherwise known as "face cards") = 10 + 2. 'A' (ace card) = 11 (if already in hand) + 3. '2' - '10' = numerical value. + + Returns: + bool: Is the hand is a blackjack (two cards worth 21). """ return (card_one == 'A' or card_two == 'A') and (value_of_card(card_one) == 10 or value_of_card(card_two) == 10) @@ -90,8 +105,12 @@ def is_blackjack(card_one, card_two): def can_split_pairs(card_one, card_two): """Determine if a player can split their hand into two hands. - :param card_one, card_two: str - cards dealt. - :return: bool - can the hand be split into two pairs? (i.e. cards are of the same value). + Parameters: + card_one (str): First card in the hand. + card_two (str): Second card in the hand. + + Returns: + bool: Can the hand be split into two pairs? (i.e. cards are of the same value). """ return value_of_card(card_one) == value_of_card(card_two) @@ -100,8 +119,12 @@ def can_split_pairs(card_one, card_two): def can_double_down(card_one, card_two): """Determine if a blackjack player can place a double down bet. - :param card_one, card_two: str - first and second cards in hand. - :return: bool - can the hand can be doubled down? (i.e. totals 9, 10 or 11 points). + Parameters: + card_one (str): First card in the hand. + card_two (str): Second card in the hand. + + Returns: + bool: Can the hand can be doubled down? (i.e. totals 9, 10 or 11 points). """ return 8 < value_of_card(card_one) + value_of_card(card_two) < 12 diff --git a/exercises/concept/card-games/.meta/exemplar.py b/exercises/concept/card-games/.meta/exemplar.py index d6531f01865..35b1b5377b8 100644 --- a/exercises/concept/card-games/.meta/exemplar.py +++ b/exercises/concept/card-games/.meta/exemplar.py @@ -7,8 +7,11 @@ def get_rounds(number): """Create a list containing the current and next two round numbers. - :param number: int - current round number. - :return: list - current round and the two that follow. + Parameters: + number (int): The current round number. + + Returns: + list: The current round number and the two that follow. """ return [number, number + 1, number + 2] @@ -17,9 +20,12 @@ def get_rounds(number): def concatenate_rounds(rounds_1, rounds_2): """Concatenate two lists of round numbers. - :param rounds_1: list - first rounds played. - :param rounds_2: list - second set of rounds played. - :return: list - all rounds played. + Parameters: + rounds_1 (list): The first rounds played. + rounds_2 (list): The second group of rounds played. + + Returns: + list: All rounds played. """ return rounds_1 + rounds_2 @@ -28,9 +34,12 @@ def concatenate_rounds(rounds_1, rounds_2): def list_contains_round(rounds, number): """Check if the list of rounds contains the specified number. - :param rounds: list - rounds played. - :param number: int - round number. - :return: bool - was the round played? + Parameters: + rounds (list): The rounds played. + number (int): The round number. + + Returns: + bool: Was the round played? """ return number in rounds @@ -39,8 +48,11 @@ def list_contains_round(rounds, number): def card_average(hand): """Calculate and returns the average card value from the list. - :param hand: list - cards in hand. - :return: float - average value of the cards in the hand. + Parameters: + hand (list): The cards in the hand. + + Returns: + float: The average value of the cards in the hand. """ return sum(hand) / len(hand) @@ -49,8 +61,11 @@ def card_average(hand): def approx_average_is_average(hand): """Return if the (average of first and last card values) OR ('middle' card) == calculated average. - :param hand: list - cards in hand. - :return: bool - does one of the approximate averages equal the `true average`? + Parameters: + hand (list): The cards in the hand. + + Returns: + bool: Does one of the approximate averages equal the `true average`? """ real_average = card_average(hand) @@ -68,8 +83,11 @@ def approx_average_is_average(hand): def average_even_is_average_odd(hand): """Return if the (average of even indexed card values) == (average of odd indexed card values). - :param hand: list - cards in hand. - :return: bool - are even and odd averages equal? + Parameters: + hand (list): The cards in the hand. + + Returns: + bool: Are the even and odd averages equal? """ return card_average(hand[::2]) == card_average(hand[1::2]) @@ -78,8 +96,11 @@ def average_even_is_average_odd(hand): def maybe_double_last(hand): """Multiply a Jack card value in the last index position by 2. - :param hand: list - cards in hand. - :return: list - hand with Jacks (if present) value doubled. + Parameters: + hand (list): The cards in the hand. + + Returns: + list: The hand with Jacks (if present) value doubled. """ if hand[-1] == 11: diff --git a/exercises/concept/cater-waiter/.meta/exemplar.py b/exercises/concept/cater-waiter/.meta/exemplar.py index 8f48c520f2e..b9c5d3e1989 100644 --- a/exercises/concept/cater-waiter/.meta/exemplar.py +++ b/exercises/concept/cater-waiter/.meta/exemplar.py @@ -13,12 +13,16 @@ def clean_ingredients(dish_name, dish_ingredients): """Remove duplicates from `dish_ingredients`. - :param dish_name: str - containing the dish name. - :param dish_ingredients: list - dish ingredients. - :return: tuple - containing (dish_name, ingredient set). + Parameters: + dish_name (str): The name of the dish. + dish_ingredients (list): The ingredients for the dish. + + Returns: + tuple: Containing (dish_name, ingredient set). This function should return a `tuple` with the name of the dish as the first item, followed by the de-duped `set` of ingredients as the second item. + """ return dish_name, set(dish_ingredients) @@ -27,12 +31,16 @@ def clean_ingredients(dish_name, dish_ingredients): def check_drinks(drink_name, drink_ingredients): """Append "Cocktail" (alcohol) or "Mocktail" (no alcohol) to `drink_name`, based on `drink_ingredients`. - :param drink_name: str - name of the drink. - :param drink_ingredients: list - ingredients in the drink. - :return: str - drink_name appended with "Mocktail" or "Cocktail". + Parameters: + drink_name (str): Name of the drink. + drink_ingredients (list): Ingredients in the drink. + + Returns: + str: drink_name appended with "Mocktail" or "Cocktail". The function should return the name of the drink followed by "Mocktail" (non-alcoholic) and drink name followed by "Cocktail" (includes alcohol). + """ if not ALCOHOLS.isdisjoint(drink_ingredients): @@ -44,13 +52,16 @@ def check_drinks(drink_name, drink_ingredients): def categorize_dish(dish_name, dish_ingredients): """Categorize `dish_name` based on `dish_ingredients`. - :param dish_name: str - dish to be categorized. - :param dish_ingredients: list - ingredients for the dish. - :return: str - the dish name appended with ": ". + Parameters: + dish_name (str): The dish to be categorized. + dish_ingredients (set): The ingredients for the dish. + + Returns: + str: TThe dish name appended with ": ". This function should return a string with the `dish name: ` (which meal category the dish belongs to). `` can be any one of (VEGAN, VEGETARIAN, PALEO, KETO, or OMNIVORE). - All dishes will "fit" into one of the categories imported from `sets_categories_data.py` + All dishes will "fit" into one of the categories imported from `sets_categories_data.py`. """ @@ -69,8 +80,11 @@ def categorize_dish(dish_name, dish_ingredients): def tag_special_ingredients(dish): """Compare `dish` ingredients to `SPECIAL_INGREDIENTS`. - :param dish: tuple - of (dish name, list of dish ingredients). - :return: tuple - containing (dish name, dish special ingredients). + Parameters: + dish (tuple): (dish name, list of dish ingredients). + + Returns: + tuple: Containing (dish name, dish special ingredients). Return the dish name followed by the `set` of ingredients that require a special note on the dish description. For the purposes of this exercise, all allergens or special ingredients that need to be tracked are in the @@ -81,12 +95,17 @@ def tag_special_ingredients(dish): def compile_ingredients(dishes): - """Create a master list of ingredients. + """Determine which `dishes` are designated `appetizers` and remove them. + + Parameters: + dishes (list): Group of dish names. + appetizers (list): Group of appetizer names. - :param dishes: list - of dish ingredient sets. - :return: set - of ingredients compiled from `dishes`. + Returns: + list: Group of dish names that do not appear on appetizer list. - This function should return a `set` of all ingredients from all listed dishes. + The function should return the list of dish names with appetizer names removed. + Either list could contain duplicates and may require de-duping. """ combined_ingredients = set() @@ -100,9 +119,12 @@ def compile_ingredients(dishes): def separate_appetizers(dishes, appetizers): """Determine which `dishes` are designated `appetizers` and remove them. - :param dishes: list - of dish names. - :param appetizers: list - of appetizer names. - :return: list - of dish names that do not appear on appetizer list. + Parameters: + dishes (list): Group of dish names. + appetizers (list): Group of appetizer names. + + Returns: + list: Group of dish names that do not appear on appetizer list. The function should return the list of dish names with appetizer names removed. Either list could contain duplicates and may require de-duping. @@ -114,13 +136,16 @@ def separate_appetizers(dishes, appetizers): def singleton_ingredients(dishes, intersection): """Determine which `dishes` have a singleton ingredient (an ingredient that only appears once across dishes). - :param dishes: list - of ingredient sets. - :param intersection: constant - can be one of `_INTERSECTION` constants imported from `sets_categories_data.py`. - :return: set - containing singleton ingredients. + Parameters: + dishes (list): Group of ingredient sets. + intersection (constant): Can be one of `_INTERSECTIONS` constants imported from `sets_categories_data.py`. + + Returns: + set: Containing singleton ingredients. Each dish is represented by a `set` of its ingredients. - Each `_INTERSECTION` is an `intersection` of all dishes in the category. `` can be any one of: + Each `_INTERSECTIONS` is an `intersection` of all dishes in the category. `` can be any one of: (VEGAN, VEGETARIAN, PALEO, KETO, or OMNIVORE). The function should return a `set` of ingredients that only appear in a single dish. diff --git a/exercises/concept/chaitanas-colossal-coaster/.meta/exemplar.py b/exercises/concept/chaitanas-colossal-coaster/.meta/exemplar.py index 24a83949647..5d40f939b8e 100644 --- a/exercises/concept/chaitanas-colossal-coaster/.meta/exemplar.py +++ b/exercises/concept/chaitanas-colossal-coaster/.meta/exemplar.py @@ -4,11 +4,14 @@ def add_me_to_the_queue(express_queue, normal_queue, ticket_type, person_name): """Add a person to the 'express' or 'normal' queue depending on the ticket number. - :param express_queue: list - names in the Fast-track queue. - :param normal_queue: list - names in the normal queue. - :param ticket_type: int - type of ticket. 1 = express, 0 = normal. - :param person_name: str - name of person to add to a queue. - :return: list - the (updated) queue the name was added to. + Parameters: + express_queue (list): The names in the Fast-track queue. + normal_queue (list): The names in the normal queue. + ticket_type (int): Type of ticket. 1 = express, 0 = normal. + person_name (str): The name of person to add to a queue. + + Returns: + list: The (updated) queue the name was added to. """ result = express_queue if ticket_type == 1 else normal_queue @@ -19,9 +22,12 @@ def add_me_to_the_queue(express_queue, normal_queue, ticket_type, person_name): def find_my_friend(queue, friend_name): """Search the queue for a name and return their queue position (index). - :param queue: list - names in the queue. - :param friend_name: str - name of friend to find. - :return: int - index at which the friends name was found. + Parameters: + queue (list): The names in the queue. + friend_name (str): The name of friend to find. + + Returns: + int: The index at which the friends name was found. """ return queue.index(friend_name) @@ -30,10 +36,13 @@ def find_my_friend(queue, friend_name): def add_me_with_my_friends(queue, index, person_name): """Insert the late arrival's name at a specific index of the queue. - :param queue: list - names in the queue. - :param index: int - the index at which to add the new name. - :param person_name: str - the name to add. - :return: list - queue updated with new name. + Parameters: + queue (list): The names in the queue. + index (int): The index at which to add the new name. + person_name (str): The name to add. + + Returns: + list: The queue updated with new name. """ queue.insert(index, person_name) @@ -43,9 +52,12 @@ def add_me_with_my_friends(queue, index, person_name): def remove_the_mean_person(queue, person_name): """Remove the mean person from the queue by the provided name. - :param queue: list - names in the queue. - :param person_name: str - name of mean person. - :return: list - queue update with the mean persons name removed. + Parameters: + queue (list): The names in the queue. + person_name (str): The name of mean person. + + Returns: + list: The queue updated with the mean persons name removed. """ queue.remove(person_name) @@ -55,9 +67,12 @@ def remove_the_mean_person(queue, person_name): def how_many_namefellows(queue, person_name): """Count how many times the provided name appears in the queue. - :param queue: list - names in the queue. - :param person_name: str - name you wish to count or track. - :return: int - the number of times the name appears in the queue. + Parameters: + queue (list): The names in the queue. + person_name (str): The name you wish to count or track. + + Returns: + int: The number of times the name appears in the queue. """ return queue.count(person_name) @@ -66,8 +81,11 @@ def how_many_namefellows(queue, person_name): def remove_the_last_person(queue): """Remove the person in the last index from the queue and return their name. - :param queue: list - names in the queue. - :return: str - name that has been removed from the end of the queue. + Parameters: + queue (list): The names in the queue. + + Returns: + str: The name that has been removed from the end of the queue. """ return queue.pop() @@ -76,8 +94,11 @@ def remove_the_last_person(queue): def sorted_names(queue): """Sort the names in the queue in alphabetical order and return the result. - :param queue: list - names in the queue. - :return: list - copy of the queue in alphabetical order. + Parameters: + queue (list): The names in the queue. + + Returns: + list: A copy of the queue in alphabetical order. """ new_queue = queue[:]