Kiểu dữ liệu finlens.typing: WhoAmI, Limits, FrameMeta

Mọi hàm truy vấn dữ liệu đều trả về pandas.DataFrame. Những gì không phải bảng — bạn là ai, hạn mức còn bao nhiêu, bảng vừa nhận mang đơn vị gì — nằm ở module finlens.typing.

Module này chia làm hai nhóm, phục vụ hai nhu cầu khác nhau:

• Alias kiểu — trả lời "tham số này nhận giá trị nào", và dùng để chú thích kiểu cho chính code của bạn.
• TypedDict — mô tả hình dạng của các dict mà whoami(), limits() và df.attrs["finlens"] trả về.

Import ở đâu

Mọi kiểu đều được re-export ở cấp finlens, nên bạn không cần nhớ tên module con:

import finlens
from pandas import DataFrame

def lay_gia(ma: finlens.SymbolsArg,
            interval: finlens.EodInterval = "1d") -> DataFrame:
    client = finlens.client()
    return client.eod.stock.ohlcv(ma, interval=interval)

def con_du_han_muc(han_muc: finlens.Limits) -> bool:
    return han_muc["requests_remaining"] > 100

Viết from finlens.typing import Limits cũng đúng, chỉ dài hơn. Gói có gợi ý kiểu theo chuẩn PEP 561, nên IDE và mypy đọc được cả hai cách.

Alias kiểu

SymbolsArg và IcbArg

SymbolsArg = str | Sequence[str]
IcbArg     = str | Sequence[str]

Ba cách viết dưới đây tương đương nhau, và hợp lệ ở mọi hàm nhận mã:

client.eod.stock.ohlcv("HPG")
client.eod.stock.ohlcv("HPG,VCB")
client.eod.stock.ohlcv(["HPG", "VCB"])

IcbArg giống hệt về hình dạng nhưng khác về nội dung: nó nhận mã ngành ICB cấp 4 dưới dạng chuỗi — "8600", "8600,3570", ["8600", "3570"]. Phải là chuỗi chứ không phải số, vì 8600 viết dạng số sẽ làm mất số 0 đứng đầu ở các mã khác.

DateArg

DateArg = str | date | datetime | None

from datetime import date

client.eod.stock.ohlcv("HPG", start="2026-01-01")
client.eod.stock.ohlcv("HPG", start=date(2026, 1, 1))

Truyền datetime cũng được, nhưng phần giờ bị bỏ: đây là ngày giao dịch, không phải một thời điểm. None nghĩa là dùng mặc định — start mặc định là một năm trước end, end mặc định là hôm nay.

EodInterval

EodInterval = Literal["1d", "1w", "1mo", "3mo", "6mo", "1y"]

Sáu giá trị, chỉ viết thường. Không có 1m, và đó là chủ ý.

Interval '1m' nhập nhằng: có thể là một phút hoặc một tháng.
Dùng '1min' cho một phút, hoặc '1mo' cho một tháng.

# Đúng
client.eod.stock.ohlcv("HPG", interval="1mo")

# Sai — InvalidIntervalError
client.eod.stock.ohlcv("HPG", interval="1M")

Cùng một bộ giá trị này dùng cho cả ohlcv() lẫn flow() và breakdown(). Việc gộp kỳ chạy ở phía máy chủ, nên interval="1w" trả về thanh tuần đã gộp sẵn chứ không phải thanh ngày để bạn tự gộp.

df = client.eod.stock.ohlcv("HPG", start="2025-01-01", end="2025-03-31",
                            interval="1mo")
df["date"].dt.strftime("%Y-%m-%d").tolist()
# ['2025-01-24', '2025-02-28', '2025-03-31']

OnError

OnError = Literal["warn", "raise", "ignore"]

Mặc định là "warn" chứ không phải "raise" vì một mã hỏng không được làm mất 49 mã còn lại. Chi tiết ở Xử lý lỗi.

Nhóm nhà đầu tư

InvestorGroup = Literal[
    "foreign",
    "foreign_individual",
    "foreign_institutional",
    "local_individual",
    "local_institutional",
    "proprietary",
]

SectorInvestorGroup     = Literal["foreign", "proprietary"]
DerivativeInvestorGroup = Literal["foreign", "proprietary"]

Hai alias sau hẹp hơn có chủ đích: bốn nhóm chi tiết không tồn tại ở cấp ngành, cũng không tồn tại ở cấp hợp đồng phái sinh. Thu hẹp Literal biến một lỗi mạng thành một lỗi lúc bạn gõ code.

Chúng trùng tập giá trị nhưng là hai alias riêng, vì hai chỗ hẹp lại vì hai lý do khác nhau và hai lý do đó có thể đổi độc lập: ở cấp ngành, cái bị chặn là một nguồn thực chất chỉ có sàn HOSE; ở cấp phái sinh, nguồn của bốn nhóm chi tiết khoá theo danh mục doanh nghiệp niêm yết, nơi không hợp đồng phái sinh nào có mặt.

Ba alias dạng số nhiều dùng cho breakdown():

InvestorGroupsArg           = str | Sequence[InvestorGroup] | None
SectorInvestorGroupsArg     = str | Sequence[SectorInvestorGroup] | None
DerivativeInvestorGroupsArg = str | Sequence[DerivativeInvestorGroup] | None

None nghĩa là đầy đủ các nhóm mà cấp đó phục vụ, không phải "không nhóm nào". Và không có giá trị "all" ở bất kỳ đâu — muốn tất cả thì để None, muốn một tập cụ thể thì liệt kê ra.

Tier

Tier = Literal["free", "standard", "pro", "premium"]

Đọc bằng client.whoami()["account"]["tier"].

Các TypedDict

Đây là TypedDict, tức lúc chạy chúng là dict thuần. Truy cập bằng khóa, không phải bằng thuộc tính, và chúng không có phương thức nào:

me = client.whoami()

me["account"]["tier"]     # đúng
me.account.tier           # AttributeError

Đổi lại, bạn không phải cài thêm thư viện nào để đọc kết quả, và IDE vẫn gợi ý đủ tên khóa.

WhoAmI — client.whoami()

import finlens

client = finlens.client(api_key="flk_...")
me = client.whoami()

me["account"]["tier"]                  # 'pro'
me["key"]["prefix"]                    # 'flk_9f2a41c3'
me["limits"]["requests_remaining"]     # 4812
me["version"]["latest_client_version"] # '1.1.1'
me["server_time"]                      # '2026-08-04T15:04:21+07:00'

Tạo client không gọi mạng; whoami() là một lời gọi thật, nên nó cũng là cách kiểm tra khóa còn dùng được hay không ngay lúc khởi động ứng dụng.

AccountInfo

expires_at ở đây là hạn của gói dịch vụ, khác với hạn của khóa trong KeyInfo. Hai thứ hết hạn độc lập nhau và cần hai hành động khác nhau — gia hạn tài khoản, hay tạo khóa mới — nên chúng cũng ném hai lớp ngoại lệ khác nhau: AccountExpiredError và ApiKeyExpiredError.

KeyInfo

VersionInfo

Bạn không cần tự so sánh ba con số này. Client tự làm: có bản mới hơn thì nó phát UpgradeAvailableWarning, còn bản của bạn quá cũ để dùng thì nó ném UpgradeRequiredError.

import finlens

client = finlens.client()

print(finlens.__version__)                  # bản đang chạy
print(client.whoami()["version"]["latest_client_version"])

Limits — client.limits()

han_muc = client.limits()

han_muc["requests_remaining"]        # 4812
han_muc["max_symbols_per_request"]   # 50
han_muc["resets_at"]                 # '2026-08-05T00:00:00+07:00'

Những con số này do máy chủ quyết định và đọc được lúc chạy, không phải hằng số biên dịch sẵn trong thư viện. Nghĩa là khi hạn mức của bạn được nới, bản finlens đang cài sẽ dùng ngay giá trị mới mà không cần nâng cấp.

Chạm hạn mức thì bạn nhận RateLimitError hoặc DailyQuotaExceededError; sắp cạn thì nhận QuotaLowWarning. Xem Xử lý lỗi.

Limits cũng chính là giá trị nằm ở whoami()["limits"] — client.limits() chỉ là lối đi tắt.

FrameMeta — siêu dữ liệu đi kèm mỗi DataFrame

Đây là kiểu bạn sẽ đọc nhiều nhất. Mỗi bảng trả về đều mang theo một FrameMeta ở df.attrs["finlens"], và nó trả lời ba câu hỏi mà bản thân bảng không trả lời được: những con số này đơn vị gì, dữ liệu tính tới lúc nào, và có mã nào không lấy được không.

import finlens

client = finlens.client()
df = client.eod.stock.ohlcv("HPG,VCB", start="2026-01-01")

meta = df.attrs["finlens"]
meta["dataset"]              # 'eod.ohlcv'
meta["units"]["close"]       # 'kVND'
meta["price_basis"]          # 'adjusted'
meta["as_of"]                # '2026-08-04T15:00:00+07:00'
meta["partial"]              # False

Đọc đơn vị ở đâu

Đơn vị không cố định theo tên cột — nó phụ thuộc loại tài sản. Cùng cột close: cổ phiếu là nghìn VND, chỉ số là điểm chỉ số, chứng quyền là VND thô. Cùng cột volume: cổ phiếu tính bằng cổ phiếu, phái sinh tính bằng hợp đồng.

Vì vậy units là câu trả lời duy nhất đáng tin:

gia = client.eod.stock.ohlcv("HPG")
gia.attrs["finlens"]["units"]["close"]     # 'kVND' — 23.4 nghĩa là 23.400 VND

dong_tien = client.eod.stock.investor.flow("HPG")
dong_tien.attrs["finlens"]["units"]["net_value"]   # 'VND' — VND thô

Hai bảng trên nằm ở hai namespace khác nhau chính vì hai bộ cột đó không cùng đơn vị. Nhân nhầm 1000 là loại lỗi không ném ngoại lệ nào — chỉ có units chặn được nó.

Phân biệt "chưa có dữ liệu" với "dữ liệu của bạn cũ"

as_of là mốc nước do máy chủ công bố, tính theo giờ thị trường. fetched_at là lúc máy bạn nhận bảng, tính bằng UTC. Hai trục khác nhau là có chủ đích:

meta = df.attrs["finlens"]

meta["as_of"]        # '2026-08-04T15:00:00+07:00' — dữ liệu tính tới đây
meta["fetched_at"]   # '2026-08-04T08:31:07+00:00' — bạn lấy về lúc này

Bảng thiếu phiên hôm nay mà as_of vẫn là hôm qua nghĩa là thị trường chưa chốt, không phải bạn đang dùng bản cũ.

Biết một mã bị lỗi bằng cách nào

Với on_error="warn" (mặc định), lời gọi không ném lỗi — nó trả về phần lấy được và ghi phần hỏng vào partial và failed:

df = client.eod.stock.ohlcv(["HPG", "VCB", "KHONGTONTAI"])

meta = df.attrs["finlens"]
meta["partial"]                            # True
list(meta["failed"])                       # ['KHONGTONTAI']
meta["failed"]["KHONGTONTAI"]["code"]      # 'FL_VALIDATION_SYMBOL'
meta["failed"]["KHONGTONTAI"]["message"]

Kiểm partial là cách rẻ nhất để biết một lô nhiều mã có trọn vẹn hay không. Nếu bạn muốn dừng hẳn thay vì đi tiếp, dùng on_error="raise" rồi đọc .data và .failures của PartialFetchError.

truncated là chuyện khác: nó True khi bảng bị cắt ở giới hạn số dòng của gói dịch vụ. Dữ liệu bạn nhận vẫn đúng, chỉ là chưa hết — thu hẹp khoảng thời gian hoặc chia nhỏ danh sách mã rồi gọi lại.

import pandas as pd

a = client.eod.stock.ohlcv("HPG")
b = client.eod.stock.ohlcv("VCB")

gop = pd.concat([a, b])
gop.attrs.get("finlens")     # None

don_vi = a.attrs["finlens"]["units"]
gop = pd.concat([a, b])
gop.attrs["finlens"] = a.attrs["finlens"]   # gán lại nếu bạn chắc hai bảng cùng đơn vị

FailedSymbol

Mỗi giá trị trong failed là một dict hai khóa:

Phân nhánh theo code, đừng so khớp message — nội dung thông báo được phép đổi, còn code thì không.

Hai kiểu còn lại

CacheStats là hình dạng của client.cache.stats(), gồm hits, misses, entries, bytes, evictions. Tỷ lệ hits trên hits + misses cho biết cache có đang giúp gì không.

client.cache.stats()["hits"]

ServiceStatus là hình dạng của client.status() — trạng thái dịch vụ, đọc được cả khi khóa API sai, nên nó là chỗ để phân biệt "backend đang có vấn đề" với "khóa của tôi có vấn đề". Nó gồm contract_version, min_client_version, latest_client_version, status và server_time.

Xem thêm