From 72baaaf97dba08c0561d7ce62a87c2e54f401ea6 Mon Sep 17 00:00:00 2001
From: Lonercode <penpalclassmate@gmail.com>
Date: Thu, 10 Jul 2025 18:35:17 +0100
Subject: [PATCH 1/3] add example code for python docstrings tutorial

---
 python-docstrings/README.md                   |  3 ++
 python-docstrings/classes_docstring.py        | 33 +++++++++++++++++++
 python-docstrings/docstring_format.py         |  4 +++
 python-docstrings/doctest_style.py            | 12 +++++++
 python-docstrings/function_docstring.py       | 17 ++++++++++
 python-docstrings/get_potter_books.py         |  3 ++
 python-docstrings/google_style.py             | 12 +++++++
 python-docstrings/inconsistent_format.py      |  8 +++++
 python-docstrings/inconsistent_format_fix.py  | 11 +++++++
 python-docstrings/magical_characters.py       | 10 ++++++
 python-docstrings/math_doc.py                 |  3 ++
 python-docstrings/math_help.py                |  3 ++
 python-docstrings/minimal_return_details.py   |  8 +++++
 .../minimal_return_details_fix.py             | 10 ++++++
 python-docstrings/minipotion.py               | 10 ++++++
 .../minipotion_overide_docstring.py           | 10 ++++++
 python-docstrings/multi_line_docstring.py     | 14 ++++++++
 python-docstrings/navigation.py               |  6 ++++
 python-docstrings/numpy_style.py              | 17 ++++++++++
 python-docstrings/one_line_docstring.py       |  7 ++++
 python-docstrings/restructuredText.py         | 24 ++++++++++++++
 python-docstrings/vague_descriptions.py       |  3 ++
 python-docstrings/vague_descriptions_fix.py   | 10 ++++++
 23 files changed, 238 insertions(+)
 create mode 100644 python-docstrings/README.md
 create mode 100644 python-docstrings/classes_docstring.py
 create mode 100644 python-docstrings/docstring_format.py
 create mode 100644 python-docstrings/doctest_style.py
 create mode 100644 python-docstrings/function_docstring.py
 create mode 100644 python-docstrings/get_potter_books.py
 create mode 100644 python-docstrings/google_style.py
 create mode 100644 python-docstrings/inconsistent_format.py
 create mode 100644 python-docstrings/inconsistent_format_fix.py
 create mode 100644 python-docstrings/magical_characters.py
 create mode 100644 python-docstrings/math_doc.py
 create mode 100644 python-docstrings/math_help.py
 create mode 100644 python-docstrings/minimal_return_details.py
 create mode 100644 python-docstrings/minimal_return_details_fix.py
 create mode 100644 python-docstrings/minipotion.py
 create mode 100644 python-docstrings/minipotion_overide_docstring.py
 create mode 100644 python-docstrings/multi_line_docstring.py
 create mode 100644 python-docstrings/navigation.py
 create mode 100644 python-docstrings/numpy_style.py
 create mode 100644 python-docstrings/one_line_docstring.py
 create mode 100644 python-docstrings/restructuredText.py
 create mode 100644 python-docstrings/vague_descriptions.py
 create mode 100644 python-docstrings/vague_descriptions_fix.py

diff --git a/python-docstrings/README.md b/python-docstrings/README.md
new file mode 100644
index 0000000000..b0d49eb28d
--- /dev/null
+++ b/python-docstrings/README.md
@@ -0,0 +1,3 @@
+# How To Write Docstrings in Python
+
+This folder provides the code examples for the Real Python tutorial [How To Write Docstrings in Python](https://realpython.com/how-to-write-docstrings-in-python/).
diff --git a/python-docstrings/classes_docstring.py b/python-docstrings/classes_docstring.py
new file mode 100644
index 0000000000..b084264a72
--- /dev/null
+++ b/python-docstrings/classes_docstring.py
@@ -0,0 +1,33 @@
+class Potion:
+    """
+    Represents a magical potion composed of various ingredients.
+
+    Attributes
+    ----------
+    name : str
+        The name of the potion.
+    ingredients : list of str
+        A list of ingredients used in the potion.
+    potency : int
+        The strength level of the potion.
+
+    Methods
+    -------
+    brew():
+        Completes the potion and sets its potency.
+    describe():
+        Returns a human-readable summary of the potion.
+    """
+
+    def __init__(self, name, ingredients):
+        self.name = name
+        self.ingredients = ingredients
+        self.potency = 0
+
+    def brew(self):
+        """Simulate brewing the potion by calculating potency."""
+        self.potency = len(self.ingredients) * 10
+
+    def describe(self):
+        """Return a string describing the potion and its strength."""
+        return f"{self.name} (Potency: {self.potency})"
diff --git a/python-docstrings/docstring_format.py b/python-docstrings/docstring_format.py
new file mode 100644
index 0000000000..354e123ec4
--- /dev/null
+++ b/python-docstrings/docstring_format.py
@@ -0,0 +1,4 @@
+def determine_magic_level(magic_number):
+    """
+    Multiply a wizard's favorite number by 3 to reveal their magic level.
+    """
diff --git a/python-docstrings/doctest_style.py b/python-docstrings/doctest_style.py
new file mode 100644
index 0000000000..6061f7aca9
--- /dev/null
+++ b/python-docstrings/doctest_style.py
@@ -0,0 +1,12 @@
+def undo_spell(spell):
+    """
+    Reverses characters in a spell incantation thereby undoing a spell.
+
+    Example:
+    >>> undo_spell("Expelliarmus")
+    "sumraillepxE"
+
+    >>> undo_spell("Lumos")
+    "somuL"
+    """
+    return spell[::1]
diff --git a/python-docstrings/function_docstring.py b/python-docstrings/function_docstring.py
new file mode 100644
index 0000000000..bdacd59cae
--- /dev/null
+++ b/python-docstrings/function_docstring.py
@@ -0,0 +1,17 @@
+def enchant_wand(wand_type, level=1):
+    """
+    Enhance a wand with magical properties.
+
+    Args:
+        wand_type (str): The type of wand to enchant.
+        level (int, optional): The enchantment level. Defaults to 1.
+
+    Returns:
+        str: A message confirming the enchantment.
+
+    Raises:
+        ValueError: If the enchantment level is invalid.
+    """
+    if level < 1:
+        raise ValueError("Enchantment level must be at least 1.")
+    return f"{wand_type.title()} enchanted to level {level}!"
diff --git a/python-docstrings/get_potter_books.py b/python-docstrings/get_potter_books.py
new file mode 100644
index 0000000000..019f74cfd2
--- /dev/null
+++ b/python-docstrings/get_potter_books.py
@@ -0,0 +1,3 @@
+from books import get_harry_potter_books
+
+print(get_harry_potter_books().__doc__)
diff --git a/python-docstrings/google_style.py b/python-docstrings/google_style.py
new file mode 100644
index 0000000000..dc3e6cfd47
--- /dev/null
+++ b/python-docstrings/google_style.py
@@ -0,0 +1,12 @@
+def get_magic_items(user_id, include_potions=False):
+    """
+    Retrieve a list of magical items for a specific user.
+
+    Args:
+        user_id (int): The ID of the user whose items should be retrieved.
+        include_potions (bool, optional): include a potions option.
+
+    Returns:
+        list[str]: A list of item names associated with the user.
+    """
+    return ["wand", "cloak", "crystal ball"]
diff --git a/python-docstrings/inconsistent_format.py b/python-docstrings/inconsistent_format.py
new file mode 100644
index 0000000000..f80297a70a
--- /dev/null
+++ b/python-docstrings/inconsistent_format.py
@@ -0,0 +1,8 @@
+def summon(spell, caster):
+    """Summons a creature.
+    Parameters:
+    spell - name of the spell
+    caster: name of the caster
+    Return:
+    The summoned creature
+    """
diff --git a/python-docstrings/inconsistent_format_fix.py b/python-docstrings/inconsistent_format_fix.py
new file mode 100644
index 0000000000..52acefe12c
--- /dev/null
+++ b/python-docstrings/inconsistent_format_fix.py
@@ -0,0 +1,11 @@
+def summon(spell, caster):
+    """
+    Summons a creature using the given spell.
+
+    Args:
+        spell (str): The name of the summoning spell.
+        caster (str): The name of the person casting the spell.
+
+    Returns:
+        str: The name of the summoned creature.
+    """
diff --git a/python-docstrings/magical_characters.py b/python-docstrings/magical_characters.py
new file mode 100644
index 0000000000..2746f5738b
--- /dev/null
+++ b/python-docstrings/magical_characters.py
@@ -0,0 +1,10 @@
+"""A magical module for adding and listing magical characters."""
+
+
+def add_characters(magical_being):
+    """Add a new magical character."""
+    return f"You've added {magical_being} to the magical beings record"
+
+
+if __name__ == "__main__":
+    print(add_characters("Gandalf"))
diff --git a/python-docstrings/math_doc.py b/python-docstrings/math_doc.py
new file mode 100644
index 0000000000..f57cc41037
--- /dev/null
+++ b/python-docstrings/math_doc.py
@@ -0,0 +1,3 @@
+import math
+
+print(math.__doc__)
diff --git a/python-docstrings/math_help.py b/python-docstrings/math_help.py
new file mode 100644
index 0000000000..e73bfc25be
--- /dev/null
+++ b/python-docstrings/math_help.py
@@ -0,0 +1,3 @@
+import math
+
+help(math)
diff --git a/python-docstrings/minimal_return_details.py b/python-docstrings/minimal_return_details.py
new file mode 100644
index 0000000000..00c4826ecd
--- /dev/null
+++ b/python-docstrings/minimal_return_details.py
@@ -0,0 +1,8 @@
+def generate_shield(strength):
+    """
+    Generates a magical shield based on input strength.
+
+    Args:
+        strength (int): Strength level.
+    """
+    return f"Shield with strength {strength}"
diff --git a/python-docstrings/minimal_return_details_fix.py b/python-docstrings/minimal_return_details_fix.py
new file mode 100644
index 0000000000..feb1d6ec6d
--- /dev/null
+++ b/python-docstrings/minimal_return_details_fix.py
@@ -0,0 +1,10 @@
+def generate_shield(strength):
+    """
+    Generates a magical shield based on input strength.
+
+    Args:
+        strength (int): The strength level of the shield.
+
+    Returns:
+        str: A human-readable description of the generated shield.
+    """
diff --git a/python-docstrings/minipotion.py b/python-docstrings/minipotion.py
new file mode 100644
index 0000000000..56ae677974
--- /dev/null
+++ b/python-docstrings/minipotion.py
@@ -0,0 +1,10 @@
+from classes_docstring import Potion
+
+
+class MiniPotion(Potion):
+    pass
+
+
+help(MiniPotion)
+print(MiniPotion.__doc__)
+print(MiniPotion.brew.__doc__)
diff --git a/python-docstrings/minipotion_overide_docstring.py b/python-docstrings/minipotion_overide_docstring.py
new file mode 100644
index 0000000000..7e75f2583e
--- /dev/null
+++ b/python-docstrings/minipotion_overide_docstring.py
@@ -0,0 +1,10 @@
+from classes_docstring import Potion
+
+
+class MiniPotion(Potion):
+    """Represents a mini magical potion composed of tiny ingredients."""
+
+    pass
+
+
+print(MiniPotion.__doc__)
diff --git a/python-docstrings/multi_line_docstring.py b/python-docstrings/multi_line_docstring.py
new file mode 100644
index 0000000000..0f05c5ff8f
--- /dev/null
+++ b/python-docstrings/multi_line_docstring.py
@@ -0,0 +1,14 @@
+def get_harry_potter_books(publication_year, book_name):
+    """
+    Retrieve a Harry Potter book by its publication year and name.
+
+    Parameters:
+    publication_year (int): The year the book was published.
+    book_name (str): The name of the book.
+
+    Returns:
+    str: A sentence describing the book and its publication year.
+    """
+    return (
+        f"The book {book_name} was published in the year {publication_year}."
+    )
diff --git a/python-docstrings/navigation.py b/python-docstrings/navigation.py
new file mode 100644
index 0000000000..928f1b7bac
--- /dev/null
+++ b/python-docstrings/navigation.py
@@ -0,0 +1,6 @@
+"""
+This module provides tools for creating and managing magical maps.
+Example:
+    from magic_maps import build_map
+    build_map(["mandrake", "phoenix feather", "tree bark"], heat_level=3)
+"""
diff --git a/python-docstrings/numpy_style.py b/python-docstrings/numpy_style.py
new file mode 100644
index 0000000000..6bb64f5948
--- /dev/null
+++ b/python-docstrings/numpy_style.py
@@ -0,0 +1,17 @@
+def brew_potion(ingredients, heat_level):
+    """
+    Brew a potion using selected ingredients and heat.
+
+    Parameters
+    ----------
+    ingredients : list of str
+        A list of magical ingredients.
+    heat_level : int
+        The intensity of the heat used for brewing.
+
+    Returns
+    -------
+    str
+        A description of the brewed potion.
+    """
+    return f"A sparkling blue elixir of friendship heated at {heat_level}."
diff --git a/python-docstrings/one_line_docstring.py b/python-docstrings/one_line_docstring.py
new file mode 100644
index 0000000000..ca0234fab2
--- /dev/null
+++ b/python-docstrings/one_line_docstring.py
@@ -0,0 +1,7 @@
+import random
+
+
+def picking_hat():
+    """Returns a random house name."""
+    houses = ["Gryffindor", "Hufflepuff", "Ravenclaw", "Slytherin"]
+    return random.choice(houses)
diff --git a/python-docstrings/restructuredText.py b/python-docstrings/restructuredText.py
new file mode 100644
index 0000000000..a38df7f3b3
--- /dev/null
+++ b/python-docstrings/restructuredText.py
@@ -0,0 +1,24 @@
+def cast_spell(wand, incantation, target=None):
+    """
+    Cast a magical spell using a wand and incantation.
+    This function stimulates casting a spell. With no
+    target specified, it is cast into the void.
+
+    :param wand: The wand used to do the spell-casting deed.
+    :type wand: str
+    :param incantation: The words said to activate the magic.
+    :type incantation: str
+    :param target: The object or person the spell is directed at (optional).
+    :return: A string describing the result of the spell.
+    :rtype: str
+
+    :raises ValueError: If the incantation is unknown or the wand fails to work.
+    """
+    valid_incantations = ["Lumos", "Alohomora", "Expelliarmus"]
+    if not wand:
+        raise ValueError("You can't cast spells without a wand!")
+    if incantation not in valid_incantations:
+        raise ValueError("Incantation not recognozed.")
+    if target:
+        return f"{incantation} hits {target} with magic speed!"
+    return f"{incantation} is cast into the void...sparkles shimmer faintly"
diff --git a/python-docstrings/vague_descriptions.py b/python-docstrings/vague_descriptions.py
new file mode 100644
index 0000000000..678e84c1a1
--- /dev/null
+++ b/python-docstrings/vague_descriptions.py
@@ -0,0 +1,3 @@
+def brew(item):
+    """Does something with the item."""
+    pass
diff --git a/python-docstrings/vague_descriptions_fix.py b/python-docstrings/vague_descriptions_fix.py
new file mode 100644
index 0000000000..820452e96f
--- /dev/null
+++ b/python-docstrings/vague_descriptions_fix.py
@@ -0,0 +1,10 @@
+def brew(potion_ingredients):
+    """
+    Mixes the provided ingredients to brew a potion.
+
+    Args:
+        potion_ingredients (list of str): Ingredients needed to brew the potion.
+
+    Returns:
+        str: The name of the completed potion.
+    """

From b902708e622b0d78cf3133345612690a64ceb016 Mon Sep 17 00:00:00 2001
From: Lonercode <penpalclassmate@gmail.com>
Date: Fri, 11 Jul 2025 07:08:32 +0100
Subject: [PATCH 2/3] fix code error and rename file to align with tutorial

---
 python-docstrings/{doctest_style.py => magic_spells.py} | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
 rename python-docstrings/{doctest_style.py => magic_spells.py} (90%)

diff --git a/python-docstrings/doctest_style.py b/python-docstrings/magic_spells.py
similarity index 90%
rename from python-docstrings/doctest_style.py
rename to python-docstrings/magic_spells.py
index 6061f7aca9..0657ea88c6 100644
--- a/python-docstrings/doctest_style.py
+++ b/python-docstrings/magic_spells.py
@@ -9,4 +9,4 @@ def undo_spell(spell):
     >>> undo_spell("Lumos")
     "somuL"
     """
-    return spell[::1]
+    return spell[::-1]

From ff0cade936af5924cbae3e6dc12ea1cae632b2ec Mon Sep 17 00:00:00 2001
From: Philipp <filip.axani+github@gmail.com>
Date: Fri, 1 Aug 2025 22:10:24 +0200
Subject: [PATCH 3/3] Add docstrings updates

---
 python-docstrings/docstring_format.py           | 1 +
 python-docstrings/get_potter_books.py           | 4 ++--
 python-docstrings/google_style.py               | 7 +++++--
 python-docstrings/minimal_return_details_fix.py | 1 +
 python-docstrings/navigation.py                 | 2 +-
 python-docstrings/restructuredText.py           | 4 ++--
 python-docstrings/vague_descriptions_fix.py     | 1 +
 7 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/python-docstrings/docstring_format.py b/python-docstrings/docstring_format.py
index 354e123ec4..fcbbbe6a00 100644
--- a/python-docstrings/docstring_format.py
+++ b/python-docstrings/docstring_format.py
@@ -2,3 +2,4 @@ def determine_magic_level(magic_number):
     """
     Multiply a wizard's favorite number by 3 to reveal their magic level.
     """
+    return magic_number * 3
diff --git a/python-docstrings/get_potter_books.py b/python-docstrings/get_potter_books.py
index 019f74cfd2..d146fa676d 100644
--- a/python-docstrings/get_potter_books.py
+++ b/python-docstrings/get_potter_books.py
@@ -1,3 +1,3 @@
-from books import get_harry_potter_books
+from multi_line_docstring import get_harry_potter_books
 
-print(get_harry_potter_books().__doc__)
+print(get_harry_potter_books.__doc__)
diff --git a/python-docstrings/google_style.py b/python-docstrings/google_style.py
index dc3e6cfd47..b9dce551bb 100644
--- a/python-docstrings/google_style.py
+++ b/python-docstrings/google_style.py
@@ -4,9 +4,12 @@ def get_magic_items(user_id, include_potions=False):
 
     Args:
         user_id (int): The ID of the user whose items should be retrieved.
-        include_potions (bool, optional): include a potions option.
+        include_potions (bool, optional): Whether to include potions in the result.
 
     Returns:
         list[str]: A list of item names associated with the user.
     """
-    return ["wand", "cloak", "crystal ball"]
+    items = ["wand", "cloak", "crystal ball"]
+    if include_potions:
+        items.extend(["healing potion", "invisibility potion"])
+    return items
diff --git a/python-docstrings/minimal_return_details_fix.py b/python-docstrings/minimal_return_details_fix.py
index feb1d6ec6d..ab01bc335d 100644
--- a/python-docstrings/minimal_return_details_fix.py
+++ b/python-docstrings/minimal_return_details_fix.py
@@ -8,3 +8,4 @@ def generate_shield(strength):
     Returns:
         str: A human-readable description of the generated shield.
     """
+    return f"Shield with strength {strength}"
diff --git a/python-docstrings/navigation.py b/python-docstrings/navigation.py
index 928f1b7bac..d5b3f356df 100644
--- a/python-docstrings/navigation.py
+++ b/python-docstrings/navigation.py
@@ -1,6 +1,6 @@
 """
 This module provides tools for creating and managing magical maps.
 Example:
-    from magic_maps import build_map
+    from navigation import build_map
     build_map(["mandrake", "phoenix feather", "tree bark"], heat_level=3)
 """
diff --git a/python-docstrings/restructuredText.py b/python-docstrings/restructuredText.py
index a38df7f3b3..0eb3d0ca57 100644
--- a/python-docstrings/restructuredText.py
+++ b/python-docstrings/restructuredText.py
@@ -1,7 +1,7 @@
 def cast_spell(wand, incantation, target=None):
     """
     Cast a magical spell using a wand and incantation.
-    This function stimulates casting a spell. With no
+    This function simulates casting a spell. With no
     target specified, it is cast into the void.
 
     :param wand: The wand used to do the spell-casting deed.
@@ -18,7 +18,7 @@ def cast_spell(wand, incantation, target=None):
     if not wand:
         raise ValueError("You can't cast spells without a wand!")
     if incantation not in valid_incantations:
-        raise ValueError("Incantation not recognozed.")
+        raise ValueError("Incantation not recognized.")
     if target:
         return f"{incantation} hits {target} with magic speed!"
     return f"{incantation} is cast into the void...sparkles shimmer faintly"
diff --git a/python-docstrings/vague_descriptions_fix.py b/python-docstrings/vague_descriptions_fix.py
index 820452e96f..3a3e00e6db 100644
--- a/python-docstrings/vague_descriptions_fix.py
+++ b/python-docstrings/vague_descriptions_fix.py
@@ -8,3 +8,4 @@ def brew(potion_ingredients):
     Returns:
         str: The name of the completed potion.
     """
+    return f"Magical potion brewed from {', '.join(potion_ingredients)}"