libfinance 0.1.3__tar.gz → 0.1.4__tar.gz

{libfinance-0.1.3 → libfinance-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libfinance
-Version: 0.1.3
+Version: 0.1.4
 Summary: libfinance is a modern finance API
 Description-Content-Type: text/markdown
 Requires-Dist: lz4
@@ -176,6 +176,7 @@ get_trading_dates("2024-01-01", "2024-01-31", market="us")   # 不涉及具体
 | 日频行情 | CN · US | `get_price` | 开高低收、成交量额、涨跌停价，可复权 |
 | 复权因子 | CN · US | `get_ex_factor` | 逐除权日的单次及累计因子 |
 | 股本 | CN · US | `get_shares` | 逐交易日的总股本与流通股本 |
+| 换手率 | CN、US | `get_turnover_rate` | 逐交易日的换手率（未复权成交量 ÷ A 股自由流通股本或美股已发行股数） |
 | 分红 / 拆股 / 配股 | CN · US | `get_dividends`、`get_splits`、`get_allotments` | 除权事件；配股只有 A 股 |
 | 分拆 | US | `get_spinoffs` | A 股不产生这类事件 |
 | 财务报表（PIT） | CN · US | `get_pit_financials_ex` | 按季度取，带修订历史 |

{libfinance-0.1.3 → libfinance-0.1.4}/README.md

@@ -163,6 +163,7 @@ get_trading_dates("2024-01-01", "2024-01-31", market="us")   # 不涉及具体
 | 日频行情 | CN · US | `get_price` | 开高低收、成交量额、涨跌停价，可复权 |
 | 复权因子 | CN · US | `get_ex_factor` | 逐除权日的单次及累计因子 |
 | 股本 | CN · US | `get_shares` | 逐交易日的总股本与流通股本 |
+| 换手率 | CN、US | `get_turnover_rate` | 逐交易日的换手率（未复权成交量 ÷ A 股自由流通股本或美股已发行股数） |
 | 分红 / 拆股 / 配股 | CN · US | `get_dividends`、`get_splits`、`get_allotments` | 除权事件；配股只有 A 股 |
 | 分拆 | US | `get_spinoffs` | A 股不产生这类事件 |
 | 财务报表（PIT） | CN · US | `get_pit_financials_ex` | 按季度取，带修订历史 |

libfinance-0.1.4/VERSION

@@ -0,0 +1 @@
+0.1.4

{libfinance-0.1.3 → libfinance-0.1.4}/libfinance/api/shares.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-"""股本：统一字段，CN 与 US 同一套（后端 shares 数据族的 get_shares_panel）。"""
+"""股本：统一字段，CN 与 US 同一套（后端 shares 数据族的 get_shares_panel）；以及由它算出的日频换手率。"""
 from typing import List, Optional, Union
 
 import pandas as pd
@@ -71,6 +71,42 @@ def get_shares(
     return _indexed(frame)
 
 
+@export_as_api
+def get_turnover_rate(
+    order_book_ids: Union[str, List[str]],
+    start_date=None,
+    end_date=None,
+) -> pd.DataFrame:
+    r"""获取日频换手率。
+
+    A 股换手率 = 当日未复权成交量 ÷ 当日生效的自由流通股本（没有时用流通股本）；
+    美股换手率 = 当日未复权成交量 ÷ 当日已发行股数。结果是\ **小数**\ （0.01 即 1%）。
+    A 股结果与 factors-daybar 的因子（如 ``system/broker-daybar/TURN20``\ ）读取的换手率同一口径。
+
+    :param order_book_ids: 单个代码或代码列表，如 ``"600000.XSHG"``、``"AAPL.US"``
+    :param start_date: 开始日期；只给一个日期时取那一天
+    :param end_date: 结束日期；两个都省略时各市场分别取最近两周内最后一个有行情的交易日
+
+    :returns: pandas.DataFrame，以 (order_book_id, date) 为索引，一列 ``turnover_rate``\ 。停牌日没有行；
+              没有股本数据的证券或日子为 NaN。
+    """
+    order_book_ids = ensure_list_of_string(order_book_ids, "order_book_ids")
+    if not order_book_ids:
+        raise ValueError("order_book_ids: at least one order book id expected")
+    if start_date is not None:
+        start_date = to_date_str(start_date)
+    if end_date is not None:
+        end_date = to_date_str(end_date)
+    if start_date is not None and end_date is not None and start_date > end_date:
+        raise ValueError(
+            "invalid date range: [{!r}, {!r}]".format(start_date, end_date)
+        )
+    frame = get_client().get_turnover_rate(
+        order_book_ids=order_book_ids, start_date=start_date, end_date=end_date,
+    )
+    return _indexed(frame)
+
+
 def _indexed(frame):
     """服务端的扁平表（order_book_id, date, 字段...）-> (order_book_id, date) 索引；已带索引的原样返回。"""
     if not isinstance(frame, pd.DataFrame) or not {"order_book_id", "date"} <= set(frame.columns):

{libfinance-0.1.3 → libfinance-0.1.4}/libfinance/client.py

@@ -3,6 +3,7 @@ import socket
 import struct
 import threading
 import sys
+from collections import deque
 from concurrent.futures import Future
 import time
 
@@ -142,6 +143,7 @@ class RpcClient:
     """
     request_timeout = 300
     request_attempt_count = 3
+    _expired_request_limit = 1024
 
     def __init__(self, host='127.0.0.1', port=8080):
         self.host = host
@@ -153,6 +155,11 @@ class RpcClient:
         self._id_lock = threading.Lock()
 
         self._pending = {}
+        # A timed-out request keeps running on the server: the wire protocol has no cancellation.
+        # Remember a bounded number of those ids so their eventual answers are recognized as late,
+        # rather than reported as a protocol error ("unknown request_id").
+        self._expired_requests = set()
+        self._expired_request_order = deque()
         self._pending_lock = threading.Lock()
 
         self._reader_thread = None
@@ -191,6 +198,8 @@ class RpcClient:
             for fut in self._pending.values():
                 fut.set_exception(ConnectionError("Connection closed"))
             self._pending.clear()
+            self._expired_requests.clear()
+            self._expired_request_order.clear()
 
         if self._reader_thread and self._reader_thread.is_alive():
             self._reader_thread.join(timeout=2)
@@ -209,10 +218,12 @@ class RpcClient:
                 raise ConnectionError(
                     "Not connected to server {}:{}: {}".format(self.host, self.port, error)) from error
 
-    def call_raw(self, function_name, args=None, timeout=10.0):
+    def call_raw(self, function_name, args=None, timeout=None):
         """Send an RPC request and wait synchronously for the raw envelope."""
         if args is None:
             args = {}
+        if timeout is None:
+            timeout = self.request_timeout
         self._ensure_connected()
 
         req_id = self._alloc_id()
@@ -233,12 +244,18 @@ class RpcClient:
             return future.result(timeout=timeout)
         except TimeoutError:
             with self._pending_lock:
-                self._pending.pop(req_id, None)
+                # If the reader won the race and already consumed the answer, there will be no
+                # late frame to classify. Only remember ids actually removed here.
+                if self._pending.pop(req_id, None) is not None:
+                    self._expired_requests.add(req_id)
+                    self._expired_request_order.append(req_id)
+                    while len(self._expired_request_order) > self._expired_request_limit:
+                        self._expired_requests.discard(self._expired_request_order.popleft())
             raise TimeoutError(
                 f"RPC '{function_name}' timeout after {timeout}s (req_id={req_id})"
             )
 
-    def call(self, function_name, args=None, timeout=10.0):
+    def call(self, function_name, args=None, timeout=None):
         """Send an RPC request, auto-unwrap envelope, return result or raise RpcError."""
         resp = self.call_raw(function_name, args, timeout)
         return self._unwrap_envelope(resp)
@@ -388,10 +405,13 @@ class RpcClient:
 
                     with self._pending_lock:
                         future = self._pending.pop(request_id, None)
+                        expired = request_id in self._expired_requests
+                        if expired:
+                            self._expired_requests.remove(request_id)
 
                     if future:
                         future.set_result(response_data)
-                    else:
+                    elif not expired:
                         print(
                             f"Received response for unknown request_id={request_id}",
                             file=sys.stderr,
@@ -420,12 +440,14 @@ class RpcClient:
             try:
                 response = self.call(api_name, kwargs)
                 break
+            except TimeoutError:
+                # The server keeps executing a timed-out request, so retrying it immediately only
+                # duplicates expensive work. Connection failures still use the retry path below.
+                raise
             except Exception as ex:
                 err = ex
                 if attempt_index < self.request_attempt_count - 1:
                     time.sleep(0.6)
-            except ResponseError as ex:
-                err = ex
 
         if response is None and isinstance(err, Exception):
             if "TSocket read 0 bytes" in str(err):
@@ -472,4 +494,4 @@ def get_client():
                 f"Client auto-connect to {_DEFAULT_HOST}:{_DEFAULT_PORT} failed: {e}. "
                 "Call init_client(host=..., port=...) explicitly before using libfinance.api.*"
             ) from e
-    return _CLIENT
+    return _CLIENT

{libfinance-0.1.3 → libfinance-0.1.4}/libfinance.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libfinance
-Version: 0.1.3
+Version: 0.1.4
 Summary: libfinance is a modern finance API
 Description-Content-Type: text/markdown
 Requires-Dist: lz4
@@ -176,6 +176,7 @@ get_trading_dates("2024-01-01", "2024-01-31", market="us")   # 不涉及具体
 | 日频行情 | CN · US | `get_price` | 开高低收、成交量额、涨跌停价，可复权 |
 | 复权因子 | CN · US | `get_ex_factor` | 逐除权日的单次及累计因子 |
 | 股本 | CN · US | `get_shares` | 逐交易日的总股本与流通股本 |
+| 换手率 | CN、US | `get_turnover_rate` | 逐交易日的换手率（未复权成交量 ÷ A 股自由流通股本或美股已发行股数） |
 | 分红 / 拆股 / 配股 | CN · US | `get_dividends`、`get_splits`、`get_allotments` | 除权事件；配股只有 A 股 |
 | 分拆 | US | `get_spinoffs` | A 股不产生这类事件 |
 | 财务报表（PIT） | CN · US | `get_pit_financials_ex` | 按季度取，带修订历史 |

{libfinance-0.1.3 → libfinance-0.1.4}/test/test_client_api_contract.py

@@ -344,6 +344,34 @@ def test_get_shares_takes_the_unified_fields_and_as_of(monkeypatch):
         shares.get_shares("600000.XSHG", fields=["total"])
 
 
+def test_get_turnover_rate_is_indexed_and_checks_its_dates(monkeypatch):
+    """financialmetrics answers a flat table; the client indexes it by (order_book_id, date) and sends dates as ISO."""
+    from datetime import date
+    import pandas as pd
+    from libfinance.api import shares
+
+    calls = []
+
+    class Client:
+        def get_turnover_rate(self, **kwargs):
+            calls.append(kwargs)
+            return pd.DataFrame([{"order_book_id": "600000.XSHG", "date": "2025-06-03", "turnover_rate": 0.0012},
+                                 {"order_book_id": "000001.XSHE", "date": "2025-06-03", "turnover_rate": None}])
+
+    monkeypatch.setattr(shares, "get_client", lambda: Client())
+    out = shares.get_turnover_rate(["600000.XSHG", "000001.XSHE"], date(2025, 6, 1), "2025-06-30")
+    assert calls == [{"order_book_ids": ["600000.XSHG", "000001.XSHE"], "start_date": "2025-06-01",
+                      "end_date": "2025-06-30"}]
+    assert list(out.index.names) == ["order_book_id", "date"] and list(out.columns) == ["turnover_rate"]
+    assert out.loc[("600000.XSHG", pd.Timestamp("2025-06-03")), "turnover_rate"] == 0.0012
+    shares.get_turnover_rate("600000.XSHG")  # no dates: the server picks the latest trading day
+    assert calls[-1] == {"order_book_ids": ["600000.XSHG"], "start_date": None, "end_date": None}
+    with pytest.raises(ValueError):
+        shares.get_turnover_rate("600000.XSHG", "2025-06-30", "2025-06-01")
+    with pytest.raises(ValueError):
+        shares.get_turnover_rate([])
+
+
 def test_as_of_keeps_a_timestamp(monkeypatch):
     import datetime
     from libfinance.utils.utils import as_of_text

{libfinance-0.1.3 → libfinance-0.1.4}/test/test_client_reconnect.py

@@ -8,9 +8,11 @@ connection is cut. Seen 2026-10-04 against deploy-libfinanceserver: every call a
 import socket
 import struct
 import threading
+import time
 
 import msgpack
 
+import libfinance.client as client_module
 from libfinance.client import RpcClient
 
 
@@ -61,6 +63,35 @@ class ClosingServer:
         self.listener.close()
 
 
+class DelayedServer(ClosingServer):
+    """Answers every call after a delay and records how many requests reached the server."""
+
+    def __init__(self, delay):
+        self.delay = delay
+        self.requests = 0
+        super().__init__(answers_per_connection=0)
+
+    def _serve(self):
+        try:
+            sock, _ = self.listener.accept()
+        except OSError:
+            return
+        self.connections += 1
+        try:
+            while True:
+                (length,) = struct.unpack("!I", self._recv(sock, 4))
+                meta_and_payload = self._recv(sock, length)
+                request_id = struct.unpack("!I", meta_and_payload[1:5])[0]
+                self.requests += 1
+                time.sleep(self.delay)
+                body = msgpack.packb({"status": "ok", "code": 0, "result": {"message": "pong"}})
+                sock.sendall(struct.pack("!I", 6 + len(body)) + bytes([0x02]) + struct.pack("!I", request_id)
+                             + bytes([0x00]) + body)
+        except (ConnectionError, OSError):
+            pass
+        sock.close()
+
+
 def test_a_call_after_the_server_closed_the_connection_reconnects():
     server = ClosingServer(answers_per_connection=1)
     client = RpcClient("127.0.0.1", server.port)
@@ -100,3 +131,46 @@ def test_an_unreachable_server_is_a_connection_error_not_a_hang():
         assert "Not connected to server" in str(error)
     else:
         raise AssertionError("expected ConnectionError")
+
+
+def test_default_timeout_uses_the_configured_request_timeout(monkeypatch):
+    observed = []
+
+    class ConnectedSocket:
+        def sendall(self, _frame):
+            pass
+
+    def result(_future, timeout):
+        observed.append(timeout)
+        return {"status": "ok"}
+
+    monkeypatch.setattr(client_module.Future, "result", result)
+    client = RpcClient()
+    client.running = True
+    client.sock = ConnectedSocket()
+    client.request_timeout = 17.5
+    assert client.call_raw("ping") == {"status": "ok"}
+    assert observed == [17.5]
+
+
+def test_api_timeout_is_not_retried_and_late_answer_is_not_unknown(capsys):
+    server = DelayedServer(delay=0.08)
+    client = RpcClient("127.0.0.1", server.port)
+    client.request_timeout = 0.02
+    client.connect()
+    try:
+        client.ping()
+    except TimeoutError as error:
+        assert "req_id=1" in str(error)
+    else:
+        raise AssertionError("expected TimeoutError")
+
+    # Let the reader consume the answer that the server completed after the caller timed out.
+    for _ in range(100):
+        if not client._expired_requests:
+            break
+        threading.Event().wait(0.01)
+    assert server.requests == 1
+    assert "unknown request_id" not in capsys.readouterr().err
+    client.close()
+    server.close()

libfinance-0.1.3/VERSION

@@ -1 +0,0 @@
-0.1.3