value-semantics-core 2.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,503 @@
1
+ """VERSIONED, frozen v1 value-semantics conventions intermediate representation.
2
+
3
+ Changing any v1 content is a contract event. A successor must be implemented in
4
+ a new ``conventions_ir_v2`` module; this module is never edited to redefine v1.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from dataclasses import dataclass
10
+ from decimal import Decimal
11
+ from typing import Final
12
+
13
+
14
+ @dataclass(frozen=True, slots=True)
15
+ class ScaleFactorV1:
16
+ """One declared numeric scale and its absolute-value multiplier."""
17
+
18
+ numeric_scale: str
19
+ multiplier: int
20
+
21
+
22
+ @dataclass(frozen=True, slots=True)
23
+ class WeightRuleV1:
24
+ """Finite numeric range and sign rule for one denominator basis."""
25
+
26
+ denominator_basis: str
27
+ permits_negative: bool
28
+ minimum: str | None
29
+ maximum: str | None
30
+ minimum_inclusive: bool | None
31
+ maximum_inclusive: bool | None
32
+
33
+
34
+ @dataclass(frozen=True, slots=True)
35
+ class UnitNumericKindBindingV1:
36
+ """One Excel-model Unit to NumericKind binding."""
37
+
38
+ unit: str
39
+ numeric_kind: str
40
+
41
+
42
+ @dataclass(frozen=True, slots=True)
43
+ class DecimalWireConventionV1:
44
+ """Canonical finite-Decimal wire grammar and normalization metadata."""
45
+
46
+ regex: str
47
+ normalization_algorithm: str
48
+ normalization_rule: str
49
+ non_finite_handling: str
50
+
51
+
52
+ @dataclass(frozen=True, slots=True)
53
+ class PeriodFieldV1:
54
+ """One required field in a closed PeriodRef variant."""
55
+
56
+ name: str
57
+ type: str
58
+
59
+
60
+ @dataclass(frozen=True, slots=True)
61
+ class PeriodVariantV1:
62
+ """One deterministically ordered PeriodRef variant declaration."""
63
+
64
+ kind: str
65
+ fields: tuple[PeriodFieldV1, ...]
66
+ canonical_projection_format: str
67
+
68
+
69
+ @dataclass(frozen=True, slots=True)
70
+ class InclusiveIntegerBoundsV1:
71
+ """Inclusive integer bounds shared by declared period year fields."""
72
+
73
+ minimum: int
74
+ maximum: int
75
+
76
+
77
+ @dataclass(frozen=True, slots=True)
78
+ class PeriodRangeRulesV1:
79
+ """Closed validation rules for the PeriodRef period_range variant."""
80
+
81
+ endpoint_kinds_must_match: bool
82
+ maximum_range_depth: int
83
+ endpoints_inclusive: bool
84
+ ordering: str
85
+
86
+
87
+ @dataclass(frozen=True, slots=True)
88
+ class PeriodRepresentationV1:
89
+ """Sole-wire and derived-projection contract for PeriodRef v1."""
90
+
91
+ discriminator_field: str
92
+ wire_form: str
93
+ accepts_string_input: bool
94
+ projection_is_derived_only: bool
95
+ extra_fields: str
96
+ variants_frozen: bool
97
+ variants: tuple[PeriodVariantV1, ...]
98
+ year_bounds: InclusiveIntegerBoundsV1
99
+ quarter_bounds: InclusiveIntegerBoundsV1
100
+ date_format: str
101
+ date_requires_real_calendar_date: bool
102
+ range_rules: PeriodRangeRulesV1
103
+
104
+
105
+ @dataclass(frozen=True, slots=True)
106
+ class ConventionsIRV1:
107
+ """Deeply immutable, deterministically ordered v1 convention data."""
108
+
109
+ numeric_kinds: tuple[str, ...]
110
+ numeric_scales: tuple[str, ...]
111
+ denominator_bases: tuple[str, ...]
112
+ scale_factors: tuple[ScaleFactorV1, ...]
113
+ weight_rules: tuple[WeightRuleV1, ...]
114
+ iso_4217_alpha_codes: tuple[str, ...]
115
+ unit_to_numeric_kind: tuple[UnitNumericKindBindingV1, ...]
116
+ decimal_wire: DecimalWireConventionV1
117
+ period: PeriodRepresentationV1
118
+
119
+
120
+ _DECIMAL_WIRE_REGEX = r"^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$"
121
+ _DECIMAL_NORMALIZATION_ALGORITHM = "finite-decimal-fixed-point/v1"
122
+ _DECIMAL_NORMALIZATION_RULE = (
123
+ "Reject non-finite values. Expand a finite base-10 Decimal exponent into "
124
+ "plain fixed-point digits, preserve its sign and represented fractional "
125
+ "trailing zeros, include a zero before a fractional point, omit any leading "
126
+ "plus sign, and never emit exponent notation."
127
+ )
128
+
129
+
130
+ CONVENTIONS_IR_V1: Final[ConventionsIRV1] = ConventionsIRV1(
131
+ numeric_kinds=(
132
+ "currency",
133
+ "percentage",
134
+ "basis_points",
135
+ "multiple",
136
+ "count",
137
+ "per_share",
138
+ "ratio",
139
+ "index",
140
+ "duration",
141
+ "date",
142
+ "weight",
143
+ ),
144
+ numeric_scales=("unit", "thousands", "millions", "billions"),
145
+ denominator_bases=(
146
+ "nav",
147
+ "gross_exposure",
148
+ "net_exposure",
149
+ "portfolio_value",
150
+ "total_market_value",
151
+ "benchmark_total",
152
+ "fund_total",
153
+ ),
154
+ scale_factors=(
155
+ ScaleFactorV1(numeric_scale="unit", multiplier=1),
156
+ ScaleFactorV1(numeric_scale="thousands", multiplier=1_000),
157
+ ScaleFactorV1(numeric_scale="millions", multiplier=1_000_000),
158
+ ScaleFactorV1(numeric_scale="billions", multiplier=1_000_000_000),
159
+ ),
160
+ weight_rules=(
161
+ WeightRuleV1(
162
+ denominator_basis="nav",
163
+ permits_negative=True,
164
+ minimum=None,
165
+ maximum=None,
166
+ minimum_inclusive=None,
167
+ maximum_inclusive=None,
168
+ ),
169
+ WeightRuleV1(
170
+ denominator_basis="gross_exposure",
171
+ permits_negative=False,
172
+ minimum="0",
173
+ maximum="1",
174
+ minimum_inclusive=True,
175
+ maximum_inclusive=True,
176
+ ),
177
+ WeightRuleV1(
178
+ denominator_basis="net_exposure",
179
+ permits_negative=True,
180
+ minimum=None,
181
+ maximum=None,
182
+ minimum_inclusive=None,
183
+ maximum_inclusive=None,
184
+ ),
185
+ WeightRuleV1(
186
+ denominator_basis="portfolio_value",
187
+ permits_negative=True,
188
+ minimum=None,
189
+ maximum=None,
190
+ minimum_inclusive=None,
191
+ maximum_inclusive=None,
192
+ ),
193
+ WeightRuleV1(
194
+ denominator_basis="total_market_value",
195
+ permits_negative=False,
196
+ minimum="0",
197
+ maximum="1",
198
+ minimum_inclusive=True,
199
+ maximum_inclusive=True,
200
+ ),
201
+ WeightRuleV1(
202
+ denominator_basis="benchmark_total",
203
+ permits_negative=False,
204
+ minimum="0",
205
+ maximum="1",
206
+ minimum_inclusive=True,
207
+ maximum_inclusive=True,
208
+ ),
209
+ WeightRuleV1(
210
+ denominator_basis="fund_total",
211
+ permits_negative=False,
212
+ minimum="0",
213
+ maximum="1",
214
+ minimum_inclusive=True,
215
+ maximum_inclusive=True,
216
+ ),
217
+ ),
218
+ iso_4217_alpha_codes=(
219
+ "AED",
220
+ "AFN",
221
+ "ALL",
222
+ "AMD",
223
+ "AOA",
224
+ "ARS",
225
+ "AUD",
226
+ "AWG",
227
+ "AZN",
228
+ "BAM",
229
+ "BBD",
230
+ "BDT",
231
+ "BHD",
232
+ "BIF",
233
+ "BMD",
234
+ "BND",
235
+ "BOB",
236
+ "BOV",
237
+ "BRL",
238
+ "BSD",
239
+ "BTN",
240
+ "BWP",
241
+ "BYN",
242
+ "BZD",
243
+ "CAD",
244
+ "CDF",
245
+ "CHE",
246
+ "CHF",
247
+ "CHW",
248
+ "CLF",
249
+ "CLP",
250
+ "CNY",
251
+ "COP",
252
+ "COU",
253
+ "CRC",
254
+ "CUP",
255
+ "CVE",
256
+ "CZK",
257
+ "DJF",
258
+ "DKK",
259
+ "DOP",
260
+ "DZD",
261
+ "EGP",
262
+ "ERN",
263
+ "ETB",
264
+ "EUR",
265
+ "FJD",
266
+ "FKP",
267
+ "GBP",
268
+ "GEL",
269
+ "GHS",
270
+ "GIP",
271
+ "GMD",
272
+ "GNF",
273
+ "GTQ",
274
+ "GYD",
275
+ "HKD",
276
+ "HNL",
277
+ "HTG",
278
+ "HUF",
279
+ "IDR",
280
+ "ILS",
281
+ "INR",
282
+ "IQD",
283
+ "IRR",
284
+ "ISK",
285
+ "JMD",
286
+ "JOD",
287
+ "JPY",
288
+ "KES",
289
+ "KGS",
290
+ "KHR",
291
+ "KMF",
292
+ "KPW",
293
+ "KRW",
294
+ "KWD",
295
+ "KYD",
296
+ "KZT",
297
+ "LAK",
298
+ "LBP",
299
+ "LKR",
300
+ "LRD",
301
+ "LSL",
302
+ "LYD",
303
+ "MAD",
304
+ "MDL",
305
+ "MGA",
306
+ "MKD",
307
+ "MMK",
308
+ "MNT",
309
+ "MOP",
310
+ "MRU",
311
+ "MUR",
312
+ "MVR",
313
+ "MWK",
314
+ "MXN",
315
+ "MXV",
316
+ "MYR",
317
+ "MZN",
318
+ "NAD",
319
+ "NGN",
320
+ "NIO",
321
+ "NOK",
322
+ "NPR",
323
+ "NZD",
324
+ "OMR",
325
+ "PAB",
326
+ "PEN",
327
+ "PGK",
328
+ "PHP",
329
+ "PKR",
330
+ "PLN",
331
+ "PYG",
332
+ "QAR",
333
+ "RON",
334
+ "RSD",
335
+ "RUB",
336
+ "RWF",
337
+ "SAR",
338
+ "SBD",
339
+ "SCR",
340
+ "SDG",
341
+ "SEK",
342
+ "SGD",
343
+ "SHP",
344
+ "SLE",
345
+ "SOS",
346
+ "SRD",
347
+ "SSP",
348
+ "STN",
349
+ "SVC",
350
+ "SYP",
351
+ "SZL",
352
+ "THB",
353
+ "TJS",
354
+ "TMT",
355
+ "TND",
356
+ "TOP",
357
+ "TRY",
358
+ "TTD",
359
+ "TWD",
360
+ "TZS",
361
+ "UAH",
362
+ "UGX",
363
+ "USD",
364
+ "USN",
365
+ "UYI",
366
+ "UYU",
367
+ "UYW",
368
+ "UZS",
369
+ "VED",
370
+ "VES",
371
+ "VND",
372
+ "VUV",
373
+ "WST",
374
+ "XAD",
375
+ "XAF",
376
+ "XAG",
377
+ "XAU",
378
+ "XBA",
379
+ "XBB",
380
+ "XBC",
381
+ "XBD",
382
+ "XCD",
383
+ "XCG",
384
+ "XDR",
385
+ "XOF",
386
+ "XPD",
387
+ "XPF",
388
+ "XPT",
389
+ "XSU",
390
+ "XTS",
391
+ "XUA",
392
+ "XXX",
393
+ "YER",
394
+ "ZAR",
395
+ "ZMW",
396
+ "ZWG",
397
+ ),
398
+ unit_to_numeric_kind=(
399
+ UnitNumericKindBindingV1(unit="dollars", numeric_kind="currency"),
400
+ UnitNumericKindBindingV1(unit="percentage", numeric_kind="percentage"),
401
+ UnitNumericKindBindingV1(unit="ratio", numeric_kind="ratio"),
402
+ UnitNumericKindBindingV1(unit="count", numeric_kind="count"),
403
+ UnitNumericKindBindingV1(unit="share_count", numeric_kind="count"),
404
+ UnitNumericKindBindingV1(unit="per_share", numeric_kind="per_share"),
405
+ UnitNumericKindBindingV1(unit="days", numeric_kind="duration"),
406
+ UnitNumericKindBindingV1(unit="date", numeric_kind="date"),
407
+ UnitNumericKindBindingV1(unit="multiple", numeric_kind="multiple"),
408
+ ),
409
+ decimal_wire=DecimalWireConventionV1(
410
+ regex=_DECIMAL_WIRE_REGEX,
411
+ normalization_algorithm=_DECIMAL_NORMALIZATION_ALGORITHM,
412
+ normalization_rule=_DECIMAL_NORMALIZATION_RULE,
413
+ non_finite_handling="reject",
414
+ ),
415
+ period=PeriodRepresentationV1(
416
+ discriminator_field="kind",
417
+ wire_form="json_object_only",
418
+ accepts_string_input=False,
419
+ projection_is_derived_only=True,
420
+ extra_fields="forbid",
421
+ variants_frozen=True,
422
+ variants=(
423
+ PeriodVariantV1(
424
+ kind="fiscal_year",
425
+ fields=(
426
+ PeriodFieldV1(name="kind", type='Literal["fiscal_year"]'),
427
+ PeriodFieldV1(name="fiscal_year", type="int"),
428
+ ),
429
+ canonical_projection_format="FY{fiscal_year}",
430
+ ),
431
+ PeriodVariantV1(
432
+ kind="fiscal_quarter",
433
+ fields=(
434
+ PeriodFieldV1(name="kind", type='Literal["fiscal_quarter"]'),
435
+ PeriodFieldV1(name="fiscal_year", type="int"),
436
+ PeriodFieldV1(name="quarter", type="int"),
437
+ ),
438
+ canonical_projection_format="FY{fiscal_year}-Q{quarter}",
439
+ ),
440
+ PeriodVariantV1(
441
+ kind="date",
442
+ fields=(
443
+ PeriodFieldV1(name="kind", type='Literal["date"]'),
444
+ PeriodFieldV1(name="date", type="str"),
445
+ ),
446
+ canonical_projection_format="{date}",
447
+ ),
448
+ PeriodVariantV1(
449
+ kind="calendar_year",
450
+ fields=(
451
+ PeriodFieldV1(name="kind", type='Literal["calendar_year"]'),
452
+ PeriodFieldV1(name="calendar_year", type="int"),
453
+ ),
454
+ canonical_projection_format="CY{calendar_year}",
455
+ ),
456
+ PeriodVariantV1(
457
+ kind="period_range",
458
+ fields=(
459
+ PeriodFieldV1(name="kind", type='Literal["period_range"]'),
460
+ PeriodFieldV1(name="start", type="PeriodRef"),
461
+ PeriodFieldV1(name="end", type="PeriodRef"),
462
+ ),
463
+ canonical_projection_format="{start}..{end}",
464
+ ),
465
+ ),
466
+ year_bounds=InclusiveIntegerBoundsV1(minimum=1900, maximum=2200),
467
+ quarter_bounds=InclusiveIntegerBoundsV1(minimum=1, maximum=4),
468
+ date_format="YYYY-MM-DD",
469
+ date_requires_real_calendar_date=True,
470
+ range_rules=PeriodRangeRulesV1(
471
+ endpoint_kinds_must_match=True,
472
+ maximum_range_depth=1,
473
+ endpoints_inclusive=True,
474
+ ordering="start<end",
475
+ ),
476
+ ),
477
+ )
478
+
479
+
480
+ def normalize_decimal_v1(value: Decimal) -> str:
481
+ """Normalize a finite Decimal to the v1 plain-notation wire grammar."""
482
+
483
+ if not isinstance(value, Decimal):
484
+ raise TypeError("value must be a Decimal")
485
+ if not value.is_finite():
486
+ raise ValueError("non-finite Decimal values are not permitted")
487
+ return format(value, "f")
488
+
489
+
490
+ __all__ = [
491
+ "CONVENTIONS_IR_V1",
492
+ "ConventionsIRV1",
493
+ "DecimalWireConventionV1",
494
+ "InclusiveIntegerBoundsV1",
495
+ "PeriodFieldV1",
496
+ "PeriodRangeRulesV1",
497
+ "PeriodRepresentationV1",
498
+ "PeriodVariantV1",
499
+ "ScaleFactorV1",
500
+ "UnitNumericKindBindingV1",
501
+ "WeightRuleV1",
502
+ "normalize_decimal_v1",
503
+ ]
@@ -0,0 +1,43 @@
1
+ """Canonical finite-Decimal JSON wire semantics."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from decimal import Decimal, InvalidOperation
6
+ import re
7
+ from typing import Annotated, TypeAlias
8
+
9
+ from pydantic import BeforeValidator, Field, PlainSerializer
10
+
11
+ from .conventions_ir_v1 import CONVENTIONS_IR_V1, normalize_decimal_v1
12
+
13
+
14
+ DECIMAL_WIRE_PATTERN: str = CONVENTIONS_IR_V1.decimal_wire.regex
15
+ DECIMAL_WIRE_RE = re.compile(DECIMAL_WIRE_PATTERN)
16
+
17
+
18
+ def _require_decimal_wire_string(value: object) -> Decimal:
19
+ if not isinstance(value, str) or not value or value != value.strip():
20
+ raise ValueError("quantity wire values must be nonempty JSON strings")
21
+ if DECIMAL_WIRE_RE.fullmatch(value) is None:
22
+ raise ValueError("quantity wire values must use canonical decimal notation")
23
+ try:
24
+ number = Decimal(value)
25
+ except InvalidOperation as exc:
26
+ raise ValueError("quantity wire value is not a decimal") from exc
27
+ if not number.is_finite():
28
+ raise ValueError("quantity wire values must be finite")
29
+ return number
30
+
31
+
32
+ CanonicalDecimalWire: TypeAlias = Annotated[
33
+ Decimal,
34
+ BeforeValidator(_require_decimal_wire_string),
35
+ PlainSerializer(normalize_decimal_v1, return_type=str, when_used="json"),
36
+ Field(
37
+ allow_inf_nan=False,
38
+ json_schema_extra={"pattern": DECIMAL_WIRE_PATTERN},
39
+ ),
40
+ ]
41
+
42
+
43
+ __all__ = ["CanonicalDecimalWire", "DECIMAL_WIRE_PATTERN"]