JSON katika Python: kusoma na kuandika faili, CSV, pathlib na usimbaji UTF-8

Kufanya kazi na JSON katika Python hakuhitaji maktaba za nje: moduli json ipo katika maktaba ya kawaida na inageuza kamusi na orodha kuwa maandishi na kurudi tena. Karibu na hiyo mara nyingi unahitaji vitu vitatu zaidi: kazi open pamoja na muundo wa with, moduli pathlib kwa njia za faili, na moduli csv kwa majedwali. Hapa chini ni yote kwa mpangilio, pamoja na msimbo unaofanya kazi na mitego ambayo watu wengi hukwama nayo.

Kazi ya open katika Python: njia na usimbaji

Faili lolote la maandishi hufunguliwa kwa kazi iliyojengwa ndani open(path, mode, encoding=...). Inarudisha kitu cha faili chenye mbinu read, readline na write, na unaweza kukipitia kwa mzunguko mstari kwa mstari.

Kwa nini with inahitajika

Faili linapaswa kufungwa: vinginevyo data inaweza isifike diskini, na mfumo unaendelea kushikilia kipini cha faili. Muundo wa with hufunga faili kiotomatiki — hata kama kulitokea kosa ndani ya kizuizi.

with open("notes.txt", "w", encoding="utf-8") as f:
    f.write("Mstari wa kwanza\n")
    f.write("Mstari wa pili\n")

with open("notes.txt", encoding="utf-8") as f:
    for line in f:
        print(line.rstrip("\n"))

Kupitia faili kwa mzunguko husoma mstari mmoja kwa wakati na hakupakii faili lote kwenye kumbukumbu, kwa hiyo hata logi za gigabaiti zinaweza kuchakatwa hivyo. Mbinu f.read() itarudisha maudhui yote kama mfuatano mmoja, na f.readlines() — orodha ya mistari.

Jinsi ya kuandika mstari kwenye faili bila kufuta ya zamani

Kosa la kawaida la mwanzo ni kufungua faili kwa "w" ili "kuongeza" mstari. Hali "w" inafuta faili wakati wa kufunguliwa, kabla ya write ya kwanza. Ili kuongeza rekodi mwishoni tumia "a", na ili kuhakikisha hautaandika juu ya faili la mtu mwingine — "x".

with open("log.txt", "a", encoding="utf-8") as f:
    f.write("rekodi mpya\n")

Kumbuka kwamba write haiongezi mstari mpya yenyewe — "\n" inaandikwa waziwazi. Pia unaweza kutumia print(..., file=f): itaweka mwisho wa mstari kwa ajili yako.

Usimbaji UTF-8: kwa nini herufi zinaharibika

Kabla ya Python 3.15, kazi open() bila parameta encoding ilitumia usimbaji wa mfumo. Kwenye Linux na macOS hiyo ni UTF-8, lakini kwenye Windows inaweza kuwa cp1252 au nyingine. Skripti iliyofanya kazi vizuri kwenye seva, kwenye kompyuta ya mwenzako ilionyesha herufi zisizo sahihi (mojibake) au ilianguka kwa UnicodeDecodeError.

Katika Python 3.15, kwa PEP 686, hali ya UTF-8 imewashwa kwa chaguo-msingi: open() bila encoding inasoma na kuandika UTF-8 kwenye mifumo yote. Tabia ya zamani inaweza kurudishwa kwa kigezo cha mazingira PYTHONUTF8=0 au bendera -X utf8=0, na kuomba waziwazi usimbaji wa mfumo — encoding="locale".

import sys
print(sys.flags.utf8_mode)   # 1 katika Python 3.15

open("legacy.txt", encoding="locale")     # usimbaji wa mfumo
open("old_excel.csv", encoding="cp1252")  # faili lililohifadhiwa kwa cp1252

Upande wa pili: CSV ya zamani kutoka Excel au skripti ya Windows, iliyohifadhiwa kwa cp1252, sasa itasomwa kama UTF-8 na kusababisha UnicodeDecodeError. Suluhisho: lisome kwa encoding="cp1252" kisha liandike upya kwa UTF-8. Kanuni nzuri haibadiliki — taja encoding waziwazi, basi msimbo unafanya kazi vivyo hivyo kwenye toleo lolote.

pathlib katika Python: njia kama vitu

Kuunganisha njia kwa mifuatano ("data" + "/" + name) ni ngumu na huvunjika kwenye mifumo tofauti. Moduli pathlib inatoa darasa Path, ambapo njia zinaunganishwa kwa opereta /, na kitu kina sifa zilizo wazi.

from pathlib import Path

data = Path("data")
csv_path = data / "expenses.csv"

print(csv_path.name)    # expenses.csv
print(csv_path.stem)    # expenses
print(csv_path.suffix)  # .csv
print(csv_path.parent)  # data
print(csv_path.exists())

data.mkdir(parents=True, exist_ok=True)
(data / "hello.txt").write_text("Habari", encoding="utf-8")
print((data / "hello.txt").read_text(encoding="utf-8"))

for p in data.glob("*.csv"):
    print(p)

Mbinu read_text na write_text zinachukua nafasi ya mchanganyiko wa open + with kwa faili ndogo. Kitu cha Path kinaweza kupitishwa kwa open ya kawaida, kwa json na kwa csv — zote zinakipokea. Njia inayohusiana na skripti yenyewe, si folda ya sasa, hupatikana hivi: Path(__file__).parent / "data".

Katika Python 3.14 Path imepata mbinu copy() na move(), kwa hiyo kwa kunakili rahisi shutil haihitajiki tena. Katika toleo hilohilo maktaba ya kawaida imeongeza moduli compression.zstd kwa mbano ya Zstandard (PEP 784).

JSON katika Python: load, dump, loads, dumps

JSON ni muundo wa maandishi wa kubadilishana data: API hutuma data kwa JSON, na mipangilio na ripoti huhifadhiwa humo. Moduli json inafanya shughuli mbili: serialization (kitu cha Python → maandishi ya JSON) na deserialization (maandishi → kitu). Mbinu ni nne, na kuchanganyikiwa kati yake ni swali la kawaida.

Ni rahisi kukumbuka: herufi s mwishoni inamaanisha string — kazi na mfuatano; bila hiyo — kazi na faili.

Ulinganifu wa aina

Tuple ikisomwa tena itakuwa orodha, lakini seti, tarehe na Decimal moduli haizijui na itatoa TypeError: Object of type ... is not JSON serializable.

Jinsi ya kuhifadhi JSON kwenye faili

import json
from pathlib import Path

report = {
    "month": "2026-10",
    "total": 15230.5,
    "categories": {"chakula": 8200, "usafiri": 2100},
    "tags": ["nyumbani", "kazi"],
}

path = Path("data/report.json")
path.parent.mkdir(parents=True, exist_ok=True)
with path.open("w", encoding="utf-8") as f:
    json.dump(report, f, ensure_ascii=False, indent=2)

Parameta ensure_ascii=False huhifadhi herufi za lugha yako kama zilivyo. Bila hiyo, badala ya "chakula" faili litakuwa na "c..." — JSON sahihi, lakini ni vigumu kwa binadamu kuisoma. indent=2 hupanga muundo kwa mikunjo.

Jinsi ya kusoma JSON kutoka faili

with open("data/report.json", encoding="utf-8") as f:
    data = json.load(f)

print(data["total"])               # 15230.5
print(data["categories"]["chakula"])   # 8200

Matokeo ni kamusi au orodha ya kawaida, na unaifanyia kazi kwa zana za kawaida. Faili lisilo JSON au lililokatika litasababisha json.JSONDecodeError yenye namba ya mstari na nafasi — inafaa kuikamata pale data inapotoka nje.

Kuchambua mfuatano wa JSON na uchapishaji mzuri

import json

raw = '{"name": "Amina", "skills": ["python", "sql"], "active": true}'
user = json.loads(raw)
print(user["skills"][0])   # python

print(json.dumps(user, ensure_ascii=False, indent=2, sort_keys=True))

sort_keys=True hupanga funguo wakati wa kutoa matokeo — ni muhimu ili kulinganisha faili kwenye git. Kwa kupanga faili haraka kutoka terminal kuna zana iliyojengwa ndani: python -m json.tool data/report.json.

Jibu la HTTP API pia ni mfuatano wa JSON. Maktaba ya requests huichambua kwa mbinu response.json(), na ndani yake ni json.loads ile ile.

Mtego: funguo za JSON daima ni mifuatano

d = {1: "januari", 2: "februari"}
back = json.loads(json.dumps(d))
print(back == d)   # False
print(back)        # {'1': 'januari', '2': 'februari'}
# back[1] -> KeyError, inahitajika back["1"]

fixed = {int(k): v for k, v in back.items()}

Katika JSON funguo za kitu zinaweza kuwa mifuatano tu, kwa hiyo funguo za namba baada ya mzunguko wa serialization zinageuka kuwa mifuatano. Zirejeshe kuwa namba unaposoma.

Aina zako mwenyewe: tarehe na Decimal

import json
from datetime import date

def default(obj):
    if isinstance(obj, date):
        return obj.isoformat()
    raise TypeError(f"siwezi kuweka {type(obj).__name__} kwenye mfuatano")

print(json.dumps({"day": date(2026, 10, 1)}, default=default))
# {"day": "2026-10-01"}

Kazi iliyo kwenye parameta default huitwa kwa kila kitu kisichojulikana. Kwa visa tata unaweza kurithi kutoka json.JSONEncoder na kubadilisha mbinu default.

Jinsi ya kuongeza kipengele kwenye safu ya JSON

JSON haiwezi kuongezwa mwishoni kama logi ya maandishi: faili linapaswa kusomwa, kubadilishwa na kuandikwa upya kwa ujumla.

path = Path("data/items.json")
items = json.loads(path.read_text(encoding="utf-8")) if path.exists() else []
items.append({"id": len(items) + 1, "title": "mpya"})
path.write_text(json.dumps(items, ensure_ascii=False, indent=2), encoding="utf-8")

Ikiwa rekodi ni nyingi na zinaongezwa kila mara, muundo wa JSON Lines ni rahisi zaidi: kitu kimoja cha JSON kwa mstari, na faili linafunguliwa kwa hali "a".

CSV katika Python: moduli csv

CSV ni jedwali katika faili la maandishi: mistari ni rekodi, thamani zimetenganishwa kwa koma. Moduli csv inashughulikia nukuu, koma ndani ya thamani na mivunjo ya mistari kwa usahihi, jambo ambalo split(",") ya kawaida haliwezi kufanya.

import csv

with open("data/expenses.csv", newline="", encoding="utf-8") as f:
    reader = csv.DictReader(f)
    total = 0.0
    for row in reader:
        total += float(row["amount"])
        print(row["date"], row["category"], row["amount"])
print("Jumla:", total)

csv.DictReader hugeuza kila mstari kuwa kamusi kwa kichwa cha faili. Thamani zote ni mifuatano: namba na tarehe zibadilishwe mwenyewe (float, int, date.fromisoformat). Faili lenye kitenganishi ";" (ambacho Excel ya Ulaya huhifadhi) husomwa kwa parameta delimiter=";".

rows = [
    {"date": "2026-10-01", "category": "chakula", "amount": 450},
    {"date": "2026-10-02", "category": "usafiri", "amount": 60},
]
with open("data/out.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.DictWriter(f, fieldnames=["date", "category", "amount"])
    writer.writeheader()
    writer.writerows(rows)

Wakati wa kuandika newline="" ni lazima: bila hiyo, kwenye Windows, mistari tupu itaonekana kati ya mistari. Ikiwa faili litafunguliwa kwenye Excel, tumia encoding="utf-8-sig" — alama ya BOM inasaidia Excel kutambua UTF-8.

Kutoka CSV hadi JSON: mfano kamili

import csv
import json
from collections import defaultdict
from pathlib import Path

src = Path("data/expenses.csv")
dst = Path("data/report.json")

by_category = defaultdict(float)
with src.open(newline="", encoding="utf-8") as f:
    for row in csv.DictReader(f):
        by_category[row["category"]] += float(row["amount"])

report = {"total": sum(by_category.values()), "categories": dict(by_category)}
dst.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
print(dst.read_text(encoding="utf-8"))

Huu ndio msingi wa skripti yoyote ya ripoti: ingizo kutoka CSV, mkusanyiko kwenye kamusi, na pato kwa JSON.

Makosa ya kawaida

• FileNotFoundError — njia ni ya jamaa na inahesabiwa kutoka folda ya kuendesha, si kutoka skripti. Tumia Path(__file__).parent.
• Faili limefutwa — lilifunguliwa kwa "w" badala ya "a".
• UnicodeDecodeError — faili lina usimbaji mwingine; itaje waziwazi (cp1252, utf-8-sig).
• TypeError: Object of type set is not JSON serializable — badilisha kuwa orodha au pitisha default.
• KeyError baada ya kupakia JSON — funguo za namba zimekuwa mifuatano.
• Faili lako limeitwa json.py au csv.py — linafunika moduli ya kawaida, na import json itaingiza faili lako.

Hitimisho

Kwa JSON katika Python maktaba ya kawaida inatosha: json.load/json.dump kwa faili, loads/dumps kwa mifuatano, ensure_ascii=False na indent kwa matokeo yanayosomeka. Fungua faili kwa with pamoja na usimbaji ulio wazi, jenga njia kwa pathlib, na soma majedwali kwa csv.DictReader. Katika kozi ya Python mada hii inafundishwa kwa vitendo: kifuatiliaji cha matumizi kinasoma matumizi kutoka CSV na kuhifadhi ripoti kwenye JSON.