DEV Community: Jon Ibañez del campo

How to Automate Code Documentation with the Claude API and Python

Jon Ibañez del campo — Sun, 03 May 2026 10:46:21 +0000

You just finished a statistics assignment.

The code works. The results are correct. Then you read the submission requirements and see it: "all functions must be properly documented."

You have twenty functions. No docstrings. Twenty minutes left.

That's the problem this tutorial solves. A Python script that takes any function, sends it to Claude, and gets back a complete docstring — parameters, return values, exceptions, and a usage example. All automatically.

This is part three of a series on building real tools with the Claude API. Parts one and two cover the basics and a code review chatbot. This one is immediately useful.

What We're Building

A script that does one thing well: takes a Python function as input and returns a complete, properly formatted docstring.

Input:  def calculate_pca(data, n_components):
Output: """
        Performs Principal Component Analysis on the input dataset.

        Args:
            data: Input matrix of shape (n_samples, n_features).
            n_components: Number of principal components to return.

        Returns:
            Transformed data of shape (n_samples, n_components).

        Raises:
            ValueError: If n_components exceeds the number of features.

        Example:
            result = calculate_pca(X, n_components=2)
        """

Setup

Same environment from the previous tutorials. If you're starting fresh:

mkdir doc-generator
cd doc-generator
python -m venv venv

Activate:

# Mac/Linux
source venv/bin/activate

# Windows
venv\Scripts\activate

Install:

pip install anthropic python-dotenv

Create your .env:

ANTHROPIC_API_KEY=your-key-here

The Core Function

The idea is simple: send Claude your function and ask for a docstring back. The system prompt does most of the work.

from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()
client = Anthropic()

def generate_docstring(function_code: str) -> str:
    """Generate a docstring for a given Python function."""

    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        system=(
            "You are a Python documentation assistant. "
            "When given a Python function, return only a Google-style docstring for it. "
            "Include: a one-line summary, Args, Returns, Raises (if applicable), and Example. "
            "Return only the docstring text inside triple quotes. No explanation, no extra text."
        ),
        messages=[
            {"role": "user", "content": function_code}
        ]
    )

    return response.content[0].text

The key instruction is "Return only the docstring text inside triple quotes. No explanation, no extra text." Without that, Claude adds commentary around the docstring and you'd need to parse it out.

Testing It

sample_function = """
def calculate_mean(values):
    total = sum(values)
    return total / len(values)
"""

docstring = generate_docstring(sample_function)
print(docstring)

Output:

"""
Calculate the arithmetic mean of a list of values.

Args:
    values: A list of numeric values.

Returns:
    The arithmetic mean as a float.

Raises:
    ZeroDivisionError: If the input list is empty.
    TypeError: If the list contains non-numeric values.

Example:
    mean = calculate_mean([1, 2, 3, 4, 5])
    # Returns: 3.0
"""

Claude infers the edge cases — empty list, wrong types — even though the original function doesn't handle them. That's useful: it documents what the function should handle, not just what it does.

Inserting the Docstring Into the Function

Getting the docstring is half the job. Inserting it automatically into the original function is the other half.

def insert_docstring(function_code: str, docstring: str) -> str:
    """Insert a generated docstring into a function definition."""
    lines = function_code.split("\n")

    # Find the line with the function definition
    for i, line in enumerate(lines):
        if line.strip().startswith("def "):
            # Insert the docstring after the def line
            indent = "    "  # Standard 4-space indent
            docstring_lines = docstring.strip().split("\n")
            indented = [indent + line for line in docstring_lines]
            lines = lines[:i+1] + indented + lines[i+1:]
            break

    return "\n".join(lines)

Test it:

sample_function = """
def calculate_mean(values):
    total = sum(values)
    return total / len(values)
"""

docstring = generate_docstring(sample_function)
documented = insert_docstring(sample_function, docstring)
print(documented)

Output:

def calculate_mean(values):
    """
    Calculate the arithmetic mean of a list of values.

    Args:
        values: A list of numeric values.

    Returns:
        The arithmetic mean as a float.

    Raises:
        ZeroDivisionError: If the input list is empty.
        TypeError: If the list contains non-numeric values.

    Example:
        mean = calculate_mean([1, 2, 3, 4, 5])
        # Returns: 3.0
    """
    total = sum(values)
    return total / len(values)

Processing an Entire File

One function at a time works for quick fixes. For a full assignment with twenty functions, you want to process the whole file at once.

import re

def extract_functions(file_content: str) -> list[str]:
    """Extract all function definitions from a Python file."""
    pattern = r"(def \w+\(.*?\):(?:\n(?:    .+|\s*))*)"
    return re.findall(pattern, file_content, re.MULTILINE)

def document_file(input_path: str, output_path: str) -> None:
    """Read a Python file, document all functions, and save the result."""
    with open(input_path, "r") as f:
        content = f.read()

    functions = extract_functions(content)
    print(f"Found {len(functions)} functions. Generating docstrings...\n")

    documented_content = content

    for i, function in enumerate(functions):
        print(f"Processing function {i+1}/{len(functions)}...")

        # Skip functions that already have docstrings
        if '"""' in function or "'''" in function:
            print(f"  Already documented, skipping.")
            continue

        docstring = generate_docstring(function)
        documented_function = insert_docstring(function, docstring)
        documented_content = documented_content.replace(function, documented_function)

    with open(output_path, "w") as f:
        f.write(documented_content)

    print(f"\nDone. Documented file saved to: {output_path}")

Usage:

document_file("statistics_assignment.py", "statistics_assignment_documented.py")

It reads the original file, skips functions that already have docstrings, generates the missing ones, and saves a new file. The original stays untouched.

The Full Script

import re
from dotenv import load_dotenv
from anthropic import Anthropic, APIError, RateLimitError, APIConnectionError

load_dotenv()
client = Anthropic()

def generate_docstring(function_code: str) -> str:
    try:
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            system=(
                "You are a Python documentation assistant. "
                "When given a Python function, return only a Google-style docstring for it. "
                "Include: a one-line summary, Args, Returns, Raises (if applicable), and Example. "
                "Return only the docstring text inside triple quotes. No explanation, no extra text."
            ),
            messages=[{"role": "user", "content": function_code}]
        )
        return response.content[0].text

    except RateLimitError:
        return '"""Rate limit reached. Document this function manually."""'
    except APIConnectionError:
        return '"""Connection failed. Document this function manually."""'
    except APIError as e:
        return f'"""API error {e.status_code}."""'

def insert_docstring(function_code: str, docstring: str) -> str:
    lines = function_code.split("\n")
    for i, line in enumerate(lines):
        if line.strip().startswith("def "):
            indent = "    "
            docstring_lines = docstring.strip().split("\n")
            indented = [indent + line for line in docstring_lines]
            lines = lines[:i+1] + indented + lines[i+1:]
            break
    return "\n".join(lines)

def extract_functions(file_content: str) -> list[str]:
    pattern = r"(def \w+\(.*?\):(?:\n(?:    .+|\s*))*)"
    return re.findall(pattern, file_content, re.MULTILINE)

def document_file(input_path: str, output_path: str) -> None:
    with open(input_path, "r") as f:
        content = f.read()

    functions = extract_functions(content)
    print(f"Found {len(functions)} functions. Generating docstrings...\n")

    documented_content = content

    for i, function in enumerate(functions):
        print(f"Processing function {i+1}/{len(functions)}...")

        if '"""' in function or "'''" in function:
            print("  Already documented, skipping.")
            continue

        docstring = generate_docstring(function)
        documented_function = insert_docstring(function, docstring)
        documented_content = documented_content.replace(function, documented_function)

    with open(output_path, "w") as f:
        f.write(documented_content)

    print(f"\nDone. Saved to: {output_path}")

if __name__ == "__main__":
    document_file("your_file.py", "your_file_documented.py")

Common Mistakes

The system prompt needs to be strict
If you don't tell Claude to return only the docstring, it adds sentences like "Here's the docstring for your function:" — and that ends up in your code. The instruction "No explanation, no extra text" is not optional.

Functions with existing docstrings
The script checks for """ before calling the API. Remove that check and it overwrites documentation you already wrote.

Large files hit rate limits
If you have a file with fifty functions, Claude will process them fast enough to trigger rate limiting. Add a small delay between calls:

import time
time.sleep(0.5)  # Half a second between calls

What's Next

The script handles the common case well. A few natural extensions if you want to take it further:

Support for NumPy-style docstrings instead of Google-style — change the system prompt and the format changes with it.

A command-line interface so you can run python doc_generator.py myfile.py directly from the terminal without editing the script.

Batch processing for entire directories — walk through a project folder and document every .py file at once.

Full Claude API documentation at platform.claude.com/docs.

# One function. One API call. One docstring.

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="Return only a Google-style docstring. No extra text.",
    messages=[{"role": "user", "content": your_function_code}]
)

print(response.content[0].text)

How to Build a Code Assistant Chatbot with the Claude API and Python

Jon Ibañez del campo — Sun, 03 May 2026 10:36:23 +0000

You already use Claude every day.

For debugging Python. For understanding C++ errors. For summarizing papers before an exam. At some point you stop going to the browser and start wondering — can I just have this inside my terminal, in my workflow, without switching windows every five minutes?

Yes. That's what this tutorial builds.

A terminal chatbot that lives in your code environment. You paste code, ask questions, get answers, and keep the conversation going — all without leaving your terminal.

This is part two of a series. If you haven't set up the Claude API yet, start with part one.

What We're Building

A terminal chatbot with three behaviors:

You paste code and it reviews it — finds bugs, suggests improvements, explains what's happening
You ask follow-up questions and it remembers the full context of what you shared
You type exit and it stops

No UI. No framework. Just Python and the Claude API.

Setup

Same as part one. If you already have the environment ready, skip this.

mkdir code-assistant
cd code-assistant
python -m venv venv

Activate:

# Mac/Linux
source venv/bin/activate

# Windows
venv\Scripts\activate

Install dependencies:

pip install anthropic python-dotenv

Create your .env file:

ANTHROPIC_API_KEY=your-key-here

The Core: A Loop That Remembers

The key difference between a single API call and a chatbot is memory.

In part one, every call was independent. Here, we keep a history list and pass it on every request — so Claude always knows what was said before.

from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()
client = Anthropic()

history = []

def chat(user_message: str) -> str:
    history.append({"role": "user", "content": user_message})

    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        system=(
            "You are a code review assistant. "
            "When the user shares code, review it: identify bugs, explain what each part does, "
            "and suggest improvements. Be direct and specific. "
            "When the user asks follow-up questions, refer back to the code they shared."
        ),
        messages=history
    )

    reply = response.content[0].text
    history.append({"role": "assistant", "content": reply})

    return reply

max_tokens is set to 2048 here instead of 1024. Code reviews tend to be longer — give Claude room to explain properly.

The Terminal Loop

Now wrap that function in a loop that keeps running until the user decides to stop:

def main():
    print("Code Assistant — type 'exit' to quit\n")

    while True:
        user_input = input("You: ").strip()

        if not user_input:
            continue

        if user_input.lower() == "exit":
            break

        response = chat(user_input)
        print(f"\nClaude: {response}\n")

if __name__ == "__main__":
    main()

strip() removes accidental whitespace. The empty input check prevents sending blank messages to the API and wasting tokens.

The Full Script

Put it all together in assistant.py:

from dotenv import load_dotenv
from anthropic import Anthropic, APIError, RateLimitError, APIConnectionError

load_dotenv()
client = Anthropic()

history = []

def chat(user_message: str) -> str:
    history.append({"role": "user", "content": user_message})

    try:
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=2048,
            system=(
                "You are a code review assistant. "
                "When the user shares code, review it: identify bugs, explain what each part does, "
                "and suggest improvements. Be direct and specific. "
                "When the user asks follow-up questions, refer back to the code they shared."
            ),
            messages=history
        )

        reply = response.content[0].text
        history.append({"role": "assistant", "content": reply})
        return reply

    except RateLimitError:
        return "Rate limit reached. Wait a moment and try again."

    except APIConnectionError:
        return "Connection failed. Check your internet."

    except APIError as e:
        return f"API error {e.status_code}."

def main():
    print("Code Assistant — type 'exit' to quit\n")

    while True:
        user_input = input("You: ").strip()

        if not user_input:
            continue

        if user_input.lower() == "exit":
            break

        response = chat(user_input)
        print(f"\nClaude: {response}\n")

if __name__ == "__main__":
    main()

Run it:

python assistant.py

How It Behaves

A real session looks like this:

Code Assistant — type 'exit' to quit

You: def divide(a, b): return a / b

Claude: The function works for most inputs but has one critical issue:
it will raise a ZeroDivisionError if b is 0. There's no input
validation. Here's a safer version:

def divide(a, b):
    if b == 0:
        return None  # or raise ValueError("Cannot divide by zero")
    return a / b

Also worth adding type hints if this is going into a larger codebase:

def divide(a: float, b: float) -> float | None:
    if b == 0:
        return None
    return a / b

You: why use None instead of raising an error?

Claude: It depends on how the function is used. Returning None is
better when the caller expects to handle missing results gracefully —
for example, in data pipelines where a failed calculation shouldn't
stop everything. Raising ValueError is better when divide(a, 0) should
never happen and you want to catch it early during development...

Claude remembers the code from the first message. The follow-up question gets a specific answer, not a generic one.

What's Happening Under the Hood

Every time you send a message, the full history goes with it:

Call 1: [user: "def divide(a, b)..."]
Call 2: [user: "def divide...", assistant: "...", user: "why use None?"]
Call 3: [user: "def divide...", assistant: "...", user: "why use None?", assistant: "...", user: "next question"]

The history grows with every turn. For long sessions this means more tokens per call — and higher cost. For a personal tool used in short bursts, it's not a problem. For a production app with many users, you'd want to trim old history at some point.

Adapting the System Prompt

The system prompt is what makes this a code assistant instead of a general chatbot. Change it and you get a completely different tool.

A Python tutor:

system="You are a Python tutor for university students. Explain concepts clearly, use analogies, and always show working examples."

A code translator:

system="You are a code translator. When the user shares code in any language, rewrite it in Python. Explain the key differences."

A documentation writer:

system="You are a technical writer. When the user shares a function, write clear docstrings and usage examples for it."

Same script. Different system prompt. Completely different tool.

Common Mistakes

Pasting multiline code directly into the terminal
Most terminals handle it fine, but some break on indentation. If your code isn't being read correctly, wrap it in triple quotes when pasting or read it from a file instead.

History growing too large
Long sessions accumulate a lot of tokens. If responses start slowing down or costs seem high, clear the history list between sessions.

max_tokens too low for code reviews
Code explanations are longer than regular answers. 1024 cuts them off. 2048 is safer for this use case.

What's Next

This is a working tool you can use today. From here, a few natural extensions:

Read code directly from files instead of pasting — open("script.py").read() and pass the content as the message.

Add streaming so responses appear word by word instead of all at once — the same pattern from part one works here.

Save the conversation history to a file so you can review past sessions.

The full Claude API documentation is at platform.claude.com/docs.

# The whole thing, simplified

from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()
client = Anthropic()
history = []

while True:
    user_input = input("You: ").strip()
    if user_input.lower() == "exit":
        break

    history.append({"role": "user", "content": user_input})
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        system="You are a code review assistant. Be direct and specific.",
        messages=history
    )
    reply = response.content[0].text
    history.append({"role": "assistant", "content": reply})
    print(f"\nClaude: {reply}\n")

How to Use the Claude API with Python

Jon Ibañez del campo — Sun, 03 May 2026 10:06:25 +0000

You have a Python script. You want it to think.

That’s the whole premise. This tutorial shows you how to connect your code to Claude — Anthropic’s AI model — so it can read, reason, and respond inside your own projects.

I wrote this after spending an afternoon figuring it out myself. No prior AI experience needed. If you’ve written a Python function before, you can follow this.

Before You Start

Two things are worth knowing up front.

First, the API costs money. Not much — $5 gets you weeks of normal usage — but it’s not free like the Claude.ai chat interface. You’ll need to add credits at console.anthropic.com.

Second, you’ll need Python 3.9 or later. Check yours:

python --version

If it’s older than 3.9, update it at python.org. During installation on Windows, check "Add Python to PATH" — it’s easy to miss, and skipping it breaks everything.

Setup

Create a folder, set up a virtual environment, and install the SDK.

mkdir claude-project
cd claude-project
python -m venv venv

Activate it:

# Mac/Linux
source venv/bin/activate

# Windows
venv\Scripts\activate

Your terminal line should now start with (venv). That’s how you know it’s active. If you install without it, your packages end up in the wrong place.

pip install anthropic python-dotenv

Your API Key

Go to console.anthropic.com, create an account, and generate a key under API Keys.

Store it in a .env file in your project folder:

ANTHROPIC_API_KEY=your-key-here

Keep it out of GitHub:

echo .env > .gitignore

This matters. A public API key gets found, used, and charged to you within hours.

The First Call

Here’s what talking to Claude from Python looks like:

from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()
client = Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "What is a REST API?"
        }
    ]
)

print(message.content[0].text)

Run it. Claude answers in your terminal.

Three things to understand about this call:

model is which version of Claude you’re using. claude-sonnet-4-6 is the default for most use cases — fast and capable.

max_tokens is the maximum length of Claude’s response. Set it too low and the response gets cut off mid-sentence. 1024 is a safe starting point.

messages is a list of turns in the conversation. Each turn has a role — user for your messages, assistant for Claude’s.

What Comes Back

The response object holds more than just text:

print(message.content[0].text)       # Claude's response
print(message.stop_reason)           # Why it stopped — usually "end_turn"
print(message.usage.input_tokens)    # Tokens in your message
print(message.usage.output_tokens)   # Tokens in Claude's reply

Tokens are roughly words. Watching them matters because that’s what you’re paying for.

Giving Claude a Role

By default, Claude is a general assistant. A system prompt changes that.

Think of it as a briefing you give before the conversation starts:

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You are a Python code reviewer. Be direct. Point out issues first, then explain why.",
    messages=[
        {"role": "user", "content": "Review this: for i in range(len(my_list)): print(my_list[i])"}
    ]
)

print(message.content[0].text)

Same model. Completely different behavior. The system prompt is where most of the real control lives.

Conversations

The API has no memory. Every call starts fresh unless you pass the history yourself.

This is what a real conversation looks like:

from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()
client = Anthropic()

history = []

def chat(message: str) -> str:
    history.append({"role": "user", "content": message})

    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        system="You are a helpful programming assistant.",
        messages=history
    )

    reply = response.content[0].text
    history.append({"role": "assistant", "content": reply})

    return reply

print(chat("What is a decorator in Python?"))
print(chat("Show me a real example."))
print(chat("How would that work in Flask?"))

Each call passes the full history. Claude reads it, understands the context, and continues the thread.

The mistake most people make: appending the user message but forgetting to append Claude’s reply. Do that and the next message arrives without context — Claude answers as if the conversation never happened.

Streaming

Waiting for a full response before printing anything works fine for scripts. For anything user-facing, streaming feels much better.

from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()
client = Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain recursion simply."}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

print()

Instead of waiting, words appear as Claude generates them — the same experience you get in the Claude.ai interface.

A Real Use Case

Here’s a function worth keeping. It summarizes any text you pass to it:

from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()
client = Anthropic()

def summarize(text: str, sentences: int = 3) -> str:
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=512,
        system=f"Summarize the following text in {sentences} sentences. Return only the summary.",
        messages=[{"role": "user", "content": text}]
    )
    return response.content[0].text

article = """
The James Webb Space Telescope has captured the deepest infrared image
of the universe ever taken. The image covers a patch of sky approximately
the size of a grain of sand held at arm's length. It contains thousands
of galaxies, some of which formed less than a billion years after the
Big Bang. Scientists believe this data will reshape our understanding
of how the earliest galaxies formed and evolved.
"""

print(summarize(article, sentences=2))

Change the system prompt and it becomes a translator, a classifier, a data extractor. The pattern is always the same.

Handling Errors

Networks fail. Rate limits happen. Wrap your calls:

from dotenv import load_dotenv
from anthropic import Anthropic, APIError, RateLimitError, APIConnectionError

load_dotenv()
client = Anthropic()

def ask(question: str) -> str:
    try:
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            messages=[{"role": "user", "content": question}]
        )
        return response.content[0].text

    except RateLimitError:
        return "Rate limit reached. Wait a moment and try again."

    except APIConnectionError:
        return "Connection failed. Check your internet."

    except APIError as e:
        return f"API error {e.status_code}."

Choosing a Model

Three options, three tradeoffs:

Model	Use when
`claude-sonnet-4-6`	Most things. Fast, capable, cost-effective
`claude-opus-4-6`	Hard problems that need deep reasoning
`claude-haiku-4-5-20251001`	High volume, simple tasks, lowest cost

Start with Sonnet. Switch if you have a reason.

Things That Will Catch You

A few things I ran into that aren’t obvious from the docs:

The API costs money. Claude.ai doesn’t. It’s easy to assume they work the same way — they don’t. Add credits before you start.

load_dotenv() doesn’t call itself. If your key isn’t loading, this is probably why.

max_tokens being too low cuts responses mid-thought. If answers feel incomplete, raise it.

The conversation history needs both sides: user messages and Claude’s replies. Miss one and the context breaks.

On Mac and Linux, python might point to Python 2. Use python3 if things aren’t working as expected.

What's Next

The foundation is here. Where it goes depends on what you’re building.

Tool use lets Claude call your own Python functions — useful when you want it to interact with real data or external services.

Vision lets you send images alongside text, so Claude can read screenshots, diagrams, or documents.

Async support via AsyncAnthropic is worth exploring if you’re handling multiple requests at once.

The full documentation is at platform.claude.com/docs.

# The whole thing in ten lines

from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()
client = Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Your message here."}]
)

print(response.content[0].text)