Chuyển đổi sang vnstock3
Trong hướng dẫn này bạn sẽ dễ dàng hình dung và làm quen cách sử dụng thư viện Vnstock3 khi chuyển đổi từ Vnstock legacy thế hệ trước đó.
Thay đổi quan trọng
Vnstock3 đem đến một trải nghiệm sử dụng mới, cấu trúc tốt và dễ sử dụng hơn. Tuy nhiên điều này chỉ phát huy giá trị khi bạn đã làm quen với cách tư duy mới, nắm bắt được cách thư viện được thiết kế và tận dụng được tối đa những ưu điểm vượt trội mà nó mang lại.
| Mục | Vnstock3 | Vnstock Legacy |
|---|---|---|
| Thiết kế hệ thống | OOP - Hướng đối tượng: Các hàm được tổ chức thành các Class (lớp) có cùng tính chất thông tin hoặc nhóm nội dung tương đồng. Việc này cho phép bạn gọi các hàm trong 1 Class dễ dàng hơn vói cú phám . (dot notation) để nhận gợi ý khi soạn thảo lệnh. Tên các hàm trở nên đơn giản và đồng bộ hơn khi đã được tổ chức phân cấp theo Class. Ví dụ: report.balance_sheet(), report.income_statement(), và report.cash_flow() cho phép tải 3 loại báo cáo tài chính cơ bản, thuộc cùng Class tên Finance | Hàm riêng lẻ: mỗi một hàm thực hiện 1 chức năng nhất định. Dù thông tin tương đồng, mỗi một hàm được đặt tên khác nhau để tránh trùng lặp. Việc này khiến người dùng bối rối và khó phân biệt. Ví dụ financial_report là hàm tải dữ liệu báo cáo tài chính từ nguồn SSI, còn financial_flow cho phép tải báo cáo từ TCBS. Trong Vnstock3, bạn chỉ cần thay đổi tham số source='VCI' hay source='TCBS' khi khởi tạo đối tượng để thay đổi nguồn cấp dữ liệu cho hàm trong khi cấu trúc hàm giữ nguyên. |
| Chuẩn hoá | Khi làm quen với Vnstock3 bạn sẽ nhận ra nỗ lực chuẩn hoá thông tin đến từ nhiều yếu tố như: tên gọi hàm/class, cách gọi hàm, kiểu dữ liệu đầu ra, định dạng dữ liệu, vv Việc tái cấu trúc và hướng đến tạo ra trải nghiệm sử dụng khoa học, dễ dàng hơn nhờ những trải nghiệm thực tế và kiến thức phát triển sản phẩm của tác giả qua thời gian. | Mức độ chuẩn hoá sơ sài, dù bạn có thể dễ dàng l àm quen và sử dụng nhưng chưa thể đạt đến mức độ tiện dụng, cách thường xuyên được sử dụng là tra cứu trang tài liệu và copy/paste mẫu lệnh vì bạn gần như khó có thể nhớ được danh sách các hàm một cách chính xác và giá trị các tham số cũng không đồng bộ. |
| Hệ thống website | Toàn bộ hệ thống website sẽ được chuyển đổi tên miền sang vnstocks.com thay cho trang chủ cũ tại tên miền vnstock.site. Việc này giúp giảm thiểm tác động tới dự án và ngừoi dùng khi chuyển đổi dịch vụ hosting quốc tế mất nhiều thời gian làm gián đoạn truy cập như khi mới triển khai Vnstock3 và đảm bảo không lặp lại trong tương lai. Trang web tại địa chỉ cũ vẫn sẽ được duy trì tới khi tên miền hết hạn. | Sử dụng tên miền vnstock.site, website sử dụng công nghệ khác nhau cho trang chủ và trang tài liệu khiến trải nghiệm người dùng kém linh hoạt. |
| Trang tài liệu | Vnstock3 sử dụng nền tảng website dựa trên framework Docusaurus, đem đến nhiều tính năng và trải nghiệm mới một cách linh hoạt hơn. Bạn cũng sẽ cần làm quen với việc điều hướng và nắm bắt cách bố trí thông tin theo cấu trúc mới để tiện tra cứu và sử dụng. | Trang tài liệu sử dụng nền tảng MkDocs, giao diện trực quan và dễ sử dụng tuy nhiên bị hạn chế nhiều tính năng kỹ thuật không còn đáp ứng được nhu cầu khi dự án cần nâng cấp và mở rộng. Bạn vẫn sẽ truy cập được trang tài liệu của bản legacy để sử dụng thư viện vnstock legacy trong thời gian các hàm cũ và thích hợp được tích hợp hoàn toàn trong Vnstock3. |
| Tương tác | Bạn sẽ cần làm quen với cách truy cập hàm mới theo đối tượng Python và tra cứu hướng dẫn sử dụng tích hợp sẵn tiện lợi hơn bên cạnh việc sử dụng code mẫu trong Jupyter Notebook. Việc này chỉ mất một thời gian rất ngắn để bạn nhận ra giá trị của sự thay đổi tất yếu trong Vnstock3. | Sử dụng trang tài liệu docs.vnstock.site là nơi tra cứu và tìm đoạn code mẫu kết hợp với file Demo trong Jupyter Notebook. |
| Giấy phép và bản quyền | Vnstock3 sử dụng giấy phép sử dụng tuỳ chỉnh, hạn chế quyền tái phân phối và sử dụng cho mục đích thương mại đối với tổ chức (cần xin tác giả chấp thuận theo trường hợp cụ thể). Việc này giúp minh bạch hoá việc sử dụng và giảm thiểu bất cân xứng nguồn lực của khi các tổ chức vốn có tiềm lực hoạt động sử dụng phần mềm nguồn mở được phát triển nhằm phổ cập sử dụng tới cộng đồng mà không bao gồm đóng góp phát triển bền vững. | Thư viện được phát hành theo giấy phép MIT tiêu chuẩn cho lưu hành phần mềm mã nguồn mở, bạn có thể làm bất kỳ điều gì với bộ mã nguồn được chia sẻ, điều kiện duy nhất là trích dẫn nguồn và tôn trọng bản quyền nội dung của tác giả. |
| Thoả thuận người dùng | Bạn cần chấp nhận điều khoản và điều kiện trong thoả thuận sử dụng phần mềm khi lần đầu tiên thư viện được chạy trên thiết bị. Điều này khuyến khích việc hiểu hơn về quyền và những điều kiện kèm theo khi bạn sử dụng phiên bản Vnstock3. Ngoài ra việc chấp nhận thoả thuận người dùng, bạn hiểu rằng Vnstock3 có thu thập dữ liệu ẩn danh về thông tin thiết bị cho mục đích phân tích và tối ưu hiệu năng thiết bị. Tất cả thông tin về dự án và tính năng ảnh hưởng tới ngừoi dùng đều được công bố công khai và minh bạch trên các kênh thông tin của Vnstock. | Thoả thuận đơn giản dựa trên giấy phép MIT, không ràng buộc hay giới hạn quyền sử dụng chặt chẽ. Không thu thập dữ liệu phân tích. |
| Gói phụ thuộc | Vnstock3 sử dụng thêm nhiều gói phần mềm phụ thuộc phổ biến trong Python. Mục tiêu phát triển của Vsntock3 hướng đến tạo ra trải nghiệm người dùng thú vị và hữu ích trong việc phân tích, giao dịch trong thị trường chứng khoán với bộ giải pháp hiện đại bằng ngôn ngữ lập trình Python. | Hướng đến sự đơn giản, dễ tiếp cận cho người dùng và xác định mức độ phù hợp của giải pháp trên thị trường hơn là một giải pháp toàn diện, mạnh mẽ. Chủ yếu sử dụng pandas và requests vốn có sẵn trong các bản phân phối Python phổ biến. |
| Tài liệu tích hợp | Các hàm trong Vnstock3 đều được viết hướng dẫn sử dụng bằng tiếng Việt ngay trong mã nguồn (docstring hiện ra khi bạn soạn thảo lệnh). Ngoài ra hàm help() cũng sẽ cung cấp khả năng tra cứu tài liệu tích hợp đ ể bạn tiện truy cập nhanh thay vì mở trang tài liệu. | Tài liệu tích hợp của các hàm được viết bằng tiếng Anh, bạn cần tra cứu trang tài liệu để xem hướng dẫn và ví dụ minh hoạ. |
| Nền tảng | Vnstock3 được chuẩn hoá và phát triển thành cơ sở nền tảng để Vnstock bổ sung các plugin và mở rộng tính năng sản phẩm trong giai đoạn mới. | Không thích hợp khi mở rộng thêm các tính năng sản phẩm yêu cầu mức độ chuẩn hoá cao. |
| Lưu trữ mã nguồn | Nhánh main của mã nguồn lưu trữ trên repo Github sẽ thể hiện bộ mã nguồn của Vnstock3 bên cạnh việc phát hành thư viện trên trang phân phối PyPI. | Nhánh main và beta của phiên bản legacy nay được gộp thành 1 nhánh duy nhất tên legacy trên trang repo dự án đặt tại Github. |
Tham chiếu các hàm tương đương
Gợi ý
Trong Vnstock3, các tính năng được phân cấp theo lớp (Class), logic thiết kế bám sát theo cách thức sử dụng lối 'top-down' tức bạn đi từ các phân nhóm tính năng rồi tới hàm chi tiết để truy cập dữ liệu bạn cần. Với logic này, việc gọi hàm trở nên dễ suy luận hơn, giảm thiểu gánh nặng nhập tham số cài đặt mà hầu hết chúng ta phải tra cứu tài liệu mới nhập đúng được thành việc gọi theo lớp và nhận gợi ý hàm con có trong lớp đó. Ví dụ bạn gọi lớp là report thì sau khi nhập . theo sau sẽ kích hoạt gợi ý các hàm tương ứng như balance_sheet, income_statement, cash_flow hay ratio thay vì phải gọi tên hàm dài khó nhớ và cần tra cứu tham số như trước.
| Danh mục | Tính năng | Hàm vnstock3 | Hàm Vnstock Legacy |
|---|---|---|---|
| Khởi tạo | Tạo đối tượng làm việc | stock = Vnstock().stock(symbol='ACB', source='VCI') | Không sử dụng. Các hàm hoạt động độc lập. |
| Thông tin niêm yết | Danh sách công ty | stock.listing.all_symbols() | listing_companies() |
| Danh sách các mã chỉ số | Chưa bổ sung | indices_listing () | |
| Mã CP theo sàn | stock.listing.symbols_by_exchange() | dùng chung hàm listing_companies() | |
| Mã CP theo ngành icb | stock.listing.symbols_by_industries() | dùng chung hàm listing_companies() | |
| Mã CP theo nhóm | stock.listing.symbols_by_group('VN30') | dùng chung hàm listing_companies() | |
| Danh sách ngành icb | stock.listing.industries_icb() | Không cung cấp | |
| Thông tin công ty | Tạo đối tượng | company = Company(symbol='TCB') | Không sử dụng |
| Tổng quan | company.overview() | company_overview('TCB') | |
| Hồ sơ | company.profile() | company_profile ('TCB') | |
| Cổ đông | company.shareholders() | company_large_shareholders ('TCB') | |
| Giao dịch nội bộ | company.insider_deals() | company_insider_deals (symbol='TCB') | |
| Công ty con | company.subsidiaries() | company_subsidiaries_listing (symbol='TCB') | |
| Lãnh đạo | company.officers() | company_officers (symbol='TCB') | |
| Sự kiện | company.events() | company_events (symbol='TCB') | |
| Tin tức | company.news() | company_news (symbol='TCB') | |
| Cổ tức | company.dividends() | sử dụng kèm hàm stock_screening_insights() | |
| Báo cáo tài chính | Khởi tạo | report = Finance(symbol='ACB', period='year') > sẽ bổ sung thêm Wrapper Class để chọn nguồn dữ liệu như 1 tham số từ đây | Không sử dụng |
| Chỉ số tài chính | report.ratio(lang='vi') | financial_ratio('TCB', 'yearly') | |
| Bảng CĐKT | report.balance_sheet(lang='vi') | financial_report (symbol='SSI', report_type='BalanceSheet', frequency='quarterly', periods=15, latest_year=None) | |
| Báo cáo kinh doanh | report.income_statement(lang='vi') | financial_report (symbol='SSI', report_type='IncomeStatement', frequency='Quarterly', periods=15, latest_year=None) | |
| Lưu chuyển tiền tệ | report.cash_flow(lang='vi') | financial_report (symbol='SSI', report_type='CashFlow', frequency='Quarterly', periods=15, latest_year=None) | |
| Giá | Bảng giá | stock.trading.price_board(['ACB']) | price_board() |
| Giá lịch sử (điều chỉnh) | stock.quote.history(start='2020-01-01', end='2024-12-31') | stock_historical_data("GMD", "2021-01-01", "2022-02-25", "1D", 'stock') | |
| Lịch sử khớp lệnh (intraday) | stock.quote.intraday(symbol='ACB') | stock_intraday_data(symbol='TCB') | |
| Giá vs khối lượng khớp | stock.quote.price_depth('ACB') | Không hỗ trợ | |
| Thị trường quốc tế | FX (nến) | fx.quote.history(start='2024-02-28', end='2024-05-10', interval='1D') | Không hỗ trợ |
| Crypto (nến) | crypto.quote.history(start='2023-01-01', end='2024-12-31', interval='1D') | Không hỗ trợ | |
| Chỉ số (nến) | index.quote.history(start='2023-01-01', end='2024-12-31', interval='1D') | Không hỗ trợ |
Tiếp tục sử dụng Vnstock legacy
Gợi ý
Bạn có thể sử dụng song song phiên bản legacy và Vnstock3 trong trường hợp dự án của bạn vẫn cần sử dụng phiên bản legacy để duy trì các tính năng trong thời gian chuyển đổi hoặc tính năng bạn cần chưa được Vnstock3 hỗ trợ hoàn toàn.
Phiên bản legacy được duy trì tên gói phần mềm như cũ vnstock trong khi Vnstock3 được sử dụng tên gói mới là vnstock3.
Để cài đặt phiên bản legacy, bạn sử dụng câu lệnh:
pip install vnstock
hoặc chỉ định rõ phiên bản cụ thể mình muốn cài đặt, ví dụ bản 0.2.9.0 là bản cuối cùng được cập nhật tới hiện tại.
pip install vnstock==0.2.9.0
Để tra cứu trang tài liệu dự án Vnstock cho phiên bản legacy, bạn có thể bấm vào đây để mở link.