add example code for python docstrings tutorial

Author: Lonercode

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/).

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})"

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.
+    """

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]

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}!"

python-docstrings/get_potter_books.py

@@ -0,0 +1,3 @@
+from books import get_harry_potter_books
+
+print(get_harry_potter_books().__doc__)

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"]

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
+    """

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.
+    """

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"))