Module và Package

"""Vài phép toán tiện dụng."""

PI = 3.14159

def dien_tich_tron(r: float) -> float:
    return PI * r ** 2

def chu_vi_tron(r: float) -> float:
    return 2 * PI * r

def _lam_tron(x: float) -> float:
    """Hàm nội bộ — dấu _ đầu tên là quy ước 'đừng dùng từ ngoài'."""
    return round(x, 2)

import toan_hoc

print(toan_hoc.PI)                    # 3.14159
print(toan_hoc.dien_tich_tron(2))    # 12.56636
print(toan_hoc.__name__)              # 'toan_hoc'
print(toan_hoc.__file__)              # /duong/dan/toan_hoc.py
print(toan_hoc.__doc__)               # 'Vài phép toán tiện dụng.'

# ① import module — namespace giữ nguyên, rõ ràng nhất
import json
data = json.loads('{"a": 1}')

# ② import ... as ... — đổi tên, tránh trùng hoặc rút gọn
import numpy as np
import xml.etree.ElementTree as ET

# ③ from ... import ... — kéo tên cụ thể vào namespace hiện tại
from pathlib import Path
from collections import Counter, defaultdict
p = Path("data.csv")          # không cần tiền tố pathlib.

# ④ from ... import * — kéo TẤT CẢ. Gần như luôn là ý tồi.
from math import *
print(sqrt(16))                # 4.0 — nhưng pi, e, floor, ceil... cũng vừa tràn vào

print("⚠️ Tôi chạy ngay khi ai đó import module này!")

ket_noi = tao_ket_noi_db()   # ⚠️ mở kết nối lúc import — rất tệ

def an_toan():
    print("tôi chỉ chạy khi được gọi")   # ✅ code trong hàm thì không

import sys

import on_ao      # in "⚠️ Tôi chạy ngay..."
import on_ao      # im lặng — lấy từ cache
import on_ao      # im lặng

print("on_ao" in sys.modules)          # True
print(sys.modules["on_ao"] is on_ao)   # True — cùng một object
print(len(sys.modules))                # ~70 module đã nạp sẵn khi khởi động

"""Vài phép toán tiện dụng."""

PI = 3.14159

def dien_tich_tron(r: float) -> float:
    return PI * r ** 2

def main() -> None:
    """Điểm vào khi chạy trực tiếp."""
    import sys
    r = float(sys.argv[1]) if len(sys.argv) > 1 else 1.0
    print(f"Diện tích hình tròn bán kính {r}: {dien_tich_tron(r):.2f}")

if __name__ == "__main__":
    main()

$ python toan_hoc.py 3
Diện tích hình tròn bán kính 3.0: 28.27

$ python -c "import toan_hoc; print(toan_hoc.dien_tich_tron(1))"
3.14159          # main() KHÔNG chạy khi import

cua_hang/
├── __init__.py          # biến thư mục thành package
├── san_pham.py          # cua_hang.san_pham
├── gio_hang.py          # cua_hang.gio_hang
└── thanh_toan/          # sub-package
    ├── __init__.py
    ├── the_tin_dung.py  # cua_hang.thanh_toan.the_tin_dung
    └── vi_dien_tu.py    # cua_hang.thanh_toan.vi_dien_tu

import cua_hang.san_pham
cua_hang.san_pham.tim("laptop")

from cua_hang import san_pham
san_pham.tim("laptop")

from cua_hang.thanh_toan import the_tin_dung
the_tin_dung.thanh_toan(100_000)

from cua_hang.thanh_toan.the_tin_dung import thanh_toan
thanh_toan(100_000)

"""Thư viện quản lý cửa hàng."""

# ① Định nghĩa metadata của package
__version__ = "1.2.0"

# ② Nâng API con lên mặt tiền — người dùng gõ ngắn hơn
from cua_hang.san_pham import SanPham, tim
from cua_hang.gio_hang import GioHang

# ③ Khai báo public API tường minh
__all__ = ["SanPham", "GioHang", "tim"]

# Nhờ ② người dùng viết được:
#   from cua_hang import SanPham       ← thay vì cua_hang.san_pham.SanPham

# ✅ ABSOLUTE — nêu đường dẫn đầy đủ từ gốc
from cua_hang.san_pham import SanPham
from cua_hang.thanh_toan.vi_dien_tu import ViDienTu

# RELATIVE — nêu vị trí tương đối so với module hiện tại
from .san_pham import SanPham              # . = cùng package (cua_hang)
from .thanh_toan.vi_dien_tu import ViDienTu  # đi xuống sub-package
from ..tien_ich import dinh_dang           # .. = package cha

import sys

for i, p in enumerate(sys.path):
    print(f"{i}. {p or '(thư mục hiện tại)'}")

# 0. /duong/dan/toi/script          ← thư mục chứa file đang chạy
# 1. /usr/lib/python312.zip
# 2. /usr/lib/python3.12
# 3. /usr/lib/python3.12/lib-dynload
# 4. /duong/dan/.venv/lib/python3.12/site-packages   ← pip install vào đây

"""Điểm vào CLI của package: python -m cua_hang"""
import sys
from cua_hang.gio_hang import GioHang

def main(argv: list[str] | None = None) -> int:
    argv = argv if argv is not None else sys.argv[1:]
    gio = GioHang()
    for ma in argv:
        gio.them(ma)
    print(f"Tổng: {gio.tong_tien():,}đ")
    return 0

if __name__ == "__main__":
    sys.exit(main())

du-an-cua-toi/
├── pyproject.toml           # metadata + dependency (Chương 1)
├── README.md
├── .gitignore
├── src/
│   └── cua_hang/            # package thật nằm trong src/
│       ├── __init__.py
│       ├── __main__.py      # python -m cua_hang
│       ├── san_pham.py
│       ├── gio_hang.py
│       └── thanh_toan/
│           ├── __init__.py
│           └── the_tin_dung.py
└── tests/
    ├── test_san_pham.py
    └── test_gio_hang.py

[project]
name = "cua-hang"
version = "1.2.0"
requires-python = ">=3.12"
dependencies = ["httpx>=0.27"]

[project.scripts]
cua-hang = "cua_hang.__main__:main"   # tạo lệnh `cua-hang` trong terminal

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/cua_hang"]        # chỉ cho build backend biết package ở đâu

$ uv pip install -e .        # hoặc: pip install -e .
$ python -c "import cua_hang; print(cua_hang.__version__)"
1.2.0
$ cua-hang SP001 SP002       # lệnh sinh từ [project.scripts]
Tổng: 500,000đ

# nguoi_dung.py
from don_hang import DonHang

class NguoiDung:
    def don_hang_moi_nhat(self) -> DonHang: ...

# don_hang.py
from nguoi_dung import NguoiDung      # ⚠️ vòng!

class DonHang:
    def chu_don(self) -> NguoiDung: ...

# ImportError: cannot import name 'DonHang' from partially initialized module
#              'don_hang' (most likely due to a circular import)

# don_hang.py
from __future__ import annotations   # hoãn đánh giá annotation
from typing import TYPE_CHECKING

if TYPE_CHECKING:                       # False lúc runtime, True với mypy/Pylance
    from nguoi_dung import NguoiDung

class DonHang:
    def chu_don(self) -> NguoiDung:      # chỉ là chuỗi lúc runtime → không cần import thật
        from nguoi_dung import tim_theo_id   # import thật ở đây, khi module đã nạp xong
        return tim_theo_id(self.chu_don_id)