🐍 Python Basics (การแปลภาษาไทยกำลังจะมา) · Python 编程基础

This page teaches Python by walking through two short files that together make a working AI assistant. The assistant runs locally with the Hermes 3 model, can search the web, generate pictures, and send messages to LINE. Every concept below — imports, functions, type hints, docstrings, async/await, HTTP requests — appears in those files. We'll pull out the relevant lines, explain them, and at the end you'll see both files in full.

If you're new to Python: don't try to memorize the syntax. Read it like prose. Python is unusually close to English, and the goal of this page is to show you that you can already understand most of what's happening.

A Python file is just text. When you run python agent_pro.py, the interpreter reads the file top-to-bottom and executes each line. Most files have three sections, in this order:

1. Imports — bring in code from other modules.
2. Definitions — declare functions, classes, constants.
3. The entry point — what to actually do when the file is run.

You can see this skeleton clearly in agent_pro.py:

import asyncio
import os
from datetime import date
from pathlib import Path

from llama_index.core.agent.workflow import ReActAgent
from llama_index.core.tools import FunctionTool
from llama_index.llms.ollama import Ollama


def multiply(a: float, b: float) -> float:
    """Multiply two numbers and return the product."""
    return a * b

# ... more functions ...

if __name__ == "__main__":
    asyncio.run(main())

Python comes with a "standard library" of useful modules built in, and you can install thousands more with pip install. Imports give you access to them. There are two forms:

import asyncio                       # whole module — use as asyncio.run(...)
from datetime import date            # one thing from a module — use as date.today()
from pathlib import Path             # same pattern
from llama_index.llms.ollama import Ollama  # nested package, deep import

The first form keeps the module's name as a prefix when you use it. The second form pulls a specific name into your file so you can use it bare. Both are fine; the choice is mostly about readability.

A function is a named block of code that takes inputs and returns an output. Here's the simplest one in the file:

def multiply(a: float, b: float) -> float:
    """Multiply two numbers and return the product."""
    return a * b

Read it left-to-right:

• def introduces a function definition.
• multiply is the name we'll call it by.
• (a: float, b: float) says it takes two inputs, both floating-point numbers.
• -> float says it returns a floating-point number.
• The """...""" line below is the docstring — documentation that lives inside the code.
• return a * b hands the result back to whoever called it.

Indentation matters in Python. The lines that make up the function body are all indented the same amount (four spaces, by convention). When the indentation stops, the function ends. There are no curly braces.

The : float and -> float annotations above are type hints. Python itself doesn't enforce them — you can technically pass a string to multiply and Python won't stop you until the multiplication actually fails. But they serve two important purposes:

• They make the code self-documenting. A reader sees def days_until(iso_date: str) -> str and knows immediately what goes in and what comes out.
• Tools like editors, linters, and (in our case) the LLM agent itself read type hints to know how to call the function correctly.

The agent in agent_pro.py learns the shape of each tool from its hints and docstring. That's why every tool here has both.

Look at web_search:

def web_search(query: str) -> str:
    """Search the web with DuckDuckGo and return the top 5 result snippets.

    Use this whenever the user asks about current events, prices, weather,
    sports scores, or anything you wouldn't already know.
    """
    from duckduckgo_search import DDGS

    with DDGS() as ddg:
        results = list(ddg.text(query, max_results=5))
    if not results:
        return "No results found."
    return "\n\n".join(
        f"{r['title']}\n{r['href']}\n{r['body']}" for r in results
    )

The triple-quoted string at the top is the docstring. It's a normal Python string — it just happens to be the first thing inside the function. Python stashes it on the function so other code can read it. In our case, the agent literally reads this docstring to decide when to use the tool. The line "Use this whenever the user asks about current events, prices, weather…" is instructions to the LLM, not just notes for humans.

Python comes with a remarkable amount of useful code already built in. agent_pro.py uses four standard-library modules:

import asyncio                  # event loops, async/await
import os                       # operating system stuff: env vars, paths
from datetime import date       # working with calendar dates
from pathlib import Path        # filesystem paths as objects

You don't need to install any of these. They ship with Python. Two examples of how they're used in the file:

# Read an environment variable, returning None if it's not set:
token = os.getenv("LINE_CHANNEL_ACCESS_TOKEN")

# Build a directory and a path to a file inside it:
Path("images").mkdir(exist_ok=True)
out_path = Path("images") / filename

That Path("images") / filename line is striking on its own. Path objects overload the / operator so that joining paths reads like… well, like a path. It works the same on Windows (images\out.png) and Linux (images/out.png) — Path handles the difference.

Anything outside the standard library has to be installed first:

pip install llama-index requests duckduckgo-search

Then you import them like any other module. agent_pro.py uses:

• llama_index — builds the agent loop. We pull in ReActAgent, FunctionTool, and Ollama (the local-LLM client).
• requests — the most widely-used HTTP client in Python. We'll see this one up close in the next section.
• duckduckgo_search — a thin wrapper over DuckDuckGo's search results.

Section 7 mentioned pip install in passing. It's worth a closer look, because installing packages is the single most common thing you do in a Python project — and there are two tools worth knowing.

8a. pip, the standard tool

pip ships with Python. Run these from your terminal (PowerShell, Terminal, or your IDE's built-in one), not inside Python:

pip install requests              # install one package
pip install -r requirements.txt   # install a list of packages from a file
pip uninstall requests            # remove one
pip list                          # see what's installed
pip show requests                 # details about a specific package

A requirements file is plain text listing one package per line, often with version pins:

llama-index>=0.10
requests==2.31.0
duckduckgo-search

Committing this file to your project means anyone else (and future you) can rebuild the same environment with one command.

8b. Virtual environments

Installing every package globally with pip works at first, but breaks fast: two projects need different versions of the same library and you can only have one. The fix is a virtual environment — a private folder containing its own Python and its own packages, isolated from the rest of your system.

python -m venv .venv                  # create a venv in ./.venv/
.venv\Scripts\activate                # activate it (Windows PowerShell)
source .venv/bin/activate             # activate it (macOS / Linux)
pip install requests                  # installs *only* into .venv now
deactivate                            # return to the system Python

You make one venv per project. The folder is conventionally called .venv and is added to .gitignore — it gets rebuilt from requirements.txt wherever the code is checked out.

8c. uv, the new fast alternative

uv is a newer tool written in Rust that does what pip and venv do, but dramatically faster — often 10× to 100× — and bundles them into one workflow. Install it once:

pip install uv

Then use these instead of pip / venv:

uv venv                               # create a .venv
uv pip install requests               # install into it (no activation needed)
uv pip install -r requirements.txt    # same input file as pip, much faster
uv run python agent_pro.py            # run a script inside the venv

The uv run ... form is the killer feature: it picks up the project's venv automatically, installs anything missing, and runs your script — no manual activate step.

This is the section the rest of the page was building toward. APIs ("Application Programming Interfaces") are how programs talk to other programs over the network. Most modern AI services — OpenAI, Anthropic, Google's Gemini, Stripe, LINE — expose APIs that take JSON in and send JSON back. If you can read image_gen.py, you can use any of them.

Here's the entire file. Forty lines, including blank lines and the docstring. We'll go through it piece by piece.

"""image_gen.py — Gemini Nano Banana 2 backend for agent_pro.py.

Drops in for the Mac-Stack SDXL helper. Exposes generate(prompt, out_path)
so agent_pro.py's generate_image tool keeps working unchanged.
"""
import base64
from pathlib import Path

import requests

_KEY_FILE = Path(r"C:\Users\Admin\claude\env.txt.txt")
_ENDPOINT = (
    "https://generativelanguage.googleapis.com/v1beta/models/"
    "gemini-3.1-flash-image-preview:generateContent"
)


def _load_key() -> str:
    for line in _KEY_FILE.read_text(encoding="utf-8").splitlines():
        name, _, value = line.partition(":")
        if name.strip() == "google-api":
            return value.strip()
    raise RuntimeError(f"google-api entry not found in {_KEY_FILE}")


def generate(prompt: str, out_path: str) -> str:
    r = requests.post(
        f"{_ENDPOINT}?key={_load_key()}",
        json={
            "contents": [{"parts": [{"text": prompt}]}],
            "generationConfig": {"responseModalities": ["IMAGE"]},
        },
        timeout=120,
    )
    r.raise_for_status()
    parts = r.json()["candidates"][0]["content"]["parts"]
    img_b64 = next(p["inlineData"]["data"] for p in parts if "inlineData" in p)
    Path(out_path).write_bytes(base64.b64decode(img_b64))
    return out_path

9a. Constants at the top

Two conventions to notice:

• The leading underscore (_KEY_FILE, _ENDPOINT) is a Python convention meaning "this is private to this file; don't import it from elsewhere." The interpreter doesn't enforce it — it's a polite signal to other humans.
• The r"..." prefix is a "raw string." It tells Python not to treat backslashes specially. Useful for Windows paths because "C:\Users\..." without the r would have to be written "C:\\Users\\...".
• Two adjacent string literals — "...models/" "gemini-3.1..." — get joined automatically. This is a clean way to wrap long URLs without having to use + for concatenation.

9b. Reading an API key from a file

_load_key walks each line of the secrets file, splits on the first colon with partition, and returns the value for the entry named google-api. The underscore in name, _, value = line.partition(":") means "I don't care about this value" — partition returns three pieces (left, separator, right) and we don't need the separator.

9c. Making the HTTP request

requests.post(...) sends an HTTP POST request and returns a response object. There's almost a one-to-one mapping between the arguments and what's happening on the network:

• The URL uses an "f-string" — Python substitutes the expressions inside {} at runtime.
• The body: json={...} — pass a Python dictionary; requests serializes it to JSON and sets Content-Type: application/json. The shape comes from the Gemini API docs.
• The timeout: timeout=120. Without this, a hanging server could freeze your program forever. Always set a timeout.

9d. Handling the response

1. r.raise_for_status() — if the server returned an error code (4xx or 5xx), raise an exception. Without this, the next line would try to read the error message as a valid response.
2. r.json() parses the response body as JSON. The chain ["candidates"][0]["content"]["parts"] reaches into Gemini's nested structure.
3. The next(...) line finds the first image part. Gemini can return text and image parts; we want the image. p["inlineData"]["data"] is the image as a base64 string.
4. base64.b64decode(img_b64) converts base64 text back into raw bytes — actual JPEG file contents. Path(out_path).write_bytes(...) writes them to disk.

Section 9 showed how image_gen.py makes an HTTP request to Google's Gemini service. Two other services worth knowing offer generous free tiers: NVIDIA build.nvidia.com and HuggingFace. Sign up for both — they take about a minute each.

10a. NVIDIA build.nvidia.com

1. Go to build.nvidia.com
2. Click Login (top right)
3. Click any model card (e.g. Llama 3.3 70B or FLUX.1)
4. Click Get API Key — key starts with nvapi-...

import base64, requests

API_KEY = "nvapi-..."   # load from your secrets file, not inline
r = requests.post(
    "https://ai.api.nvidia.com/v1/genai/black-forest-labs/flux.1-schnell",
    headers={"Authorization": f"Bearer {API_KEY}", "Accept": "application/json"},
    json={"prompt": "a Lanna temple at sunrise", "width": 1024, "height": 1024, "seed": 0},
    timeout=60,
)
r.raise_for_status()
img_b64 = r.json()["artifacts"][0]["base64"]
open("temple.png", "wb").write(base64.b64decode(img_b64))

Notice the shape: POST, JSON body, base64 image in the response, decode and write. Exactly what image_gen.py does, with different field names. Once you've read one API, you've largely read them all.

10b. HuggingFace

1. Go to huggingface.co/join
2. Settings → Access Tokens, click New token, choose Read
3. Token starts with hf_...

pip install huggingface_hub
hf auth login    # paste your hf_... token when prompted

10c. What you can build with these keys

10d. Keeping keys safe — non-negotiable

1. Never paste a key into source code that gets committed to git. Bots scan public repos for patterns like AIza..., sk-..., nvapi-... within seconds of a push, and use found keys to run up huge bills.
2. Use scoped tokens where the service offers them.
3. Rotate keys when something looks weird.

To put the package-installation lesson into practice, here's a tiny standalone function that uses a third-party package to generate a QR code. Useful for handouts: print a QR code on a worksheet, students scan it to reach a website or video.

pip install "qrcode[pil]"

The [pil] tells pip to also pull in Pillow (the Python imaging library), which qrcode uses to draw the actual image.

def make_qr(text: str, out_path: str = "qr.png") -> str:
    """Encode some text or a URL as a QR code and save it as a PNG."""
    import qrcode

    img = qrcode.make(text)
    img.save(out_path)
    return out_path

Three lines of real work — the typical shape of a small Python function once you have the right package. You'd call it like:

make_qr("https://krueng.ai/lesson-5", "lesson5_qr.png")

Once you understand the pieces, the main function in agent_pro.py reads in one breath:

async def main() -> None:
    agent = build_agent()
    print("Hermes Pro agent ready. Empty line to quit.\n")
    while True:
        try:
            q = input("you > ").strip()
        except (EOFError, KeyboardInterrupt):
            print()
            return
        if not q:
            return
        response = await agent.run(q)
        print(f"\nagent > {response}\n")

Build the agent, then in a loop: read a line from the user, send it to the agent, print the response. try/except catches Ctrl-C and Ctrl-D so they don't crash the program. if not q: return exits on an empty line.

The async and await keywords

The function is declared with async def instead of plain def, and it uses await on the line that calls the agent. The ReActAgent from LlamaIndex is built on Python's asynchronous machinery. When you call agent.run(q), it returns immediately — not with an answer, but with a handle to work-in-progress. await tells Python "pause this function until the work finishes, then give me the result." For that to be possible, the surrounding function has to be marked async. And to run an async function from a normal script, you need asyncio.run(...):

if __name__ == "__main__":
    asyncio.run(main())

You don't need to fully understand async to use it. The rule of thumb: if a library says "you must await this," wrap your caller in async def, use await, and start it all with asyncio.run(...).

Notepad works. But an IDE (Integrated Development Environment) gives you syntax highlighting, autocomplete, inline error checking, a debugger, and a built-in terminal — all of which save real time. Four worth considering:

VS Code

Free, made by Microsoft, by far the most popular editor for Python today. Install the official "Python" extension. Cross-platform. The safe default — start here.

PyCharm Community Edition

Free, made by JetBrains. Heavier than VS Code but everything is configured out of the box. Particularly good for refactoring and navigating large codebases.

Cursor

Free for basic use, a fork of VS Code with built-in AI chat. If you're already learning with AI tools, having a chat window that can read the file you're editing is genuinely useful.

Thonny

Free, designed specifically for beginners. Ships with its own Python. The variable explorer (a panel showing what's in memory at each step) is a real teaching aid.

If you want to go deeper, in this order:

• python_basics.ipynb — the same material as this page, but as a runnable notebook. Change a cell, press Shift+Enter, watch it run.
• python_next_steps.ipynb — modules, file I/O, try / except, and list comprehensions. Takes you from "I can read Python" to "I can write small useful scripts."
• python_apis_async.ipynb — functions in depth (defaults, *args, lambdas, decorators), calling HTTP APIs with requests, and async / await.
• The official Python tutorial — docs.python.org/3/tutorial. Short, dense, and authoritative.
• The requests library quickstart — most APIs you'll ever use are reachable through the same four or five lines you saw above.
• Real Python — practical articles aimed at intermediate learners.
• The asyncio docs, once you've written enough sync code to feel the need for async.

But before any of that, the most useful thing you can do is read your own code out loud, the way we did with these files. The patterns repeat.