pam-python 0.2.18__py3-none-any.whl → 0.2.19__py3-none-any.whl

pam/__init__.py

@@ -1,3 +1,3 @@
 """PAM Data Plugin framework."""
 
-__version__ = "0.2.18"
+__version__ = "0.2.19"

pam/reports/store.py

@@ -6,7 +6,7 @@ import sqlite3
 import threading
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Iterable, List, Optional, Set
+from typing import Any, Iterable, List, Mapping, Optional, Set
 
 from pam.datetime_utils import format_pam_datetime
 from pam.reports.errors import (
@@ -157,9 +157,12 @@ class ReportStore:
         granularity: str,
         columns: Iterable[Field],
         temporal_mode: Optional[TemporalMode] = None,
+        row_order: Optional[Mapping[str, Iterable[Any]]] = None,
     ) -> TableReport:
         """Declare a typed Table report."""
-        return TableReport.declare(self, key, granularity, columns, temporal_mode)
+        return TableReport.declare(
+            self, key, granularity, columns, temporal_mode, row_order
+        )
 
     def metric(
         self,

pam/reports/table.py

@@ -1,7 +1,8 @@
 """Typed Table report public API."""
 
-from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
 
+from pam.reports.axis import normalize_value_order
 from pam.reports.definition import ReportDefinition
 from pam.reports.errors import ReportStoreValidationError
 from pam.reports.fields import Dimension, Field, Measure
@@ -22,6 +23,7 @@ class TableReport:
         report,
         granularity: str,
         columns: Sequence[Field],
+        row_order: Mapping[str, Tuple[Any, ...]],
     ):
         self._report = report
         self.key = report.key
@@ -33,6 +35,7 @@ class TableReport:
         self._measures = tuple(
             column for column in self.columns if isinstance(column, Measure)
         )
+        self.row_order = dict(row_order)
 
     @classmethod
     def declare(
@@ -42,6 +45,7 @@ class TableReport:
         granularity: str,
         columns: Iterable[Field],
         temporal_mode: Optional[TemporalMode] = None,
+        row_order: Optional[Mapping[str, Iterable[Any]]] = None,
     ):
         if isinstance(columns, (str, bytes)):
             raise ReportStoreValidationError("columns must contain field declarations")
@@ -71,12 +75,21 @@ class TableReport:
         normalized_temporal_mode = normalize_temporal_mode(
             temporal_mode, granularity, measures, "Table"
         )
+        normalized_row_order = cls._normalize_row_order(
+            normalized_columns, row_order
+        )
 
         definition = ReportDefinition.create(
             report_type="table",
             contract_version=TABLE_CONTRACT_VERSION,
             fields=normalized_columns,
             binding={"columns": [column.name for column in normalized_columns]},
+            options={
+                "row_order": {
+                    name: list(values)
+                    for name, values in normalized_row_order.items()
+                }
+            } if normalized_row_order else None,
             temporal_mode=normalized_temporal_mode,
         )
         report = store._declare_typed_report(
@@ -86,7 +99,40 @@ class TableReport:
             granularity=granularity,
             definition_json=definition.to_json(),
         )
-        return cls(report, granularity, normalized_columns)
+        return cls(report, granularity, normalized_columns, normalized_row_order)
+
+    @staticmethod
+    def _normalize_row_order(
+        columns: Sequence[Field],
+        row_order: Optional[Mapping[str, Iterable[Any]]],
+    ) -> Dict[str, Tuple[Any, ...]]:
+        if row_order is None:
+            return {}
+        if not isinstance(row_order, Mapping) or not row_order:
+            raise ReportStoreValidationError(
+                "Table row_order must be a non-empty mapping of dimension names to values"
+            )
+        dimensions = {
+            column.name: column
+            for column in columns
+            if isinstance(column, Dimension)
+        }
+        unknown = set(row_order) - set(dimensions)
+        if unknown:
+            raise ReportStoreValidationError(
+                f"Table row_order contains unknown dimension fields: {sorted(unknown)}"
+            )
+        normalized = {}
+        for name, values in row_order.items():
+            order = normalize_value_order(
+                "Table", f"row_order['{name}']", dimensions[name], values
+            )
+            if order is None:
+                raise ReportStoreValidationError(
+                    f"Table row_order['{name}'] must be non-empty"
+                )
+            normalized[name] = order
+        return normalized
 
     def append_rows(
         self,
@@ -241,4 +287,10 @@ class TableReport:
             raise ReportStoreValidationError(
                 f"Report '{self.key}' row {index} must contain a dimension value"
             )
+        for name, values in self.row_order.items():
+            if dimensions.get(name) not in values:
+                raise ReportStoreValidationError(
+                    f"Table row {index} value '{dimensions.get(name)}' is not declared "
+                    f"in row_order['{name}']"
+                )
         return normalized

pam/templates/init/REPORTS-th.md

@@ -399,6 +399,7 @@ table = store.table(
         Dimension("branch", label="สาขา", value_type="string"),
         Measure("members", label="สมาชิก", value_type="integer", unit="คน"),
     ],
+    row_order={"branch": ["กรุงเทพฯ", "เชียงใหม่", "รวม"]},
 )
 
 table.append_rows(
@@ -413,6 +414,8 @@ table.append_rows(
 - Required column ต้องมีครบและค่าต้องตรงชนิด
 - Row ใน Report เดียวกันห้ามมี generated identity ซ้ำ
 - CMS ใช้ลำดับ column จาก definition ไม่ใช่ row แรก
+- `row_order` กำหนดลำดับค่าของ Dimension ได้ โดยค่าที่เขียนต้องอยู่ในรายการทั้งหมด
+  เช่น วาง `รวม` เป็นตัวสุดท้ายเพื่อให้อยู่ล่างสุดเสมอ
 - Partition เป็น metadata สำหรับ range/order ไม่ถูกเพิ่มเป็น Day/Month column พิเศษ
 - `remove_rows` รับเฉพาะ Dimension identity; Measure ไม่ใช่ identity
 

pam/templates/init/REPORTS.md

@@ -558,11 +558,17 @@ table = store.table(
             unit="THB",
         ),
     ],
+    row_order={
+        "branch": ["Bangkok", "Chiang Mai", "Total"],
+    },
 )
 ```
 
 Column order is the declaration order. At least one dimension is required. By
-default, all dimension values form the stable row identity.
+default, all dimension values form the stable row identity. Optional `row_order`
+maps Dimension names to their complete display order. Every written value for an
+ordered Dimension must appear in that list; place values such as `Total` last when
+they must remain at the bottom of the table.
 
 ## Writing rows
 

{pam_python-0.2.18.dist-info → pam_python-0.2.19.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.2.18
+Version: 0.2.19
 Summary: Pam Python Library
 Author-email: Narongrit Kanhanoi <narongrit@pams.ai>
 Project-URL: Homepage, https://github.com/heart/pam-python

{pam_python-0.2.18.dist-info → pam_python-0.2.19.dist-info}/RECORD

@@ -1,4 +1,4 @@
-pam/__init__.py,sha256=EPwLYPy_XyrD-Pj5t3E9m73WOd0PDLIEJ299GVK-UJg,57
+pam/__init__.py,sha256=FJm-IRTRlhqCfc4j3SOZSm0M6COGOUIQWtufhNDjpAA,57
 pam/api.py,sha256=nfsq9OLHutitRMqwkoi3mD0gZ3EfMUzN2rwmS9gpVpY,8198
 pam/cli.py,sha256=Ip4kYNbZ49WAkcMN4SuNc2qXxDeagOzJwE7GSb-BYlE,13831
 pam/datetime_utils.py,sha256=sDFxNRR46FsO61p-EzhmIRS6ARnfMPRquKee_RcQ_3E,664
@@ -44,16 +44,16 @@ pam/reports/record.py,sha256=ttFKu97794CFzNgwXOdD6SU0gozqwPcm2WiOdfSOGQs,5287
 pam/reports/report.py,sha256=yZDjuLhkQ-1BdN51imKtFUnXuQjLOt3Ia4Z0hh7BxBQ,1229
 pam/reports/scatter.py,sha256=0VgX0Uu3C5_W5WWAdnjcmOHNe3CXKK3CHNneGEAgvrI,4127
 pam/reports/schema.py,sha256=qYOzlRWIUzIMjE-x4HYCuobdlEve5ylPEt-9r6kPO00,1231
-pam/reports/store.py,sha256=aH90Kb4zZ4U_NT9ltMH2YNQRnJcycEr-okMV5WD92Bs,25756
-pam/reports/table.py,sha256=n0FEIOw2hlrrcHqYwXZVo8r2XkgzVN0EqQ9zaaJBarc,8760
+pam/reports/store.py,sha256=BZSarCtGRlHnG_MiA2z19TsftcffCJUQ4TjccHyIIDw,25863
+pam/reports/table.py,sha256=33kx8T_rB_TwFsTTYKOxABJGClWAJYpJ08EijR5c5Dw,10877
 pam/reports/temporal.py,sha256=s3aEjoJ9c5hMI4NDaStqdDP7PksNgXlDf0Xfp55VSPc,1806
 pam/reports/transport.py,sha256=iDm63RQnPfhCJ1zFbr1uAVYHz3ondNfp2scz21JAnL8,2111
 pam/reports/treemap.py,sha256=W_VwxbiRMSvkNpY2z1HfbZtGKWXNr6FdbVdI0grVesw,4251
 pam/templates/buildcmd/pamb,sha256=58GCN59ysvHGNhPvTD3nkF4aLg-kM1WfWmH7CL3eQVo,530
 pam/templates/buildcmd/pamb-base.sh,sha256=Q0DkbeHtPx33PIjc68EeI7ZIwBOLlwcSmPhpxALXxVY,518
 pam/templates/init/AGENT.md,sha256=yOtdr5aSsqPbjh7gWbyfoFYnCZ7opVSF9ol0LbONCTw,27030
-pam/templates/init/REPORTS-th.md,sha256=tKL8za7nxIG6jxBPzwqK00nfDdh8xe-lM34ueAU4WAQ,35752
-pam/templates/init/REPORTS.md,sha256=7yYbC2A7A92_NZloozJSkJaFL-bIddrrgcsSDpuIWaA,49561
+pam/templates/init/REPORTS-th.md,sha256=VdGUFvxU0Zl6pYKgFHIC6U8pmQJcz4JFM7_QYbcXblc,36196
+pam/templates/init/REPORTS.md,sha256=LCMXW1SLRpOz2yWYM5Pp_B7H90E_X_aQ9vXYvHhEJgc,49868
 pam/templates/init/dockerignore.tmpl,sha256=Ht1eCgQLqalEwpUjih0FQavzhYJbT2jH-FP4btM3960,52
 pam/templates/init/gitignore.tmpl,sha256=xi8KBrPKSCPiuwtKP8xsF4shQbYowh1_LGW3fKbl09M,917
 pam/templates/init/main.tmpl,sha256=CtrwBpk5610OGa0KscawpfcDuAciRfpnqQvGydvD0KI,260
@@ -73,9 +73,9 @@ pam/templates/service/pandas/service_class.tmpl,sha256=qaq9tqRhxogWQlqi09dbX5vLu
 pam/templates/service/polars/functions.tmpl,sha256=7Qlwsd5Q1vdkOvXHtlltjb2oS-i7JuNKPor2iNDSsQg,701
 pam/templates/service/polars/service.test.tmpl,sha256=nC6VoauZMYy_UTTXxxergfWbXvUD_VWwpM7-7A3aKqE,6881
 pam/templates/service/polars/service_class.tmpl,sha256=jMGeruXduu0eBB7FPDEkZu8b4mSIO3uRt5TiDuNq5T4,3688
-pam_python-0.2.18.dist-info/licenses/LICENSE.txt,sha256=yeHD2-gzrkkET2ZkMe22WyUGpDjlwTrqA4POb0FoZi4,1138
-pam_python-0.2.18.dist-info/METADATA,sha256=bLVH-U_jGsSiAvNfdFKInKbSyVhLWuw9IUcPJm3GNvA,10116
-pam_python-0.2.18.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-pam_python-0.2.18.dist-info/entry_points.txt,sha256=xqYpsIqvNlO0j8elZc02bDwR-12dLK9FU2B1ACsLYxw,37
-pam_python-0.2.18.dist-info/top_level.txt,sha256=0EOjbyc3hQyzjhn6iyMgsEseqA66Xz0p27iBN7G7W1w,4
-pam_python-0.2.18.dist-info/RECORD,,
+pam_python-0.2.19.dist-info/licenses/LICENSE.txt,sha256=yeHD2-gzrkkET2ZkMe22WyUGpDjlwTrqA4POb0FoZi4,1138
+pam_python-0.2.19.dist-info/METADATA,sha256=y4WkR7ZBdQWvV2GkxmuoaBiSNZmLmUHX2-jzd12KYPM,10116
+pam_python-0.2.19.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pam_python-0.2.19.dist-info/entry_points.txt,sha256=xqYpsIqvNlO0j8elZc02bDwR-12dLK9FU2B1ACsLYxw,37
+pam_python-0.2.19.dist-info/top_level.txt,sha256=0EOjbyc3hQyzjhn6iyMgsEseqA66Xz0p27iBN7G7W1w,4
+pam_python-0.2.19.dist-info/RECORD,,