[Exemplar Files Docstrings]: Updated docstrings for exemplar solutions.

exercises/concept/guidos-gorgeous-lasagna/.meta/exemplar.py

@@ -11,8 +11,11 @@
 def bake_time_remaining(elapsed_bake_time):
     """Calculate the bake time remaining.
 
-    :param elapsed_bake_time: int - baking time already elapsed.
-    :return: int - remaining bake time (in minutes) derived from 'EXPECTED_BAKE_TIME'.
+    Parameters:
+        elapsed_bake_time (int): The baking time already elapsed.
+
+    Returns:
+        int: The remaining bake time (in minutes) derived from 'EXPECTED_BAKE_TIME'.
 
     Function that takes the actual minutes the lasagna has been in the oven as
     an argument and returns how many minutes the lasagna still needs to bake
@@ -25,11 +28,15 @@ def bake_time_remaining(elapsed_bake_time):
 def preparation_time_in_minutes(number_of_layers):
     """Calculate the preparation time.
 
-    :param number_of_layers: int - the number of lasagna layers made.
-    :return: int - amount of prep time (in minutes), based on 2 minutes per layer added.
+    Parameters:
+        number_of_layers(int): The number of lasagna layers made.
+
+    Returns:
+        int: Amount of prep time (in minutes), based on 2 minutes per layer added.
 
     This function takes an integer representing the number of layers added to the dish,
     calculating preparation time using a time of 2 minutes per layer added.
+
     """
 
     return number_of_layers * PREPARATION_TIME
@@ -38,13 +45,17 @@ def preparation_time_in_minutes(number_of_layers):
 def elapsed_time_in_minutes(number_of_layers, elapsed_bake_time):
     """Calculate the elapsed time.
 
-    :param number_of_layers: int - the number of layers in the lasagna.
-    :param elapsed_bake_time: int - elapsed cooking time.
-    :return: int - total time elapsed (in in minutes) preparing and cooking.
+    Parameters:
+        number_of_layers (int): The number of layers in the lasagna.
+        elapsed_bake_time (int): Elapsed cooking time.
+
+    Returns:
+        int: Total time elapsed (in minutes) preparing + cooking.
 
     This function takes two integers representing the number of lasagna layers and the
     time already spent baking and calculates the total elapsed minutes spent cooking the
     lasagna.
+
     """
 
     return preparation_time_in_minutes(number_of_layers) + elapsed_bake_time

exercises/concept/meltdown-mitigation/.meta/exemplar.py

@@ -4,14 +4,19 @@
 def is_criticality_balanced(temperature, neutrons_emitted):
     """Verify criticality is balanced.
 
-    :param temperature: int or float - temperature value in kelvin.
-    :param neutrons_emitted: int or float - number of neutrons emitted per second.
-    :return: bool - is criticality balanced?
-
-    A reactor is said to be critical if it satisfies the following conditions:
-    - The temperature is less than 800 K.
-    - The number of neutrons emitted per second is greater than 500.
-    - The product of temperature and neutrons emitted per second is less than 500000.
+    Parameters:
+        temperature (int or float): The temperature value in kelvin.
+        neutrons_emitted (int or float): The number of neutrons emitted per second.
+
+    Returns:
+        bool: Is criticality balanced?
+
+    Note:
+        A reactor is said to be balanced in criticality if it satisfies the following conditions:
+            - The temperature is less than 800 K.
+            - The number of neutrons emitted per second is greater than 500.
+            - The product of temperature and neutrons emitted per second is less than 500000.
+
     """
 
     output = temperature * neutrons_emitted
@@ -26,21 +31,24 @@ def is_criticality_balanced(temperature, neutrons_emitted):
 def reactor_efficiency(voltage, current, theoretical_max_power):
     """Assess reactor efficiency zone.
 
-    :param voltage: int or float - voltage value.
-    :param current: int or float - current value.
-    :param theoretical_max_power: int or float - power that corresponds to a 100% efficiency.
-    :return: str - one of ('green', 'orange', 'red', or 'black').
+    Parameters:
+        voltage (int or float): Voltage value.
+        current (int or float): Current value.
+        theoretical_max_power (int or float): The power level that corresponds to a 100% efficiency.
 
-    Efficiency can be grouped into 4 bands:
+    Returns:
+        str: One of ('green', 'orange', 'red', or 'black').
 
-    1. green -> efficiency of 80% or more,
-    2. orange -> efficiency of less than 80% but at least 60%,
-    3. red -> efficiency below 60%, but still 30% or more,
-    4. black ->  less than 30% efficient.
+    Note:
+        Efficiency can be grouped into 4 bands:
+            1. green -> efficiency of 80% or more,
+            2. orange -> efficiency of less than 80% but at least 60%,
+            3. red -> efficiency below 60%, but still 30% or more,
+            4. black ->  less than 30% efficient.
 
-    The percentage value is calculated as
-    (generated power/ theoretical max power)*100
-    where generated power = voltage * current
+        The percentage value is calculated as
+        (generated power/ theoretical max power)*100
+        where generated power = voltage * current
     """
 
     generated_power = voltage * current
@@ -61,14 +69,18 @@ def reactor_efficiency(voltage, current, theoretical_max_power):
 def fail_safe(temperature, neutrons_produced_per_second, threshold):
     """Assess and return status code for the reactor.
 
-    :param temperature: int or float - value of the temperature in kelvin.
-    :param neutrons_produced_per_second: int or float - neutron flux.
-    :param threshold: int or float - threshold for category.
-    :return: str - one of ('LOW', 'NORMAL', 'DANGER').
+    Parameters:
+        temperature (int or float): The value of the temperature in kelvin.
+        neutrons_produced_per_second (int or float): The neutron flux.
+        threshold (int or float): The threshold for the category.
+
+    Returns:
+        str: One of ('LOW', 'NORMAL', 'DANGER').
 
-    1. 'LOW' -> `temperature * neutrons per second` < 90% of `threshold`
-    2. 'NORMAL' -> `temperature * neutrons per second` +/- 10% of `threshold`
-    3. 'DANGER' -> `temperature * neutrons per second` is not in the above-stated ranges
+    Note:
+        1. 'LOW' -> `temperature * neutrons per second` < 90% of `threshold`
+        2. 'NORMAL' -> `temperature * neutrons per second` +/- 10% of `threshold`
+        3. 'DANGER' -> `temperature * neutrons per second` is not in the above-stated ranges
     """
 
     output = temperature * neutrons_produced_per_second

exercises/concept/plane-tickets/.meta/exemplar.py

@@ -8,13 +8,16 @@
 def generate_seat_letters(number):
     """Generate a series of letters for airline seats.
 
-    :param number: int - total number of seat letters to be generated.
-    :return: generator - generator that yields seat letters.
+    Parameters:
+        number (int): Total number of seat letters to be generated.
 
-    Seat letters are generated from A to D.
-    After D it should start again with A.
+    Returns:
+        generator: A generator that yields seat letters.
 
-    Example: A, B, C, D
+    Note:
+        Seat letters are generated from A to D.
+        After D the sequence starts again with A.
+        For example: A, B, C, D, A, B
 
     """
 
@@ -25,17 +28,18 @@ def generate_seat_letters(number):
 def generate_seats(number):
     """Generate a series of identifiers for airline seats.
 
-    :param number: int - total number of seats to be generated.
-    :return: generator - generator that yields seat numbers.
+    Parameters:
+        number (int): The total number of seats to be generated.
 
-    A seat number consists of the row number and the seat letter.
+    Returns:
+        generator: A generator that yields seat numbers.
 
-    There is no row 13.
-    Each row has 4 seats.
+    Note:
+        A seat number consists of the row number and the seat letter.
+        There is no row 13, and each row has 4 seats.
 
-    Seats should be sorted from low to high.
-
-    Example: 3C, 3D, 4A, 4B
+        Seats should be sorted from low to high.
+        For exampl: 3C, 3D, 4A, 4B
 
     """
 
@@ -53,10 +57,12 @@ def generate_seats(number):
 def assign_seats(passengers):
     """Assign seats to passengers.
 
-    :param passengers: list[str] - a list of strings containing names of passengers.
-    :return: dict - with the names of the passengers as keys and seat numbers as values.
+    Parameters:
+        passengers (list[str]): A list of strings containing names of passengers.
 
-    Example output: {"Adele": "1A", "Björk": "1B"}
+    Returns:
+        dict: With passenger names as keys and seat numbers as values.
+        Example output: {"Adele": "1A", "Björk": "1B"}
 
     """
 
@@ -69,9 +75,12 @@ def assign_seats(passengers):
 def generate_codes(seat_numbers, flight_id):
     """Generate codes for a ticket.
 
-    :param seat_numbers: list[str] - list of seat numbers.
-    :param flight_id: str - string containing the flight identifier.
-    :return: generator - generator that yields 12 character long ticket codes.
+    Parameters:
+        seat_numbers (list[str]): A list of seat numbers.
+        flight_id (str): A string containing the flight identifier.
+
+    Returns:
+        generator: A generator that yields 12 character long ticket codes.
 
     """
 

exercises/concept/tisbury-treasure-hunt/.meta/exemplar.py

@@ -4,8 +4,11 @@
 def get_coordinate(record):
     """Return coordinate value from a tuple containing the treasure name, and treasure coordinate.
 
-    :param record: tuple - with a (treasure, coordinate) pair.
-    :return: str - the extracted map coordinate.
+    Parameters:
+        record (tuple): A (treasure, coordinate) pair.
+
+    Returns:
+        str: The extracted map coordinate.
     """
 
     return record[1]
@@ -14,8 +17,11 @@ def get_coordinate(record):
 def convert_coordinate(coordinate):
     """Split the given coordinate into tuple containing its individual components.
 
-    :param coordinate: str - a string map coordinate
-    :return: tuple - the string coordinate split into its individual components.
+    Parameters:
+        coordinate (str): A string map coordinate.
+
+    Returns:
+        tuple: The string coordinate split into its individual components.
     """
 
     return tuple(coordinate)
@@ -24,9 +30,12 @@ def convert_coordinate(coordinate):
 def compare_records(azara_record, rui_record):
     """Compare two record types and determine if their coordinates match.
 
-    :param azara_record: tuple - a (treasure, coordinate) pair.
-    :param rui_record: tuple - a (location, tuple(coordinate_1, coordinate_2), quadrant) trio.
-    :return: bool - do the coordinates match?
+    Parameters:
+        azara_record (tuple):  A (treasure, coordinate) pair.
+        rui_record (tuple): A (location, tuple(coordinate_1, coordinate_2), quadrant) trio.
+
+    Returns:
+        bool: Do the coordinates match?
     """
 
     return convert_coordinate(azara_record[1]) in rui_record
@@ -35,9 +44,12 @@ def compare_records(azara_record, rui_record):
 def create_record(azara_record, rui_record):
     """Combine the two record types (if possible) and create a combined record group.
 
-    :param azara_record: tuple - a (treasure, coordinate) pair.
-    :param rui_record: tuple - a (location, coordinate, quadrant) trio.
-    :return: tuple or str - the combined record (if compatible), or the string "not a match" (if incompatible).
+    Parameters:
+        azara_record (tuple): A (treasure, coordinate) pair.
+        rui_record (tuple): A (location, coordinate, quadrant) trio.
+
+    Returns:
+        tuple or str: The combined record (if compatible), or the string "not a match" (if incompatible).
     """
 
     result = "not a match"
@@ -51,12 +63,16 @@ def create_record(azara_record, rui_record):
 def clean_up(combined_record_group):
     """Clean up a combined record group into a multi-line string of single records.
 
-    :param combined_record_group: tuple - everything from both participants.
-    :return: str - everything "cleaned", excess coordinates and information are removed.
+    Parameters:
+        combined_record_group (tuple): Everything from both participants.
+
+    Returns:
+        str: Everything "cleaned", excess coordinates and information are removed.
 
-    The return statement should be a multi-lined string with items separated by newlines.
+    Note:
+        The return statement is a multi-lined string with items separated by newlines.
+        (see HINTS.md for an example).
 
-    (see HINTS.md for an example).
     """
 
     report = ""