In this challenge, you will practice writing **docstrings** for Python functions. Docstrings are essential for documenting what a function does, its parameters, and its return value. Your task is to read each function and write a clear, concise docstring that explains its purpose, describes its parameters, and specifies what it returns. This exercise will help you develop the habit of documenting your code for yourself and others.


import unittest
import user_code
import ast
import re   
import importlib
import ast
import inspect
import sys
import types
import io
from contextlib import redirect_stdout
import unittest

class TestTask(unittest.TestCase):
    def _get_function(self, func_name):
        import user_code
        importlib.reload(user_code)
        return getattr(user_code, func_name, None)

    def _get_docstring(self, func):
        return inspect.getdoc(func)

    def test_add_numbers_docstring(self):
        func = self._get_function('add_numbers')
        docstring = self._get_docstring(func)
        has_summary = docstring is not None and "add two numbers" in docstring.lower()
        has_param_a = docstring is not None and ("a (int or float)" in docstring or "a (float or int)" in docstring)
        has_param_b = docstring is not None and ("b (int or float)" in docstring or "b (float or int)" in docstring)
        has_returns = docstring is not None and ("returns" in docstring.lower())
        _dynamic_test(
            self,
            has_summary and has_param_a and has_param_b and has_returns,
            "add_numbers docstring includes summary, parameter descriptions, and return value.",
            f"Docstring for add_numbers missing required parts: {docstring}",
        )

    def test_greet_user_docstring(self):
        func = self._get_function('greet_user')
        docstring = self._get_docstring(func)
        has_summary = docstring is not None and "greeting message" in docstring.lower()
        has_param_name = docstring is not None and ("name (str)" in docstring)
        has_param_greeting = docstring is not None and ("greeting (str" in docstring.lower())
        has_returns = docstring is not None and ("returns" in docstring.lower())
        _dynamic_test(
            self,
            has_summary and has_param_name and has_param_greeting and has_returns,
            "greet_user docstring includes summary, parameter descriptions, and return value.",
            f"Docstring for greet_user missing required parts: {docstring}",
        )

    def test_find_max_docstring(self):
        func = self._get_function('find_max')
        docstring = self._get_docstring(func)
        has_summary = docstring is not None and ("find the maximum" in docstring.lower() or "maximum value" in docstring.lower())
        has_param_numbers = docstring is not None and ("numbers (list of int or float)" in docstring or "numbers (list of float or int)" in docstring)
        has_returns = docstring is not None and ("returns" in docstring.lower())
        _dynamic_test(
            self,
            has_summary and has_param_numbers and has_returns,
            "find_max docstring includes summary, parameter descriptions, and return value.",
            f"Docstring for find_max missing required parts: {docstring}",
        )

def _dynamic_test(test_case, condition, success_message, failure_message):
    if condition:
        test_case._testMethodName = success_message
        test_case.assertTrue(True, success_message)
    else:
        test_case._testMethodName = failure_message
        test_case.fail(failure_message)

def normalize_text(text):
    text = text.lower()
    text = re.sub(r"\s{2,}", " ", text)
    text = re.sub(r"\s*([,:?])\s*", r"\1 ", text)
    return text.strip()

def change_var(code: str, var_name: str, value: str) -> str:
    tree = ast.parse(code)
    lines = code.splitlines()
    for i, node in enumerate(tree.body):
        if isinstance(node, ast.Assign):
            for target in node.targets:
                if isinstance(target, ast.Name) and target.id == var_name:
                    start_line = node.lineno - 1
                    line = lines[start_line]
                    indent = ' ' * (len(line) - len(line.lstrip()))
                    lines[start_line] = f"{indent}{var_name} = {value}"
                    next_line = len(lines)
                    for next_node in tree.body[i+1:]:
                        if hasattr(next_node, 'lineno'):
                            next_line = next_node.lineno - 1
                            break
                    if next_line > start_line + 1:
                        lines[start_line+1:next_line] = []
                    
                    return '\\n'.join(lines)
    return code

if __name__ == "__main__":
    unittest.main()


test_main.py

Master the principles of writing clean, maintainable, and efficient Python code. Learn to identify code smells, apply refactoring techniques, and adopt best practices for code quality. Practice your skills with hands-on tasks designed for those familiar with basic Python syntax.

Explore the fundamental concepts of code quality, why it matters, and how to recognize poor code in Python.

Delve into practical refactoring methods to enhance Python code structure and eliminate code smells.

Adopt Pythonic conventions and idioms to write elegant, efficient, and maintainable code.

Learn strategies for maintaining code quality over time, including documentation, testing, and code reviews.

Challenge: Write Docstrings

Solution

Awesome!

Challenge: Write Docstrings

Solution