Kiến trúc thư viện
Cập nhật lần cuối:
Thảo luậnGiới thiệu
Thư viện `vnstock_data` được thiết kế với cấu trúc hướng mô-đun, dễ mở rộng, dễ tích hợp, và dễ chuyển đổi nguồn dữ liệu chỉ qua một tham số cấu hình.
Đây là bộ công cụ dữ liệu chứng khoán - kinh tế - tài sản toàn diện, sẵn sàng hỗ trợ bạn xây dựng mọi sản phẩm từ phân tích, giao dịch, đến dự báo thị trường.
Kiến trúc hệ thống
Triết Lý Thiết Kế
| Đặc điểm | Ý nghĩa |
|---|---|
| Adapter Pattern | Một chuẩn giao tiếp duy nhất, dễ dàng thay đổi nhà cung cấp dữ liệu thông qua các hàm hoạt động như adapter trung gian. |
| Phân lớp rõ ràng | Mỗi lớp đại diện cho một nhóm dữ liệu chuyên biệt: Quote, Trading, Finance, v.v. |
| Tương lai mở rộng | Thêm nguồn mới không làm phá vỡ cấu trúc của thư viện trong tương lai. |
| Tối ưu hiệu suất & bảo trì | Quản lý dễ dàng các thay đổi nguồn cấp, cập nhật tính năng mới linh hoạt. |
Hướng Dẫn Sử Dụng
Gợi ý
`vnstock_data` hỗ trợ **2 cách tiếp cận** khi gọi dữ liệu, phù hợp cho cả nhu cầu linh hoạt lẫn nhu cầu ổn định.
Gọi hàm qua Adapter chung
Tối ưu cho sự linh hoạt và khả năng hoán đổi nguồn dữ liệu.
Bạn khởi tạo lớp với tham số source, và sử dụng hàm tương ứng.
Điều này cho phép dễ dàng chuyển đổi giữa các nguồn mà không cần sửa đổi code nhiều.
from vnstock_data import Quote, Trading, Finance, Listing, Company, CommodityPrice, Macro quote = Quote(source="vci", symbol="VCI") df = quote.history(start="2024-02-01", end="2025-04-18", interval="1D") df.head()
✅ Ưu điểm:
- Linh hoạt thay đổi
sourcetheo nhu cầu (ví dụ: VCI ➔ VND ➔ MAS...). - Một chuẩn code chung áp dụng cho nhiều nhà cung cấp.
⚠️ Lưu ý:
- Không phải nguồn nào cũng hỗ trợ đầy đủ tất cả các phương thức.
- Nếu nguồn không hỗ trợ hàm gọi, sẽ có thông báo lỗi (
NotImplementedError).
📌 Tham khảo: Sơ đồ kiến trúc & bảng tra cứu nguồn dữ liệu để biết nguồn nào hỗ trợ hàm nào.
Gọi hàm qua Module Nguồn Dữ Liệu
Tối ưu cho sự ổn định và kiểm soát chặt chẽ.
Bạn import trực tiếp từ module nội bộ của nhà cung cấp (ví dụ explorer.vci, explorer.mas,...).
from vnstock_data.explorer.vci import Quote, Trading, Finance, Listing, Company quote = Quote(symbol="VCI") df = quote.history(start="2024-02-01", end="2025-04-18", interval="1D") df.head()
✅ Ưu điểm:
- Tránh lỗi "không hỗ trợ" vì đã cố định nguồn.
- Phù hợp khi bạn biết chắc mình chỉ làm việc với một nhà cung cấp nhất định.
⚡ Khuyến nghị:
- Dùng cách này trong các hệ thống production cần sự ổn định cao.
- Hoặc khi cần tận dụng các tính năng riêng biệt của từng nguồn.
Tra cứu các loại dữ liệu & nguồn cấp
Mỗi lớp (Adapter) được thiết kế để phục vụ cho các nghiệp vụ cụ thể.
Dưới đây là bảng tổng hợp toàn bộ phương thức theo từng lớp và nhà cung cấp hỗ trợ:
Phương Thức Của Lớp Listing
Tra cứu mã chứng khoán, phân ngành, chỉ số, trái phiếu, chứng quyền.
| Phương thức | VCI | VND | Mô tả |
|---|---|---|---|
| all_symbols | ✅ | ✅ | Danh sách chứng khoán niêm yết |
| industry | ✅ | ❌ | Phân ngành |
| symbols_by_industries | ✅ | ❌ | Mã chứng khoán theo phân ngành ICB |
| symbols_by_exchange | ✅ | ❌ | Mã chứng khoán theo sàn giao dịch |
| industries_icb | ✅ | ❌ | Danh sách phân ngành ICB |
| symbols_by_group | ✅ | ❌ | Mã chứng khoán theo nhóm, ví dụ VN30, VN100, vv |
| all_future_indices | ✅ | ❌ | Tất cả mã chỉ số hợp đồng tương lai |
| all_government_bonds | ✅ | ❌ | Tất cả mã trái phiếu chính phủ |
| all_covered_warrant | ✅ | ❌ | Tất cả mã chứng quyền |
| all_bonds | ✅ | ❌ | Tất cả mã trái phiếu doanh nghiệp |
Phương Thức Của Lớp Company
Khai thác thông tin chi tiết về từng doanh nghiệp.
| Phương thức | VCI | MAS | Mô tả |
|---|---|---|---|
| overview | ✅ | Tổng quan doanh nghiệp | |
| shareholders | ✅ | Cổ đông lớn | |
| officers | ✅ | Ban lãnh đạo | |
| subsidiaries | ✅ | Công ty con | |
| affiliate | ✅ | Công ty liên kết | |
| news | ✅ | Tin tức doanh nghiệp | |
| events | ✅ | Sự kiện doanh nghiệp | |
| reports | ✅ | Báo cáo phân tích | |
| trading_stats | ✅ | Thống kê giao dịch | |
| ratio_summary | ✅ | Tóm tắt chỉ số tài chính |
Phương Thức Của Lớp Finance
Tập trung vào dữ liệu báo cáo tài chính đã chuẩn hóa & chỉ số phân tích.
| Phương thức | VCI | MAS | Mô tả |
|---|---|---|---|
| balance_sheet | ✅ | ✅ | Bảng cân đối kế toán |
| income_statement | ✅ | ✅ | Báo cáo kết quả kinh doanh |
| cashflow | ✅ | ✅ | Báo cáo lưu chuyển tiền tệ |
| ratio | ✅ | ✅ | Chỉ số tài chính |
| annual_plan | ❌ | ✅ | Kế hoạch năm |
Phương Thức Của Lớp Quote
Theo dõi diễn biến giá theo thời gian.
| Phương thức | VCI | MAS | VND | Mô tả |
|---|---|---|---|---|
| history | ✅ | ✅ | ✅ | Dữ liệu giá lịch sử |
| intraday | ✅ | ✅ | ❌ | Dữ liệu giá trong ngày |
| price_depth | ✅ | ✅ | ❌ | Thống kê bước giá & khối lượng |
Phương Thức Của Lớp Trading
Khai thác dữ liệu giao dịch, khối lượng, đặt lệnh.
| Phương thức | VCI | CafeF | Mô tả |
|---|---|---|---|
| price_board | ✅ | ❌ | Thông tin bảng giá |
| trading_stats | ✅ | ❌ | Thống kê lịch sử giao dịch |
| side_stats | ✅ | ❌ | Dữ liệu cung cầu |
| price_history | ❌ | ✅ | Lịch sử giá |
| foreign_trade | ❌ | ✅ | Lịch sử giao dịch khối ngoại |
| prop_trade | ❌ | ✅ | Lịch sử giao dịch tự doanh |
| order_stats | ❌ | ✅ | Thống kê đặt lệnh |
| insider_deal | ❌ | ✅ | Giao dịch nội bộ và cổ đông lớn |
Phương Thức Của Lớp Market
Thông tin định giá thị trường theo thời gian
| Phương thức | VND | Mô tả |
|---|---|---|
| pe | ✅ | Chỉ số định giá thị trường P/E |
| pb | ✅ | Chỉ số định giá thị trường P/B |
| evaluation | ✅ | Lịch sử định giá thị trường |
Phương Thức Của Lớp Insights
Thống kê thị trường theo danh sách top cổ phiếu
| Phương thức | VND | Mô tả |
|---|---|---|
| gainer | ✅ | Top cổ phiếu tăng giá |
| loser | ✅ | Top cổ phiếu giảm giá |
| value | ✅ | Top cổ phiếu theo giá trị giao dịch |
| volume | ✅ | Top cổ phiếu theo KLGD |
| deal | ✅ | Top cổ phiếu theo giao dịch thỏa thuận |
| foreign_buy | ✅ | Top cổ phiếu NĐTNN mua ròng |
| foreign_sell | ✅ | Top cổ phiếu NĐTNN bán ròng |
Phương Thức Của Lớp Macro
Dữ liệu kinh tế vĩ mô
| Phương thức | MBK | Mô tả |
|---|---|---|
gdp | ✅ | Lấy chuỗi thời gian GDP theo quý/năm |
cpi | ✅ | Lấy chỉ số giá tiêu dùng (CPI) theo tháng/năm |
industry_prod | ✅ | Lấy chỉ số sản xuất công nghiệp theo tháng/năm |
import_export | ✅ | Lấy số liệu xuất – nhập khẩu hàng hóa theo tháng/năm |
retail | ✅ | Lấy doanh thu bán lẻ tiêu dùng theo tháng/năm |
fdi | ✅ | Lấy vốn đầu tư trực tiếp nước ngoài (FDI) theo tháng/năm |
money_supply | ✅ | Lấy số liệu cung tiền theo tháng/năm |
exchange_rate | ✅ | Lấy tỷ giá ngoại tệ (ví dụ USD/VND) theo ngày/năm |
population_labor | ✅ | Lấy thống kê dân số và lao động theo tháng/năm |
Phương Thức Của Lớp Commodity
Dữ liệu thị trường hàng hóa
| Phương thức | SPL | Mô tả |
|---|---|---|
gold_vn | ✅ | Lịch sử giá vàng giao dịch tại Việt Nam |
gold_global | ✅ | Lịch sử giá vàng trên thị trường quốc tế |
gas_vn | ✅ | Lịch sử giá xăng và dầu diesel tại Việt Nam |
oil_crude | ✅ | Lịch sử giá dầu thô trên thị trường thế giới |
gas_natural | ✅ | Lịch sử giá khí thiên nhiên |
coke | ✅ | Lịch sử giá than cốc phục vụ luyện kim |
steel_d10 | ✅ | Lịch sử giá thép thanh vằn D10 tại Việt Nam |
iron_ore | ✅ | Lịch sử giá quặng sắt trên thị trường quốc tế |
steel_hrc | ✅ | Lịch sử giá thép cuộn cán nóng (Hot-Rolled Coil, HRC) |
fertilizer_ure | ✅ | Lịch sử giá phân bón Urê |
soybean | ✅ | Lịch sử giá đậu nành trên thị trường quốc tế |
corn | ✅ | Lịch sử giá ngô (bắp) trên thị trường quốc tế |
sugar | ✅ | Lịch sử giá đường trên thị trường quốc tế |
pork_north_vn | ✅ | Lịch sử giá lợn (heo) hơi tại vùng miền Bắc Việt Nam |
pork_china | ✅ | Lịch sử giá lợn (heo) hơi tại thị trường Trung Quốc |
Thảo luận