Bỏ qua đến nội dung chính
Mục lục

Package trong Python: thư mục module và __init__.py

AIDev Team · duyệt: Nguyễn Việt Chung

Bài 7/14 · Chương 9

Module, gói và môi trường

  • 6 phút
  • Cơ bản
  • Python 3.14
  • Cập nhật

Một package trong Python là một thư mục chứa nhiều module, có file __init__.py đánh dấu, để bạn import từng module theo đường dẫn chấm như lich_hoc.ngay_le. Khi dự án lớn dần, bạn tạo package để gom các module cùng chủ đề vào một chỗ thay vì để hàng chục file nằm lẫn cạnh file chính.

Cần biết trước: import và module và tự viết module.

Package là thư mục chứa module

Dự án lịch học dưới đây có một package tên lich_hoc, trong đó có hai module:

text
du_an/
├── main.py
└── lich_hoc/
    ├── __init__.py
    ├── ngay_le.py
    └── buoi_hoc.py

Tên thư mục là tên package, tên file bỏ .py là tên module, và dấu / trong đường dẫn thành dấu chấm khi import: lich_hoc/ngay_le.py là module lich_hoc.ngay_le. Package giống một tủ hồ sơ: tủ có tên, mỗi ngăn là một module, và bạn gọi một ngăn bằng tên tủ chấm tên ngăn.

Trên máy, bạn tạo thư mục và các file bằng trình soạn thảo. Trên trang này mỗi lần chạy bắt đầu trong một thư mục trống, nên ví dụ tự tạo thư mục bằng Path(...).mkdir(), ghi các file rồi mới import. Bài pathlib dạy kỹ hai việc tạo và ghi đó:

python
from pathlib import Path

Path("lich_hoc").mkdir()
Path("lich_hoc/__init__.py").write_text("", encoding="utf-8")
Path("lich_hoc/ngay_le.py").write_text(
    'NGAY_LE = {"01/01": "Tết", "02/09": "Quốc khánh"}\n',
    encoding="utf-8")

import lich_hoc.ngay_le
print(lich_hoc.ngay_le.NGAY_LE["02/09"])
from lich_hoc import ngay_le
print(len(ngay_le.NGAY_LE))

KẾT QUẢ

Quốc khánh
2

import lich_hoc.ngay_le bắt bạn viết đủ tên dài mỗi lần dùng, còn from lich_hoc import ngay_le cho bạn gọi ngắn ngay_le.NGAY_LE. File __init__.py ở đây để trống, vẫn đủ đánh dấu thư mục là một package.

Đổi ["02/09"] thành ["01/01"] rồi chạy lại: dòng đầu in Tết.

File __init__.py chạy khi import package

Lần đầu bạn import package hay một module bên trong nó, Python chạy __init__.py của package trước, rồi mới tới module:

python
from pathlib import Path

Path("lich_hoc").mkdir()
Path("lich_hoc/__init__.py").write_text(
    'print("Đang nạp package", __name__)\n', encoding="utf-8")
Path("lich_hoc/ngay_le.py").write_text(
    'print("Đang nạp module", __name__)\n', encoding="utf-8")

import lich_hoc.ngay_le
import lich_hoc.ngay_le

KẾT QUẢ

Đang nạp package lich_hoc
Đang nạp module lich_hoc.ngay_le

Mỗi dòng in một lần dù có hai lần import, giống module ở bài trước. Bên trong module của package, __name__ là tên đầy đủ có chấm, lich_hoc.ngay_le.

Import tương đối bên trong package

Module buoi_hoc cần dữ liệu ngày lễ của module ngay_le cùng package. Bên trong package, bạn viết from .ngay_le import NGAY_LE: dấu chấm đầu nghĩa là "trong package của chính file này", gọi là import tương đối. __init__.py cũng dùng cách đó để đưa hàm hay dùng ra ngay tên package:

python
from pathlib import Path
Path("lich_hoc").mkdir()
Path("lich_hoc/ngay_le.py").write_text(
    'NGAY_LE = ("01/01", "02/09")\n', encoding="utf-8")
ma_nguon = '''from .ngay_le import NGAY_LE

def co_hoc(ngay):
    return ngay not in NGAY_LE
'''
Path("lich_hoc/buoi_hoc.py").write_text(ma_nguon, encoding="utf-8")
Path("lich_hoc/__init__.py").write_text(
    "from .buoi_hoc import co_hoc\n", encoding="utf-8")

import lich_hoc
print(lich_hoc.co_hoc("02/09"), lich_hoc.co_hoc("05/09"))

KẾT QUẢ

False True

Nhờ dòng trong __init__.py, file chính chỉ cần import lich_hoc là gọi được lich_hoc.co_hoc(). Đổi tên package sau này cũng không phải sửa các dòng import bên trong, vì chúng chỉ nói "cùng package". Cách viết đầy đủ from lich_hoc.ngay_le import NGAY_LE vẫn đúng, gọi là import tuyệt đối.

Kiểm tra nhanh

  1. File tro_choi/xuc_xac/tung.py là module có tên import nào?

    • tro_choi/xuc_xac/tung
    • tro_choi.xuc_xac.tung
    • tung.py
  2. Trong ví dụ có hai dòng import lich_hoc.ngay_le, dòng nào được in trước?

    • Đang nạp package lich_hoc
    • Đang nạp module lich_hoc.ngay_le
    • Hai dòng in xen kẽ, mỗi lần import một cặp
  3. Với __init__.py để trống, sau import lich_hoc thì lich_hoc.ngay_le cho gì?

    • Module ngay_le
    • None
    • Báo lỗi AttributeError
  4. Dòng from .ngay_le import NGAY_LE dùng được ở đâu?

    • Trong lich_hoc/buoi_hoc.py, khi file chính import lich_hoc
    • Trong file chính main.py cạnh thư mục lich_hoc
    • Trong lich_hoc/__init__.py
    • Ở bất kỳ file nào, miễn có file ngay_le.py cùng thư mục
Đúng hết lần đầu +15 XP

Bài tập

Đổi đường dẫn file thành tên import

Viết thân hàm duong_dan_import(duong_dan): nhận đường dẫn một file .py trong dự án, các thư mục ngăn bằng dấu /, và trả về tên dùng sau import. Dấu / thành dấu chấm, đuôi .py bị bỏ, và file __init__.py đại diện cho chính thư mục chứa nó.

Ví dụ duong_dan_import("lich_hoc/ngay_le.py") trả về "lich_hoc.ngay_le", còn duong_dan_import("lich_hoc/__init__.py") trả về "lich_hoc".

Trả về: tên import, một str.

python
def duong_dan_import(duong_dan):
    pass  # Viết thân hàm thay cho dòng này

Tóm tắt

  • Package là thư mục chứa các module, có file __init__.py.

  • Module trong package import theo đường dẫn chấm: lich_hoc/ngay_le.py là lich_hoc.ngay_le.

  • __init__.py chạy một lần, trước mọi module con, ở lần import đầu.

  • import lich_hoc không tự nạp module con; import đúng module con hoặc nạp nó trong __init__.py.

  • Trong package, from .ngay_le import NGAY_LE là import tương đối; ở file chính nó báo ImportError.

Câu hỏi thường gặp

File __init__.py dùng để làm gì, có cần viết gì trong đó không?

__init__.py đánh dấu thư mục là package và chạy khi package được import lần đầu. Để trống là đủ. Bạn chỉ thêm vào đó dòng như from .buoi_hoc import co_hoc khi muốn gọi ngắn lich_hoc.co_hoc(), như ví dụ import tương đối ở trên. Đừng đặt việc nặng vào đó, vì nó chạy ngay ở lần import đầu, kể cả khi chỉ import một module con.

Tạo package Python để cài bằng pip thì sao?

Bài này tổ chức package trong dự án của bạn. Đóng gói để người khác cài bằng pip cần thêm file mô tả gói và là chủ đề riêng; việc cài một gói có sẵn từ PyPI ở bài pip install. Các module chuẩn như json hay email chính là package theo đúng cách bài này dạy, xem bài import.

Python package báo ModuleNotFoundError dù thư mục có thật?

Kiểm tra file chính có nằm cạnh thư mục package không, vì Python tìm package trong thư mục của file chính. Kiểm tra cả tên: thư mục lich-hoc có dấu gạch ngang không import được, đổi thành lich_hoc. Cách đọc lỗi này ở bài ModuleNotFoundError, và quy tắc đặt tên file ở bài tự viết module.

Chủ đề

python package

Bài này có hữu ích?

Hỏi đáp

Đang tải câu hỏi…

Tham vấn chuyên môn

Nguyễn Việt Chung

Nhà sáng lập AIDev và VietPlatform · Thạc sĩ AI MSE

  • Tốt nghiệp thủ khoa xuất sắc Thạc sĩ AI MSE.
  • Đồng sáng lập, CTO E-University, SVOnline: số hóa 10+ đại học, 40.000+ sinh viên.
  • Xây hệ thống AI cho doanh nghiệp tại VietPlatform.
Biên soạn: AIDev Team · Rà soát · Quy trình biên tập