yjdata 0.2.3__tar.gz → 0.2.4__tar.gz

yjdata-0.2.4/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: yjdata
+Version: 0.2.4
+Summary: yjdata SDK for Python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25
+Requires-Dist: polars>=1.30
+Requires-Dist: pyarrow>=18
+Requires-Dist: pydantic>=2.11
+
+# yjdata
+
+Python SDK for the YJData web API, MySQL/PostgreSQL adapters, and Parquet utilities.
+
+## Web API
+
+```python
+from yjdata import WebDataClient
+
+client = WebDataClient()
+prices = client.cn_stock.stk_eod_md("2026-11-06", ids="000001.XSHE")
+for price in prices:
+    print(price.id, price.close)
+
+trading_days = client.calendar.range("2026-11-01", "2026-11-06")
+```
+
+| Method | Data |
+| --- | --- |
+| `cn_stock.stk_eod_md(date, ids=None, stable_id=True)` | Stock end-of-day prices |
+| `cn_stock.stk_sod_ref(date, ids=None)` | Stock pre-market reference data |
+| `cn_future.fut_eod_md(date, ids=None)` | Futures end-of-day prices |
+| `cn_future.fut_sod_ref(date, ids=None)` | Futures pre-market reference data |
+| `calendar.next_n(start, n)`, `last_n(end, n)`, `range(start, end)`, `is_trading_day(date)` | Trading calendar; optional `calendar="XSHG"` |
+
+- Dates accept `YYYY-MM-DD`, `YYYYMMDD`, `datetime.date`, or `datetime.datetime`.
+- IDs accept lists or comma-separated strings. `None` returns all records;
+  `[]` or a blank string returns none.
+- Stock prices use first-listing IDs by default. `stable_id=False` uses the
+  ticker on the requested date.
+- Market data returns Pydantic models with friendly fields such as `close`,
+  `volume`, and `display_id`; `time` is a `YYYY-MM-DD` string. Models accept
+  friendly names and API aliases. `model_dump(by_alias=True)` exports API names.
+- Use `AsyncWebDataClient` with `await` for the same methods.
+
+See the [OpenAPI schema](https://yjdata-api.yaojingriver.internal/openapi.json)
+for endpoint and field details.
+
+## Database adapters
+
+`MysqlAdapter` (MySQL 8.0+) and `PostgresAdapter` support
+`select_last_of_group(table, group_by=..., sort_by=...)` and
+`select_last_of_group_polars(...)`, returning dictionaries or a Polars DataFrame.
+
+These methods select the last complete row per group in SQL. Use `ascending`
+to control sort direction, `filter` before selection, `post_filter` afterward,
+and `columns` for projection. NULLs sort below non-NULL values; include a unique
+tie-breaker in `sort_by` for deterministic selection. Group output order is
+unspecified.
+
+## Tests
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests -v
+```

yjdata-0.2.4/README.md

@@ -0,0 +1,55 @@
+# yjdata
+
+Python SDK for the YJData web API, MySQL/PostgreSQL adapters, and Parquet utilities.
+
+## Web API
+
+```python
+from yjdata import WebDataClient
+
+client = WebDataClient()
+prices = client.cn_stock.stk_eod_md("2026-11-06", ids="000001.XSHE")
+for price in prices:
+    print(price.id, price.close)
+
+trading_days = client.calendar.range("2026-11-01", "2026-11-06")
+```
+
+| Method | Data |
+| --- | --- |
+| `cn_stock.stk_eod_md(date, ids=None, stable_id=True)` | Stock end-of-day prices |
+| `cn_stock.stk_sod_ref(date, ids=None)` | Stock pre-market reference data |
+| `cn_future.fut_eod_md(date, ids=None)` | Futures end-of-day prices |
+| `cn_future.fut_sod_ref(date, ids=None)` | Futures pre-market reference data |
+| `calendar.next_n(start, n)`, `last_n(end, n)`, `range(start, end)`, `is_trading_day(date)` | Trading calendar; optional `calendar="XSHG"` |
+
+- Dates accept `YYYY-MM-DD`, `YYYYMMDD`, `datetime.date`, or `datetime.datetime`.
+- IDs accept lists or comma-separated strings. `None` returns all records;
+  `[]` or a blank string returns none.
+- Stock prices use first-listing IDs by default. `stable_id=False` uses the
+  ticker on the requested date.
+- Market data returns Pydantic models with friendly fields such as `close`,
+  `volume`, and `display_id`; `time` is a `YYYY-MM-DD` string. Models accept
+  friendly names and API aliases. `model_dump(by_alias=True)` exports API names.
+- Use `AsyncWebDataClient` with `await` for the same methods.
+
+See the [OpenAPI schema](https://yjdata-api.yaojingriver.internal/openapi.json)
+for endpoint and field details.
+
+## Database adapters
+
+`MysqlAdapter` (MySQL 8.0+) and `PostgresAdapter` support
+`select_last_of_group(table, group_by=..., sort_by=...)` and
+`select_last_of_group_polars(...)`, returning dictionaries or a Polars DataFrame.
+
+These methods select the last complete row per group in SQL. Use `ascending`
+to control sort direction, `filter` before selection, `post_filter` afterward,
+and `columns` for projection. NULLs sort below non-NULL values; include a unique
+tie-breaker in `sort_by` for deterministic selection. Group output order is
+unspecified.
+
+## Tests
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests -v
+```

{yjdata-0.2.3 → yjdata-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "yjdata"
-version = "0.2.3"
+version = "0.2.4"
 description = "yjdata SDK for Python"
 readme = "README.md"
 requires-python = ">=3.10"

{yjdata-0.2.3 → yjdata-0.2.4}/src/yjdata/web/calendar.py

@@ -49,7 +49,7 @@ class CalendarWebClient:
         return self._context.post(f'{self._api_root}/next-n', payload={
             'start': parse_date_str_arg(start, False),
             'n': n,
-            'calendar': calendar
+            'exchange': calendar
         })
 
     def last_n(
@@ -83,7 +83,7 @@ class CalendarWebClient:
         return self._context.post(f'{self._api_root}/last-n', payload={
             'end': parse_date_str_arg(end, False),
             'n': n,
-            'calendar': calendar
+            'exchange': calendar
         })
 
     def range(
@@ -118,7 +118,7 @@ class CalendarWebClient:
         return self._context.post(f'{self._api_root}/range', payload={
             'start': parse_date_str_arg(start, False),
             'end': parse_date_str_arg(end, False),
-            'calendar': calendar
+            'exchange': calendar
         })
 
     @abstractmethod

{yjdata-0.2.3 → yjdata-0.2.4}/src/yjdata/web/client.py

@@ -1,6 +1,8 @@
 import os
 
 from .calendar import SyncCalenderWebClient, AsyncCalendarWebClient
+from .cn_future import CnFutureWebClient
+from .cn_stock import CnStockWebClient
 from ._context import RequestContext, SyncRequestContext, AsyncRequestContext
 
 
@@ -23,6 +25,16 @@ class _WebClient:
             self._host = host
         self._context = context
 
+    @property
+    def cn_stock(self) -> CnStockWebClient:
+        """API set for domestic stock market data."""
+        return CnStockWebClient(self._host, self._context)
+
+    @property
+    def cn_future(self) -> CnFutureWebClient:
+        """API set for domestic futures market data."""
+        return CnFutureWebClient(self._host, self._context)
+
 
 class WebDataClient(_WebClient):
     """Client for accessing YJData web API."""

yjdata-0.2.4/src/yjdata/web/cn_future.py

@@ -0,0 +1,110 @@
+from typing import Awaitable, List, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ._context import RequestContext
+from ._input import DateStrArgType, StrListArgType, parse_date_str_arg, parse_str_list_arg
+
+
+__all__ = ['CnFutureWebClient', 'FutEodMd', 'FutSodRef']
+
+
+class FutEodMd(BaseModel):
+    """Futures end-of-day prices, volume, turnover and open interest."""
+
+    model_config = ConfigDict(validate_by_name=True)
+
+    id: str
+    time: str          = Field(alias='date')
+    pre_settle: float  = Field(alias='ps')
+    pre_close: float   = Field(alias='pc')
+    open: float        = Field(alias='o')
+    high: float        = Field(alias='h')
+    low: float         = Field(alias='l')
+    close: float       = Field(alias='c')
+    settle: float      = Field(alias='s')
+    volume: int        = Field(alias='vol')
+    amount: float      = Field(alias='amt')
+    open_interest: int = Field(alias='oi')
+
+
+class FutSodRef(BaseModel):
+    """Futures pre-market reference data, including contract specifications."""
+
+    model_config = ConfigDict(validate_by_name=True)
+
+    id: str
+    time: str                       = Field(alias='date')
+    name: str
+    display_id: str                 = Field(alias='dispId')
+    ticker: str
+    trading_status: str             = Field(alias='status')
+    underlying_id: Union[str, None] = Field(alias='ulId')
+    product: str                    = Field(alias='prod')
+    multiplier: float               = Field(alias='mult')
+    tick: float
+    pre_close: float                = Field(alias='pc')
+    pre_settle: float               = Field(alias='ps')
+    auct_hours: str                 = Field(alias='auct')
+    cont_hours: str                 = Field(alias='cont')
+    upper_limit: float              = Field(alias='ul')
+    lower_limit: float              = Field(alias='ll')
+
+
+class CnFutureWebClient:
+
+    def __init__(self, host: str, context: RequestContext):
+        self._api_root = f'http://{host}/v1/cn_future'
+        self._context = context
+
+    def fut_eod_md(
+            self,
+            date: DateStrArgType,
+            ids: StrListArgType = None
+    ) -> Union[List[FutEodMd], Awaitable[List[FutEodMd]]]:
+        """Get domestic futures end-of-day market data for a trading date.
+
+        Parameters
+        ----------
+        date : str, datetime.date or datetime.datetime
+            Trading date; strings accept YYYY-MM-DD or YYYYMMDD.
+        ids : str or list[str], optional
+            IDs as a list or comma-separated string. None returns all records;
+            an empty list or blank string returns no records.
+
+        Returns
+        -------
+        list[FutEodMd] or Awaitable[list[FutEodMd]]
+            Validated records; await the result with AsyncWebDataClient.
+        """
+        return self._context.post_model_list(FutEodMd, f'{self._api_root}/fut-eod-md', payload={
+            'date': parse_date_str_arg(date, False),
+            'ids': None if ids is None else parse_str_list_arg(ids)
+        })
+
+    def fut_sod_ref(
+            self,
+            date: DateStrArgType,
+            ids: StrListArgType = None
+    ) -> Union[List[FutSodRef], Awaitable[List[FutSodRef]]]:
+        """Get domestic futures pre-market reference data for a trading date.
+
+        Parameters
+        ----------
+        date : str, datetime.date or datetime.datetime
+            Trading date; strings accept YYYY-MM-DD or YYYYMMDD.
+        ids : str or list[str], optional
+            IDs as a list or comma-separated string. None returns all records;
+            an empty list or blank string returns no records.
+
+        Returns
+        -------
+        list[FutSodRef] or Awaitable[list[FutSodRef]]
+            Validated records; await the result with AsyncWebDataClient.
+            API fields dispId and ulId use display_id and underlying_id.
+            underlying_id is None for contracts without an underlying index.
+        """
+        return self._context.post_model_list(FutSodRef, f'{self._api_root}/fut-sod-ref', payload={
+            'date': parse_date_str_arg(date, False),
+            'ids': None if ids is None else parse_str_list_arg(ids)
+        })

yjdata-0.2.4/src/yjdata/web/cn_stock.py

@@ -0,0 +1,108 @@
+from typing import Awaitable, List, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ._context import RequestContext
+from ._input import DateStrArgType, StrListArgType, parse_date_str_arg, parse_str_list_arg
+
+
+__all__ = ['CnStockWebClient', 'StkEodMd', 'StkSodRef']
+
+
+class StkEodMd(BaseModel):
+    """Stock end-of-day prices, volume and turnover."""
+
+    model_config = ConfigDict(validate_by_name=True)
+
+    id: str
+    time: str        = Field(alias='date')
+    pre_close: float = Field(alias='pc')
+    open: float      = Field(alias='o')
+    high: float      = Field(alias='h')
+    low: float       = Field(alias='l')
+    close: float     = Field(alias='c')
+    volume: int      = Field(alias='vol')
+    amount: float    = Field(alias='amt')
+
+
+class StkSodRef(BaseModel):
+    """Stock pre-market reference data. IDs use the first listing ticker."""
+
+    model_config = ConfigDict(validate_by_name=True)
+
+    id: str
+    time: str           = Field(alias='date')
+    name: str
+    display_id: str     = Field(alias='dispId')
+    ticker: str
+    trading_status: str = Field(alias='status')
+    st_status: str      = Field(alias='st')
+    pre_close: float    = Field(alias='pc')
+    prior_close: float  = Field(alias='prc')
+    upper_limit: float  = Field(alias='ul')
+    lower_limit: float  = Field(alias='ll')
+    auct_hours: str     = Field(alias='auct')
+    cont_hours: str     = Field(alias='cont')
+
+
+class CnStockWebClient:
+
+    def __init__(self, host: str, context: RequestContext):
+        self._api_root = f'http://{host}/v1/cn_stock'
+        self._context = context
+
+    def stk_eod_md(
+            self,
+            date: DateStrArgType,
+            ids: StrListArgType = None,
+            stable_id: bool = True
+    ) -> Union[List[StkEodMd], Awaitable[List[StkEodMd]]]:
+        """Get stock end-of-day market data for a trading date.
+
+        Parameters
+        ----------
+        date : str, datetime.date or datetime.datetime
+            Trading date; strings accept YYYY-MM-DD or YYYYMMDD.
+        ids : str or list[str], optional
+            IDs as a list or comma-separated string. None returns all records;
+            an empty list or blank string returns no records.
+        stable_id : bool, default: True
+            Use the first listing ticker plus exchange for both the ID filter
+            and returned IDs. False uses the ticker on the requested date.
+
+        Returns
+        -------
+        list[StkEodMd] or Awaitable[list[StkEodMd]]
+            Validated records; await the result with AsyncWebDataClient.
+        """
+        return self._context.post_model_list(StkEodMd, f'{self._api_root}/stk-eod-md', payload={
+            'date': parse_date_str_arg(date, False),
+            'ids': None if ids is None else parse_str_list_arg(ids),
+            'stableId': stable_id
+        })
+
+    def stk_sod_ref(
+            self,
+            date: DateStrArgType,
+            ids: StrListArgType = None
+    ) -> Union[List[StkSodRef], Awaitable[List[StkSodRef]]]:
+        """Get stock pre-market reference data for a trading date.
+
+        Parameters
+        ----------
+        date : str, datetime.date or datetime.datetime
+            Trading date; strings accept YYYY-MM-DD or YYYYMMDD.
+        ids : str or list[str], optional
+            IDs as a list or comma-separated string. None returns all records;
+            an empty list or blank string returns no records.
+
+        Returns
+        -------
+        list[StkSodRef] or Awaitable[list[StkSodRef]]
+            Validated records; await the result with AsyncWebDataClient.
+            Fields use backend Python names, such as display_id for dispId.
+        """
+        return self._context.post_model_list(StkSodRef, f'{self._api_root}/stk-sod-ref', payload={
+            'date': parse_date_str_arg(date, False),
+            'ids': None if ids is None else parse_str_list_arg(ids)
+        })

yjdata-0.2.4/src/yjdata.egg-info/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: yjdata
+Version: 0.2.4
+Summary: yjdata SDK for Python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25
+Requires-Dist: polars>=1.30
+Requires-Dist: pyarrow>=18
+Requires-Dist: pydantic>=2.11
+
+# yjdata
+
+Python SDK for the YJData web API, MySQL/PostgreSQL adapters, and Parquet utilities.
+
+## Web API
+
+```python
+from yjdata import WebDataClient
+
+client = WebDataClient()
+prices = client.cn_stock.stk_eod_md("2026-11-06", ids="000001.XSHE")
+for price in prices:
+    print(price.id, price.close)
+
+trading_days = client.calendar.range("2026-11-01", "2026-11-06")
+```
+
+| Method | Data |
+| --- | --- |
+| `cn_stock.stk_eod_md(date, ids=None, stable_id=True)` | Stock end-of-day prices |
+| `cn_stock.stk_sod_ref(date, ids=None)` | Stock pre-market reference data |
+| `cn_future.fut_eod_md(date, ids=None)` | Futures end-of-day prices |
+| `cn_future.fut_sod_ref(date, ids=None)` | Futures pre-market reference data |
+| `calendar.next_n(start, n)`, `last_n(end, n)`, `range(start, end)`, `is_trading_day(date)` | Trading calendar; optional `calendar="XSHG"` |
+
+- Dates accept `YYYY-MM-DD`, `YYYYMMDD`, `datetime.date`, or `datetime.datetime`.
+- IDs accept lists or comma-separated strings. `None` returns all records;
+  `[]` or a blank string returns none.
+- Stock prices use first-listing IDs by default. `stable_id=False` uses the
+  ticker on the requested date.
+- Market data returns Pydantic models with friendly fields such as `close`,
+  `volume`, and `display_id`; `time` is a `YYYY-MM-DD` string. Models accept
+  friendly names and API aliases. `model_dump(by_alias=True)` exports API names.
+- Use `AsyncWebDataClient` with `await` for the same methods.
+
+See the [OpenAPI schema](https://yjdata-api.yaojingriver.internal/openapi.json)
+for endpoint and field details.
+
+## Database adapters
+
+`MysqlAdapter` (MySQL 8.0+) and `PostgresAdapter` support
+`select_last_of_group(table, group_by=..., sort_by=...)` and
+`select_last_of_group_polars(...)`, returning dictionaries or a Polars DataFrame.
+
+These methods select the last complete row per group in SQL. Use `ascending`
+to control sort direction, `filter` before selection, `post_filter` afterward,
+and `columns` for projection. NULLs sort below non-NULL values; include a unique
+tie-breaker in `sort_by` for deterministic selection. Group output order is
+unspecified.
+
+## Tests
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests -v
+```

{yjdata-0.2.3 → yjdata-0.2.4}/src/yjdata.egg-info/SOURCES.txt

@@ -26,6 +26,8 @@ src/yjdata/web/_context.py
 src/yjdata/web/_input.py
 src/yjdata/web/calendar.py
 src/yjdata/web/client.py
+src/yjdata/web/cn_future.py
+src/yjdata/web/cn_stock.py
 src/yjdata/web/time_util.py
 tests/test_batch_writes.py
 tests/test_last_of_group.py

yjdata-0.2.3/PKG-INFO

@@ -1,130 +0,0 @@
-Metadata-Version: 2.4
-Name: yjdata
-Version: 0.2.3
-Summary: yjdata SDK for Python
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: httpx>=0.25
-Requires-Dist: polars>=1.30
-Requires-Dist: pyarrow>=18
-Requires-Dist: pydantic>=2.11
-
-# yjdata
-
-Python SDK for yjdata, including MySQL and PostgreSQL database adapters.
-
-## Select the last row of each group
-
-`MysqlAdapter` (MySQL 8.0+) and `PostgresAdapter` provide:
-
-- `select_last_of_group(...) -> list[dict[str, Any]]`
-- `select_last_of_group_polars(...) -> polars.DataFrame`
-
-Both methods execute grouping, row selection, filtering, and projection in SQL
-using `ROW_NUMBER()`. They accept the table name followed by keyword arguments:
-
-| Parameter | Meaning |
-| --- | --- |
-| `table` | Table name, optionally qualified by schema or database. |
-| `group_by: Sequence[str]` | Required nonempty sequence of grouping columns. |
-| `sort_by: Sequence[str]` | Required nonempty sequence of sort columns, in priority order. |
-| `ascending: bool \| Sequence[bool] = True` | One direction for every sort column, or one boolean per column. |
-| `columns: Sequence[str] \| None = None` | Nonempty sequence of output columns; `None` returns all original columns. |
-| `filter: Expression \| None = None` | Filter source rows before choosing a row per group. |
-| `post_filter: Expression \| None = None` | Filter the chosen rows, before projecting output columns. |
-
-The operation first applies `filter`, orders each group, selects its last complete
-source row, applies `post_filter`, and finally projects `columns`. Values come
-from the same row, including NULL values; this is not a separate last-non-NULL
-aggregation for each column. A post-filter rejection removes the group entirely,
-without falling back to an older row.
-
-NULLs sort below all non-NULL values on both backends: first for ascending order
-and last for descending order. Consequently, ascending selection prefers the
-largest non-NULL value, while descending selection prefers NULL when present.
-This rule applies to each sort column. NULL grouping keys group together.
-For deterministic selection among ties, include a unique column in `sort_by`,
-such as `sort_by=["change_time", "record_id"]`. Output order across groups is
-unspecified.
-
-Group, sort, and filter columns need not appear in `columns`. Internal ranking
-columns are excluded by the SQL projection, even if the table has similarly
-named columns. With `columns=None`, an additional zero-row query reads column
-metadata so the adapter can explicitly project all original columns.
-An empty result is `[]` for dictionaries or a DataFrame with no columns for
-Polars, matching the existing selection methods. Polars infers types from all
-returned rows.
-
-### THS concept snapshots
-
-For an existing adapter `client` and a cutoff value `cutoff`:
-
-```python
-import yjdata.db.expression as ye
-
-data = client.select_last_of_group_polars(
-    table="thsetl.concept_change_record",
-    group_by=["concept_id"],
-    sort_by=["change_time"],
-    ascending=True,
-    columns=["concept_id", "concept_name"],
-    filter=(
-        (ye.col("change_time") <= cutoff)
-        & (ye.col("isvalid") == "1")
-    ),
-    post_filter=ye.col("change_type") != "conceptNegation",
-)
-```
-
-This selects the latest valid change at or before the cutoff, then excludes
-concepts whose selected change is a negation. The MySQL query has this form:
-
-```sql
-SELECT `concept_id`, `concept_name`
-FROM (
-    SELECT `concept_id`, `concept_name`, `change_type`,
-           ROW_NUMBER() OVER (
-               PARTITION BY `concept_id`
-               ORDER BY (`change_time` IS NULL) ASC, `change_time` DESC
-           ) AS `_yjdata_row_number`
-    FROM `thsetl`.`concept_change_record`
-    WHERE (`change_time` <= %s) AND (`isvalid` = %s)
-) AS `_yjdata_latest`
-WHERE `_yjdata_row_number` = 1 AND (`change_type` <> %s)
-```
-
-Values are bound in order: `[cutoff, "1", "conceptNegation"]`. PostgreSQL uses
-the same query structure with double-quoted identifiers. Expressions retain
-normal SQL NULL semantics: for example, `change_type <> 'conceptNegation'`
-also excludes NULL `change_type` values.
-
-## Batch writes
-
-PostgreSQL inserts, upserts and updates use `psycopg2.extras.execute_batch`.
-MySQL inserts and upserts use PyMySQL's optimized `executemany`. MySQL updates
-combine driver-escaped UPDATE statements into one request, preserving input
-order, repeated keys and ordinary `=` matching (NULL keys do not match).
-MySQL connections enable `CLIENT.MULTI_STATEMENTS` for these update batches.
-
-`batch_size` limits rows per batch. MySQL update batches also respect the
-cursor's `max_stmt_length` in encoded bytes (normally about 1 MB); an individual
-larger statement is sent alone and remains subject to the server's packet limit.
-Every result is consumed so errors in later statements propagate before commit.
-With the default transactional connection settings and transactional tables,
-all batches commit together or roll back on failure. This reduces network
-round trips; the server still executes one UPDATE per input row.
-
-## Tests
-
-```sh
-python -m unittest discover -s tests -v
-```
-
-The grouped-selection tests exercise both adapters' validation, quoting,
-parameter ordering, and result conversion. Generated queries execute against
-SQLite's window engine with DB-API placeholders translated, so tests require
-neither optional database drivers nor running servers. This does not replace
-integration testing against MySQL and PostgreSQL.
-
-With `pymysql` installed, the MySQL batch-update tests also exercise the real
-driver's escaping, encoded request sizes and result handling without a server.

yjdata-0.2.3/README.md

@@ -1,119 +0,0 @@
-# yjdata
-
-Python SDK for yjdata, including MySQL and PostgreSQL database adapters.
-
-## Select the last row of each group
-
-`MysqlAdapter` (MySQL 8.0+) and `PostgresAdapter` provide:
-
-- `select_last_of_group(...) -> list[dict[str, Any]]`
-- `select_last_of_group_polars(...) -> polars.DataFrame`
-
-Both methods execute grouping, row selection, filtering, and projection in SQL
-using `ROW_NUMBER()`. They accept the table name followed by keyword arguments:
-
-| Parameter | Meaning |
-| --- | --- |
-| `table` | Table name, optionally qualified by schema or database. |
-| `group_by: Sequence[str]` | Required nonempty sequence of grouping columns. |
-| `sort_by: Sequence[str]` | Required nonempty sequence of sort columns, in priority order. |
-| `ascending: bool \| Sequence[bool] = True` | One direction for every sort column, or one boolean per column. |
-| `columns: Sequence[str] \| None = None` | Nonempty sequence of output columns; `None` returns all original columns. |
-| `filter: Expression \| None = None` | Filter source rows before choosing a row per group. |
-| `post_filter: Expression \| None = None` | Filter the chosen rows, before projecting output columns. |
-
-The operation first applies `filter`, orders each group, selects its last complete
-source row, applies `post_filter`, and finally projects `columns`. Values come
-from the same row, including NULL values; this is not a separate last-non-NULL
-aggregation for each column. A post-filter rejection removes the group entirely,
-without falling back to an older row.
-
-NULLs sort below all non-NULL values on both backends: first for ascending order
-and last for descending order. Consequently, ascending selection prefers the
-largest non-NULL value, while descending selection prefers NULL when present.
-This rule applies to each sort column. NULL grouping keys group together.
-For deterministic selection among ties, include a unique column in `sort_by`,
-such as `sort_by=["change_time", "record_id"]`. Output order across groups is
-unspecified.
-
-Group, sort, and filter columns need not appear in `columns`. Internal ranking
-columns are excluded by the SQL projection, even if the table has similarly
-named columns. With `columns=None`, an additional zero-row query reads column
-metadata so the adapter can explicitly project all original columns.
-An empty result is `[]` for dictionaries or a DataFrame with no columns for
-Polars, matching the existing selection methods. Polars infers types from all
-returned rows.
-
-### THS concept snapshots
-
-For an existing adapter `client` and a cutoff value `cutoff`:
-
-```python
-import yjdata.db.expression as ye
-
-data = client.select_last_of_group_polars(
-    table="thsetl.concept_change_record",
-    group_by=["concept_id"],
-    sort_by=["change_time"],
-    ascending=True,
-    columns=["concept_id", "concept_name"],
-    filter=(
-        (ye.col("change_time") <= cutoff)
-        & (ye.col("isvalid") == "1")
-    ),
-    post_filter=ye.col("change_type") != "conceptNegation",
-)
-```
-
-This selects the latest valid change at or before the cutoff, then excludes
-concepts whose selected change is a negation. The MySQL query has this form:
-
-```sql
-SELECT `concept_id`, `concept_name`
-FROM (
-    SELECT `concept_id`, `concept_name`, `change_type`,
-           ROW_NUMBER() OVER (
-               PARTITION BY `concept_id`
-               ORDER BY (`change_time` IS NULL) ASC, `change_time` DESC
-           ) AS `_yjdata_row_number`
-    FROM `thsetl`.`concept_change_record`
-    WHERE (`change_time` <= %s) AND (`isvalid` = %s)
-) AS `_yjdata_latest`
-WHERE `_yjdata_row_number` = 1 AND (`change_type` <> %s)
-```
-
-Values are bound in order: `[cutoff, "1", "conceptNegation"]`. PostgreSQL uses
-the same query structure with double-quoted identifiers. Expressions retain
-normal SQL NULL semantics: for example, `change_type <> 'conceptNegation'`
-also excludes NULL `change_type` values.
-
-## Batch writes
-
-PostgreSQL inserts, upserts and updates use `psycopg2.extras.execute_batch`.
-MySQL inserts and upserts use PyMySQL's optimized `executemany`. MySQL updates
-combine driver-escaped UPDATE statements into one request, preserving input
-order, repeated keys and ordinary `=` matching (NULL keys do not match).
-MySQL connections enable `CLIENT.MULTI_STATEMENTS` for these update batches.
-
-`batch_size` limits rows per batch. MySQL update batches also respect the
-cursor's `max_stmt_length` in encoded bytes (normally about 1 MB); an individual
-larger statement is sent alone and remains subject to the server's packet limit.
-Every result is consumed so errors in later statements propagate before commit.
-With the default transactional connection settings and transactional tables,
-all batches commit together or roll back on failure. This reduces network
-round trips; the server still executes one UPDATE per input row.
-
-## Tests
-
-```sh
-python -m unittest discover -s tests -v
-```
-
-The grouped-selection tests exercise both adapters' validation, quoting,
-parameter ordering, and result conversion. Generated queries execute against
-SQLite's window engine with DB-API placeholders translated, so tests require
-neither optional database drivers nor running servers. This does not replace
-integration testing against MySQL and PostgreSQL.
-
-With `pymysql` installed, the MySQL batch-update tests also exercise the real
-driver's escaping, encoded request sizes and result handling without a server.

yjdata-0.2.3/src/yjdata.egg-info/PKG-INFO

@@ -1,130 +0,0 @@
-Metadata-Version: 2.4
-Name: yjdata
-Version: 0.2.3
-Summary: yjdata SDK for Python
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: httpx>=0.25
-Requires-Dist: polars>=1.30
-Requires-Dist: pyarrow>=18
-Requires-Dist: pydantic>=2.11
-
-# yjdata
-
-Python SDK for yjdata, including MySQL and PostgreSQL database adapters.
-
-## Select the last row of each group
-
-`MysqlAdapter` (MySQL 8.0+) and `PostgresAdapter` provide:
-
-- `select_last_of_group(...) -> list[dict[str, Any]]`
-- `select_last_of_group_polars(...) -> polars.DataFrame`
-
-Both methods execute grouping, row selection, filtering, and projection in SQL
-using `ROW_NUMBER()`. They accept the table name followed by keyword arguments:
-
-| Parameter | Meaning |
-| --- | --- |
-| `table` | Table name, optionally qualified by schema or database. |
-| `group_by: Sequence[str]` | Required nonempty sequence of grouping columns. |
-| `sort_by: Sequence[str]` | Required nonempty sequence of sort columns, in priority order. |
-| `ascending: bool \| Sequence[bool] = True` | One direction for every sort column, or one boolean per column. |
-| `columns: Sequence[str] \| None = None` | Nonempty sequence of output columns; `None` returns all original columns. |
-| `filter: Expression \| None = None` | Filter source rows before choosing a row per group. |
-| `post_filter: Expression \| None = None` | Filter the chosen rows, before projecting output columns. |
-
-The operation first applies `filter`, orders each group, selects its last complete
-source row, applies `post_filter`, and finally projects `columns`. Values come
-from the same row, including NULL values; this is not a separate last-non-NULL
-aggregation for each column. A post-filter rejection removes the group entirely,
-without falling back to an older row.
-
-NULLs sort below all non-NULL values on both backends: first for ascending order
-and last for descending order. Consequently, ascending selection prefers the
-largest non-NULL value, while descending selection prefers NULL when present.
-This rule applies to each sort column. NULL grouping keys group together.
-For deterministic selection among ties, include a unique column in `sort_by`,
-such as `sort_by=["change_time", "record_id"]`. Output order across groups is
-unspecified.
-
-Group, sort, and filter columns need not appear in `columns`. Internal ranking
-columns are excluded by the SQL projection, even if the table has similarly
-named columns. With `columns=None`, an additional zero-row query reads column
-metadata so the adapter can explicitly project all original columns.
-An empty result is `[]` for dictionaries or a DataFrame with no columns for
-Polars, matching the existing selection methods. Polars infers types from all
-returned rows.
-
-### THS concept snapshots
-
-For an existing adapter `client` and a cutoff value `cutoff`:
-
-```python
-import yjdata.db.expression as ye
-
-data = client.select_last_of_group_polars(
-    table="thsetl.concept_change_record",
-    group_by=["concept_id"],
-    sort_by=["change_time"],
-    ascending=True,
-    columns=["concept_id", "concept_name"],
-    filter=(
-        (ye.col("change_time") <= cutoff)
-        & (ye.col("isvalid") == "1")
-    ),
-    post_filter=ye.col("change_type") != "conceptNegation",
-)
-```
-
-This selects the latest valid change at or before the cutoff, then excludes
-concepts whose selected change is a negation. The MySQL query has this form:
-
-```sql
-SELECT `concept_id`, `concept_name`
-FROM (
-    SELECT `concept_id`, `concept_name`, `change_type`,
-           ROW_NUMBER() OVER (
-               PARTITION BY `concept_id`
-               ORDER BY (`change_time` IS NULL) ASC, `change_time` DESC
-           ) AS `_yjdata_row_number`
-    FROM `thsetl`.`concept_change_record`
-    WHERE (`change_time` <= %s) AND (`isvalid` = %s)
-) AS `_yjdata_latest`
-WHERE `_yjdata_row_number` = 1 AND (`change_type` <> %s)
-```
-
-Values are bound in order: `[cutoff, "1", "conceptNegation"]`. PostgreSQL uses
-the same query structure with double-quoted identifiers. Expressions retain
-normal SQL NULL semantics: for example, `change_type <> 'conceptNegation'`
-also excludes NULL `change_type` values.
-
-## Batch writes
-
-PostgreSQL inserts, upserts and updates use `psycopg2.extras.execute_batch`.
-MySQL inserts and upserts use PyMySQL's optimized `executemany`. MySQL updates
-combine driver-escaped UPDATE statements into one request, preserving input
-order, repeated keys and ordinary `=` matching (NULL keys do not match).
-MySQL connections enable `CLIENT.MULTI_STATEMENTS` for these update batches.
-
-`batch_size` limits rows per batch. MySQL update batches also respect the
-cursor's `max_stmt_length` in encoded bytes (normally about 1 MB); an individual
-larger statement is sent alone and remains subject to the server's packet limit.
-Every result is consumed so errors in later statements propagate before commit.
-With the default transactional connection settings and transactional tables,
-all batches commit together or roll back on failure. This reduces network
-round trips; the server still executes one UPDATE per input row.
-
-## Tests
-
-```sh
-python -m unittest discover -s tests -v
-```
-
-The grouped-selection tests exercise both adapters' validation, quoting,
-parameter ordering, and result conversion. Generated queries execute against
-SQLite's window engine with DB-API placeholders translated, so tests require
-neither optional database drivers nor running servers. This does not replace
-integration testing against MySQL and PostgreSQL.
-
-With `pymysql` installed, the MySQL batch-update tests also exercise the real
-driver's escaping, encoded request sizes and result handling without a server.