Hướng dẫn đóng gói thư viện python và phân phối qua PyPI
I. GIỚI THIỆU
Năm 2021, khi tôi lần đầu tiên cố gắng đóng gói một gói Python (thư viện Python) của mình, với tên là "vnstock", tôi đã gặp khó khăn khi đọc các tài liệu hướng dẫn. Dù đã tìm hiểu qua các bài viết tiếng Anh và tiếng Việt, nhưng vẫn cảm thấy khá mơ hồ và phức tạp. Đến ngày hôm nay, khi tìm kiếm trên Google với từ khóa "cách tạo thư viện PyPI" hoặc "how to create pypi package", tôi vẫn chưa tìm thấy một hướng dẫn dễ hiểu và thực hiện, đặc biệt dành cho những người mới bắt đầu muốn chia sẻ thư viện Python của mình. Điều này đã thúc đẩy tôi quyết định dành thời gian chia sẻ bài viết và làm video hướng dẫn này, nhằm giúp nhiều người trải nghiệm việc chia sẻ mã nguồn Python mã nguồn mở một cách dễ dàng. Trong bài viết này, tôi sẽ hướng dẫn bạn cách đóng gói một thư viện Python dựa trên hướng dẫn gốc từ The Python Foundation Tại đây. Trong hướng dẫn này, quá trình tạo một gói python bắt đầu từ việc sử dụng 1 Github repo mẫu tên là py_packaging_template.
py_packaging_template
là một repo trên Github chứa cấu trúc mẫu của một thư viện Python, bạn có thể bắt đầu clone repo này về máy để thực hiện chỉnh sửa theo bài hướng dẫn này và phân phối thư viện python đầu tay của mình.
1.1. Vì sao cần đóng gói python package
Có nhiều lý do cho mục đích đóng gói và phân phối gói python package trong đó tôi làm rõ 2 lý do chính dưới đây:
Cho bạn: sử dụng các dự án của mình đã phát triển một cách dễ dàng. Bạn có thể dùng công cụ pip để cài đặt thư viện của mình trên bất kỳ thiết bị nào. Các đoạn code phức tạp bạn viết được đóng gói trong các hàm (function) để sẵn sàng import code vào dự án mới mà không cần lặp lại các đoạn code này giúp dự án của bạn trình bày thanh thoát và hiệu quả. Cho cộng đồng: chia sẻ tới cộng đồng sử dụng dự án bạn đã phát triển, công khai mã nguồn để cộng đồng có thể đóng góp phát triển.
1.2. Cấu trúc thư viện mẫu
Nội dung của thư viện này được clone từ một thư mục mà tôi chia sẻ tên là ur_gadget để bạn có thể hình dung thực tế 1 thư viện chứa những thông tin chính xác như thế nào. Thư viện này cũng đã được chia sẻ lên Pypi và Github.
Thư viện mẫu này bao gồm các thành phần sau:
py_packaging_template/
├─.gitattributes
├─.gitignore
├─code/
│ ├─datetime_intel.py
│ ├─gadget.py
│ └─__init__.py
└─src/
└─github_desktop_clone.png
├─LICENSE
├─README.md
├─pyproject.toml
├─setup.cfg
├─requirements.txt
Trong đó:
-
code/
chứa các file mã nguồn của thư viện -
src/
chứa các file tài nguyên đính kèm bao gồm hình ảnh, video, tài liệu hướng dẫn, ... -
LICENSE
: chứa thông tin về giấy phép sử dụng thư viện, trong trường hợp này là giấy phép MIT. -
README.md
: chứa thông tin về thư viện, cách cài đặt và sử dụng thư viện, đây là file người dùng đọc trước khi cài đặt thư viện và được hiển thị mặc định khi bạn chia sẻ thư viện lên Pypi. -
pyproject.toml
: cho biết các công cụ quản lý thư viện như pip và build sẽ sử dụng thêm các gói thư viện nào để tạo các gói thư viện của bạn khi người dùng cài đặt vào máy của họ. Bạn cần chỉ rõ các gói thư viện phụ thuộc (dependencies) trong file này. Hướng dẫn này sử dụng setuptools để tạo gói thư viện. -
setup.cfg
: chứa các thông tin cấu hình cho thư viện như tên thư viện, tác giả, phiên bản, ... -
requirements.txt
: chứa các gói thư viện cần thiết để phát triển thư viện, trong trường hợp này là setuptools và wheel. Bạn có thể chỉ rõ các gói thư viện khác nếu cần thiết, thông thường khi bạn tham chiếu một thư viện python không có sẵn khi cài đặt Python, bạn cần chỉ rõ các gói thư viện này trong file này để người dùng cài đặt thư viện này mới có thể sử dụng thư viện của bạn.
II. HƯỚNG DẪN SỬ DỤNG
2.1. Clone repo này về máy của bạn
Trong hướng dẫn này, bạn có thể clone dự án về máy của mình thông qua 2 cách là dùng Terminal/Command Prompt hoặc Github Desktop.
a. Sử dụng Terminal / Command Prompt
Mở Terminal/Command Prompt
Di chuyển đến thư mục bạn muốn lưu trữ dự án với lệnh
cd ĐƯỜNG_DẪN_TỚI_THƯ_MỤC. Ví dụ: cd C:\Users\thinh\Github\
Clone dự án về máy của bạn với lệnh
git clone https://github.com/thinh-vu/py_packaging_template.git
Chờ một lát, bạn sẽ thấy một thư mục mới được tạo ra với tên py_packaging_template bên trong thư mục bạn chọn để lưu trữ dự án.
b. Sử dụng Github Desktop
Nếu bạn chưa từng sử dụng Github Desktop, bước đầu tiên cần làm là cài đặt Github Desktop trên máy tính và đăng nhập với một tài khoản Github. Bạn có thể tải Github Desktop tại đây. Sử dụng Github (và Git nói chung) là một cách không thể thiếu để quản lý mã nguồn của bạn.
- Mở Github Desktop
- Chọn File > Clone repository
- Paste link của repo vào cửa sổ hiện ra và chọn thư mục lưu trữ dự án để tiếp tục