🧰 Python Toolkit (การแปลภาษาไทยกำลังจะมา) · Python 工具箱

You can already read a Python file. You know functions, loops, and lists. This page covers the next seven tools. Each one solves a problem you will meet soon.

Every section has the same shape: the problem, the code, and when to use it. Read the code out loud. Then open the notebook and change it.

• 1. Classes — keep data and behaviour together.
• 2. Generators — handle data too big for memory.
• 3. Decorators — add behaviour to a function without editing it.
• 4. Type hints — say what goes in and what comes out.
• 5. pathlib — file paths that work on every computer.
• 6. json — save and load data in two lines.
• 7. requests — fetch web pages and APIs.
• 8. All seven in one program

Say you are tracking dogs at a shelter. Each dog has a name and an age. Each dog can bark. With plain variables it gets messy fast:

dog1_name = "Somchai"
dog1_age = 3
dog2_name = "Nong Mee"
dog2_age = 5

Two dogs need four variables. Ten dogs need twenty. And nothing links a name to its age. A class fixes this. A class is a template. It says what data one dog holds, and what one dog can do.

class Dog:
    """One dog at the shelter."""

    def __init__(self, name, age):
        self.name = name
        self.age = age

    def bark(self):
        return f"{self.name} says woof!"

    def human_years(self):
        return self.age * 7

Now make some dogs. Each one is an object built from the template:

somchai = Dog("Somchai", 3)
nong_mee = Dog("Nong Mee", 5)

print(somchai.bark())         # Somchai says woof!
print(nong_mee.human_years()) # 35

Reading the class

• class Dog: starts the template. Class names use CapitalCase by convention.
• __init__ runs once when you make a new dog. It is called the constructor.
• self means "this particular dog". Every method takes it as the first input.
• self.name = name stores the name on the object, so it stays there.
• bark and human_years are methods — functions that belong to the class.
• You never pass self yourself. somchai.bark() passes it for you.

When to use a class

Use a class when some data and some actions always travel together. A dog and its bark. A user and their password check. A file and how you save it.

Do not use a class when a function is enough. Many beginners wrap one function in a class for no reason. If your class has one method and no stored data, write a function instead.

dog1_name = "Somchai"
dog1_age = 3
dog2_name = "Nong Mee"
dog2_age = 5

class Dog:
    """One dog at the shelter."""

    def __init__(self, name, age):
        self.name = name
        self.age = age

    def bark(self):
        return f"{self.name} says woof!"

    def human_years(self):
        return self.age * 7

somchai = Dog("Somchai", 3)
nong_mee = Dog("Nong Mee", 5)

print(somchai.bark())         # Somchai says woof!
print(nong_mee.human_years()) # 35

Here is a function that reads a log file:

def read_lines(path):
    lines = []
    with open(path) as f:
        for line in f:
            lines.append(line.strip())
    return lines          # the WHOLE file is now in memory

This works for a small file. For a 20 GB log file, your computer runs out of memory and the program dies. The problem is return. It hands back everything at once.

A generator hands back one item at a time. You swap return for yield:

def read_lines(path):
    with open(path) as f:
        for line in f:
            yield line.strip()   # give ONE line, then pause

The code looks almost the same. The behaviour is completely different.

What yield actually does

Calling the function does not run it. It returns a generator object — a promise to produce values later.

lines = read_lines("huge.log")
print(lines)        # generator object, no file read yet

for line in lines:  # NOW it runs, one line at a time
    print(line)

Each time the loop asks for a value, the function runs until it hits yield. Then it pauses, keeping all its variables. The next request wakes it up at that exact spot.

An endless generator

Because values are made on demand, a generator can be infinite. A list cannot.

def count_from(start):
    n = start
    while True:          # never ends
        yield n
        n += 1

for n in count_from(10):
    print(n)
    if n >= 13:
        break            # 10, 11, 12, 13

Rules to remember

• Any function with yield in it is a generator. There is no other keyword.
• A generator is used once. Loop over it twice and the second loop gets nothing.
• You cannot ask for len() or index it with [3]. It does not know its own size.
• Need a list after all? list(read_lines(path)) — but that brings the memory cost back.

def read_lines(path):
    lines = []
    with open(path) as f:
        for line in f:
            lines.append(line.strip())
    return lines          # 整个文件现在都在内存里

def read_lines(path):
    with open(path) as f:
        for line in f:
            yield line.strip()   # 交出一行，然后暂停

lines = read_lines("huge.log")
print(lines)        # 生成器对象，此时还没读文件

for line in lines:  # 现在才开始运行，一次一行
    print(line)

def count_from(start):
    n = start
    while True:          # 永远不结束
        yield n
        n += 1

for n in count_from(10):
    print(n)
    if n >= 13:
        break            # 10, 11, 12, 13

You have five functions. You want to know how long each one takes. The obvious fix is to edit all five:

def fetch_data():
    start = time.time()          # added
    ...
    print(time.time() - start)   # added

That is the same two lines copied five times. If you change the format, you edit five places. A decorator writes those lines once and wraps them around any function.

import time

def timed(fn):
    """Print how long the wrapped function takes."""
    def wrapper(*args, **kwargs):
        start = time.time()
        result = fn(*args, **kwargs)
        print(f"{fn.__name__} took {time.time() - start:.2f}s")
        return result
    return wrapper

Now use it. The @ line is the decorator:

@timed
def slow_add(a, b):
    time.sleep(1)
    return a + b

slow_add(2, 3)
# slow_add took 1.00s
# 5

How to read it

A decorator is a function that takes a function and returns a new function. That sentence is the whole idea. The @ is only shorthand:

@timed
def slow_add(a, b): ...

# means exactly the same as:

def slow_add(a, b): ...
slow_add = timed(slow_add)

• timed(fn) receives the original function as fn.
• wrapper is the replacement. It does the extra work, then calls fn.
• *args, **kwargs means "accept any inputs" and pass them straight through.
• return result matters. Forget it and your function returns None.
• return wrapper — note the missing brackets. You return the function, not a call to it.

Where you will meet them

You will use decorators from libraries long before you write your own:

Decorator	From	What it does
@app.route("/hi")	Flask	Runs this function when a browser visits /hi.
@property	Python itself	Lets a method be read like plain data.
@staticmethod	Python itself	A method in a class that ignores self.
@lru_cache	functools	Remembers past results so repeat calls are instant.
@pytest.fixture	pytest	Supplies test data to your tests.

def fetch_data():
    start = time.time()          # 新增
    ...
    print(time.time() - start)   # 新增

import time

def timed(fn):
    """Print how long the wrapped function takes."""
    def wrapper(*args, **kwargs):
        start = time.time()
        result = fn(*args, **kwargs)
        print(f"{fn.__name__} took {time.time() - start:.2f}s")
        return result
    return wrapper

@timed
def slow_add(a, b):
    time.sleep(1)
    return a + b

slow_add(2, 3)
# slow_add took 1.00s
# 5

@timed
def slow_add(a, b): ...

# 和下面完全等价：

def slow_add(a, b): ...
slow_add = timed(slow_add)

Look at this function. What is data? A list? A file? A number?

def process(data):
    ...

You cannot tell. You have to read the whole body to find out. Type hints answer the question in the first line:

def greet(name: str) -> str:
    """Return a friendly greeting."""
    return f"Hello, {name}!"

• name: str — the input should be a string.
• -> str — the function gives back a string.
• Nothing else changed. The function body is the same.

Python does not enforce them. greet(42) still runs. Hints are notes for humans and tools, not rules for the interpreter.

The types you will actually use

Hint	Means
str, int, float, bool	Text, whole number, decimal, True/False.
list[str]	A list of strings.
dict[str, int]	A dictionary with string keys and number values.
str | None	A string, or nothing. Very common for "might fail".
Path	A pathlib path — see the next section.
-> None	Returns nothing. Use it for functions that only print or save.

from pathlib import Path

def word_count(text: str) -> dict[str, int]:
    """Count how many times each word appears."""
    counts: dict[str, int] = {}
    for word in text.lower().split():
        counts[word] = counts.get(word, 0) + 1
    return counts


def find_config(folder: Path) -> Path | None:
    """Return the config file if it exists, otherwise None."""
    candidate = folder / "config.json"
    return candidate if candidate.exists() else None

Why bother

• Your editor gets smarter. Type name. and VS Code lists every string method. Without the hint it cannot guess.
• Mistakes are caught early. Run pip install mypy, then mypy myfile.py. It finds wrong types before you run anything.
• The code documents itself. -> Path | None warns the reader to handle the None case.
• AI tools read them. An LLM agent decides how to call your function from its hints and docstring.

Lesson 1 introduces type hints too, from the beginner's side.

def process(data):
    ...

def greet(name: str) -> str:
    """Return a friendly greeting."""
    return f"Hello, {name}!"

from pathlib import Path

def word_count(text: str) -> dict[str, int]:
    """Count how many times each word appears."""
    counts: dict[str, int] = {}
    for word in text.lower().split():
        counts[word] = counts.get(word, 0) + 1
    return counts


def find_config(folder: Path) -> Path | None:
    """Return the config file if it exists, otherwise None."""
    candidate = folder / "config.json"
    return candidate if candidate.exists() else None

Old Python code joins paths with strings:

import os

path = os.path.join(os.path.dirname(__file__), "data", "notes.txt")
name = os.path.splitext(os.path.basename(path))[0]
if not os.path.exists(os.path.dirname(path)):
    os.makedirs(os.path.dirname(path))

It works, but it is hard to read. Every line calls a different os.path function on a plain string. pathlib gives you a real Path object instead:

from pathlib import Path

path = Path(__file__).parent / "data" / "notes.txt"
name = path.stem
path.parent.mkdir(parents=True, exist_ok=True)

Three lines, and each one says what it does.

The slash is the trick

pathlib reuses the / operator to join paths. It reads like a real path:

base = Path("lessons")
today = base / "2026" / "august" / "notes.txt"
print(today)
# Windows:  lessons\2026\august\notes.txt
# Mac/Linux: lessons/2026/august/notes.txt

You write / and Python picks the right separator for the computer. Never type "folder\\file.txt" again.

The methods worth memorising

Code	What you get
p.name	notes.txt — the file name with its extension.
p.stem	notes — the name without the extension.
p.suffix	.txt — the extension.
p.parent	The folder holding the file.
p.exists()	True or False.
p.mkdir(parents=True, exist_ok=True)	Make the folder. Do not complain if it is already there.
p.read_text(encoding="utf-8")	The whole file as a string. No open() needed.
p.write_text(s, encoding="utf-8")	Save a string to the file.
p.glob("*.txt")	Every .txt file in the folder. A generator!
p.rglob("*.txt")	The same, but through every sub-folder too.

from pathlib import Path

folder = Path("lessons")
for txt in folder.rglob("*.txt"):
    print(txt.stem, "-", len(txt.read_text(encoding="utf-8")), "characters")

import os

path = os.path.join(os.path.dirname(__file__), "data", "notes.txt")
name = os.path.splitext(os.path.basename(path))[0]
if not os.path.exists(os.path.dirname(path)):
    os.makedirs(os.path.dirname(path))

from pathlib import Path

path = Path(__file__).parent / "data" / "notes.txt"
name = path.stem
path.parent.mkdir(parents=True, exist_ok=True)

base = Path("lessons")
today = base / "2026" / "august" / "notes.txt"
print(today)
# Windows:  lessons\2026\august\notes.txt
# Mac/Linux: lessons/2026/august/notes.txt

from pathlib import Path

folder = Path("lessons")
for txt in folder.rglob("*.txt"):
    print(txt.stem, "-", len(txt.read_text(encoding="utf-8")), "characters")

Your program has a Python dictionary. You want it to still be there tomorrow. JSON is the standard text format for that job. Every language reads it, and every web API speaks it.

import json
from pathlib import Path

student = {
    "name": "Ploy",
    "level": "B1",
    "scores": [82, 91, 77],
    "active": True,
}

# Save it
Path("student.json").write_text(json.dumps(student, indent=2), encoding="utf-8")

# Load it back
loaded = json.loads(Path("student.json").read_text(encoding="utf-8"))
print(loaded["scores"][1])   # 91

That is the whole library, for most work. Two functions.

Four names, easy to mix up

Function	Direction	Remember it as
json.dumps(obj)	Python → text	dump-s = dump to string
json.loads(text)	text → Python	load-s = load from string
json.dump(obj, f)	Python → open file	no s = works on a file
json.load(f)	open file → Python	no s = works on a file

With pathlib you mostly need only the two s versions, as shown above.

How Python types map to JSON

Python	JSON
dict	object { }
list	array [ ]
str	string
int / float	number
True / False	true / false — lower case
None	null

Two arguments worth knowing

json.dumps(student, indent=2)                    # readable, one item per line
json.dumps(student, ensure_ascii=False)          # keeps Thai and Chinese readable

Without ensure_ascii=False, the word ครู is saved as ครู. It still loads correctly, but nobody can read the file.

import json
from pathlib import Path

student = {
    "name": "Ploy",
    "level": "B1",
    "scores": [82, 91, 77],
    "active": True,
}

# 保存
Path("student.json").write_text(json.dumps(student, indent=2), encoding="utf-8")

# 读回来
loaded = json.loads(Path("student.json").read_text(encoding="utf-8"))
print(loaded["scores"][1])   # 91

json.dumps(student, indent=2)                    # 好读，每项一行
json.dumps(student, ensure_ascii=False)          # 让中文和泰文保持可读

The first six tools ship with Python. This one you install:

pip install requests

It is the most-used package in Python, and it is worth the install. Here is a whole API call:

import requests

r = requests.get("https://api.github.com/repos/python/cpython", timeout=10)
r.raise_for_status()
data = r.json()

print(data["name"], "has", data["stargazers_count"], "stars")
# cpython has 74328 stars

Reading the four lines

• requests.get(url) asks a server for something and waits for the answer.
• timeout=10 gives up after 10 seconds. Always set it. Without it your program can hang forever.
• raise_for_status() raises an error if the server said 404 or 500. Without it, a failed request looks like a successful one.
• r.json() turns the reply into Python dictionaries and lists. It runs json.loads for you.

What comes back

Code	What you get
r.status_code	200 is fine. 404 not found. 500 server broke.
r.ok	True if the status is under 400.
r.text	The reply as a string — use this for HTML pages.
r.json()	The reply parsed from JSON — use this for APIs.
r.content	Raw bytes — use this for images and files.

Sending data with the request

# Query string: .../quotes?limit=3
r = requests.get("https://dummyjson.com/quotes", params={"limit": 3}, timeout=10)
for q in r.json()["quotes"]:
    print(f'"{q["quote"]}" — {q["author"]}')

# Sending JSON to a server
r = requests.post(
    "https://httpbin.org/post",
    json={"student": "Ploy", "score": 91},
    headers={"Authorization": "Bearer YOUR_KEY"},
    timeout=10,
)

• params= builds the ?key=value part safely. Do not glue it on with +.
• json= sends a Python dictionary as a JSON body. It sets the header for you.
• headers= is where API keys go, almost always as Authorization.

Saving a file you downloaded

Here requests and pathlib meet:

from pathlib import Path
import requests

r = requests.get("https://www.python.org/static/img/python-logo.png", timeout=30)
r.raise_for_status()
Path("logo.png").write_bytes(r.content)

pip install requests

import requests

r = requests.get("https://api.github.com/repos/python/cpython", timeout=10)
r.raise_for_status()
data = r.json()

print(data["name"], "has", data["stargazers_count"], "stars")
# cpython has 74328 stars

# 查询字符串：.../quotes?limit=3
r = requests.get("https://dummyjson.com/quotes", params={"limit": 3}, timeout=10)
for q in r.json()["quotes"]:
    print(f'"{q["quote"]}" — {q["author"]}')

# 向服务器发送 JSON
r = requests.post(
    "https://httpbin.org/post",
    json={"student": "Ploy", "score": 91},
    headers={"Authorization": "Bearer YOUR_KEY"},
    timeout=10,
)

from pathlib import Path
import requests

r = requests.get("https://www.python.org/static/img/python-logo.png", timeout=30)
r.raise_for_status()
Path("logo.png").write_bytes(r.content)

This script fetches quotes from a public API, saves them, and prints them. It uses all seven tools. Read it and name each one.

"""quotes.py — fetch quotes once, then read them from a local file.

    pip install requests
    python quotes.py
"""
import json
import time
from pathlib import Path
from typing import Iterator

import requests

CACHE_DIR = Path("cache")


def timed(fn):                                          # 3. decorator
    """Print how long the wrapped function takes."""
    def wrapper(*args, **kwargs):
        start = time.time()
        result = fn(*args, **kwargs)
        print(f"[{fn.__name__} took {time.time() - start:.2f}s]")
        return result
    return wrapper


class Quote:                                            # 1. class
    """One quote and the person who said it."""

    def __init__(self, text: str, author: str):         # 4. type hints
        self.text = text
        self.author = author

    def short(self, limit: int = 50) -> str:
        """The quote, cut to `limit` characters."""
        if len(self.text) <= limit:
            return self.text
        return self.text[:limit - 3] + "..."


@timed
def fetch_quotes(count: int) -> list[dict]:             # 7. requests
    """Ask the API for `count` quotes."""
    r = requests.get(
        "https://dummyjson.com/quotes",
        params={"limit": count},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()["quotes"]


def read_quotes(path: Path) -> Iterator[Quote]:         # 2. generator
    """Read the saved file, one Quote at a time."""
    data = json.loads(path.read_text(encoding="utf-8"))  # 6. json
    for item in data:
        yield Quote(item["quote"], item["author"])


def main() -> None:
    CACHE_DIR.mkdir(exist_ok=True)                      # 5. pathlib
    cache_file = CACHE_DIR / "quotes.json"

    if not cache_file.exists():
        print("No cache. Fetching...")
        quotes = fetch_quotes(5)
        cache_file.write_text(
            json.dumps(quotes, indent=2, ensure_ascii=False),
            encoding="utf-8",
        )
    else:
        print(f"Reading cache: {cache_file}")

    for quote in read_quotes(cache_file):
        print(f"  {quote.short()} — {quote.author}")


if __name__ == "__main__":
    main()

Run it twice. The first run fetches from the internet. The second run reads the file, and is instant. That small change is what a cache is.

"""quotes.py — fetch quotes once, then read them from a local file.

    pip install requests
    python quotes.py
"""
import json
import time
from pathlib import Path
from typing import Iterator

import requests

CACHE_DIR = Path("cache")


def timed(fn):                                          # 3. 装饰器
    """Print how long the wrapped function takes."""
    def wrapper(*args, **kwargs):
        start = time.time()
        result = fn(*args, **kwargs)
        print(f"[{fn.__name__} took {time.time() - start:.2f}s]")
        return result
    return wrapper


class Quote:                                            # 1. 类
    """One quote and the person who said it."""

    def __init__(self, text: str, author: str):         # 4. 类型提示
        self.text = text
        self.author = author

    def short(self, limit: int = 50) -> str:
        """The quote, cut to `limit` characters."""
        if len(self.text) <= limit:
            return self.text
        return self.text[:limit - 3] + "..."


@timed
def fetch_quotes(count: int) -> list[dict]:             # 7. requests
    """Ask the API for `count` quotes."""
    r = requests.get(
        "https://dummyjson.com/quotes",
        params={"limit": count},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()["quotes"]


def read_quotes(path: Path) -> Iterator[Quote]:         # 2. 生成器
    """Read the saved file, one Quote at a time."""
    data = json.loads(path.read_text(encoding="utf-8"))  # 6. json
    for item in data:
        yield Quote(item["quote"], item["author"])


def main() -> None:
    CACHE_DIR.mkdir(exist_ok=True)                      # 5. pathlib
    cache_file = CACHE_DIR / "quotes.json"

    if not cache_file.exists():
        print("No cache. Fetching...")
        quotes = fetch_quotes(5)
        cache_file.write_text(
            json.dumps(quotes, indent=2, ensure_ascii=False),
            encoding="utf-8",
        )
    else:
        print(f"Reading cache: {cache_file}")

    for quote in read_quotes(cache_file):
        print(f"  {quote.short()} — {quote.author}")


if __name__ == "__main__":
    main()

Start with the notebook. It has all of this as runnable cells, plus eight exercises with answers.

• python_toolkit.ipynb — this page, but you can run and change every line.
• Lesson 1 — Start Python on a Mac — go back here if the Terminal, functions or imports still feel unfamiliar.
• python_basics.ipynb — the language itself, with an exercise after every section.
• python_apis_async.ipynb — decorators and requests again, then async / await.
• python_next_steps.ipynb — modules, file I/O, try/except, comprehensions.
• Official docs, all short and worth reading in full: pathlib, json, requests quickstart.

One project to try: point the capstone script at a different API. Change the URL, the params, and the keys you read from the JSON. Almost nothing else needs to change. That is the point.