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,157 @@
1
+ """Shared value-semantics types and canonical numeric conventions."""
2
+
3
+ from .decimal_wire import CanonicalDecimalWire, DECIMAL_WIRE_PATTERN
4
+ from .enterprise_value import (
5
+ DatedEnterpriseValueAvailable,
6
+ DatedEnterpriseValueResult,
7
+ DatedEnterpriseValueUnavailable,
8
+ EnterpriseValueComponent,
9
+ EnterpriseValueUnavailableReason,
10
+ derive_dated_enterprise_value,
11
+ )
12
+ from .formatting import format_numeric, normalize_declared_numeric, numeric_unit_tag
13
+ from .forward_ev_adjusted_ebitda import (
14
+ ForwardEvAdjustedEbitdaAvailable,
15
+ ForwardEvAdjustedEbitdaResult,
16
+ ForwardEvAdjustedEbitdaUnavailable,
17
+ ForwardEvAdjustedEbitdaUnavailableReason,
18
+ NtmForwardEvAdjustedEbitdaAvailable,
19
+ NtmForwardEvAdjustedEbitdaResult,
20
+ NtmForwardEvAdjustedEbitdaUnavailable,
21
+ NtmForwardEvAdjustedEbitdaUnavailableReason,
22
+ QuarterlyForwardAdjustedEbitdaEstimate,
23
+ derive_forward_ev_adjusted_ebitda,
24
+ derive_ntm_forward_ev_adjusted_ebitda,
25
+ )
26
+ from .forward_pe import (
27
+ ForwardEpsEstimate,
28
+ ForwardPeAvailable,
29
+ ForwardPeResult,
30
+ ForwardPeUnavailable,
31
+ ForwardPeUnavailableReason,
32
+ Fy1ForwardPeriodAvailable,
33
+ Fy1ForwardPeriodResult,
34
+ Fy1ForwardPeriodUnavailable,
35
+ Fy1ForwardPeriodUnavailableReason,
36
+ NtmForwardPeAvailable,
37
+ NtmForwardPeResult,
38
+ NtmForwardPeUnavailable,
39
+ NtmForwardPeUnavailableReason,
40
+ QuarterlyForwardEpsEstimate,
41
+ derive_forward_pe,
42
+ derive_fy1_forward_pe,
43
+ derive_ntm_forward_pe,
44
+ select_fy1_forward_period,
45
+ )
46
+ from .numeric_display import (
47
+ DenominatorBasis,
48
+ ISO_4217_ALPHA_CODES,
49
+ NumericDisplaySpec,
50
+ NumericKind,
51
+ NumericScale,
52
+ )
53
+ from .period_ref import (
54
+ CalendarYearPeriod,
55
+ DatePeriod,
56
+ FiscalQuarterPeriod,
57
+ FiscalYearPeriod,
58
+ PeriodRange,
59
+ PeriodRef,
60
+ )
61
+ from .quantity import Quantity
62
+ from .reconciliation import (
63
+ ReconciliationComponent,
64
+ TwoStageReconciliationAvailable,
65
+ TwoStageReconciliationResult,
66
+ TwoStageReconciliationUnavailable,
67
+ TwoStageReconciliationUnavailableReason,
68
+ reconcile_two_stage_bridge,
69
+ )
70
+
71
+ from .conventions_ir_v1 import (
72
+ CONVENTIONS_IR_V1,
73
+ ConventionsIRV1,
74
+ DecimalWireConventionV1,
75
+ InclusiveIntegerBoundsV1,
76
+ PeriodFieldV1,
77
+ PeriodRangeRulesV1,
78
+ PeriodRepresentationV1,
79
+ PeriodVariantV1,
80
+ ScaleFactorV1,
81
+ UnitNumericKindBindingV1,
82
+ WeightRuleV1,
83
+ normalize_decimal_v1,
84
+ )
85
+
86
+ __all__ = [
87
+ "CalendarYearPeriod",
88
+ "CanonicalDecimalWire",
89
+ "CONVENTIONS_IR_V1",
90
+ "ConventionsIRV1",
91
+ "DECIMAL_WIRE_PATTERN",
92
+ "DatePeriod",
93
+ "DatedEnterpriseValueAvailable",
94
+ "DatedEnterpriseValueResult",
95
+ "DatedEnterpriseValueUnavailable",
96
+ "DecimalWireConventionV1",
97
+ "DenominatorBasis",
98
+ "FiscalQuarterPeriod",
99
+ "FiscalYearPeriod",
100
+ "ForwardEpsEstimate",
101
+ "ForwardEvAdjustedEbitdaAvailable",
102
+ "ForwardEvAdjustedEbitdaResult",
103
+ "ForwardEvAdjustedEbitdaUnavailable",
104
+ "ForwardEvAdjustedEbitdaUnavailableReason",
105
+ "ForwardPeAvailable",
106
+ "ForwardPeResult",
107
+ "ForwardPeUnavailable",
108
+ "ForwardPeUnavailableReason",
109
+ "Fy1ForwardPeriodAvailable",
110
+ "Fy1ForwardPeriodResult",
111
+ "Fy1ForwardPeriodUnavailable",
112
+ "Fy1ForwardPeriodUnavailableReason",
113
+ "EnterpriseValueComponent",
114
+ "EnterpriseValueUnavailableReason",
115
+ "NtmForwardEvAdjustedEbitdaAvailable",
116
+ "NtmForwardEvAdjustedEbitdaResult",
117
+ "NtmForwardEvAdjustedEbitdaUnavailable",
118
+ "NtmForwardEvAdjustedEbitdaUnavailableReason",
119
+ "NtmForwardPeAvailable",
120
+ "NtmForwardPeResult",
121
+ "NtmForwardPeUnavailable",
122
+ "NtmForwardPeUnavailableReason",
123
+ "QuarterlyForwardAdjustedEbitdaEstimate",
124
+ "QuarterlyForwardEpsEstimate",
125
+ "ReconciliationComponent",
126
+ "derive_dated_enterprise_value",
127
+ "derive_forward_ev_adjusted_ebitda",
128
+ "derive_forward_pe",
129
+ "derive_fy1_forward_pe",
130
+ "derive_ntm_forward_ev_adjusted_ebitda",
131
+ "derive_ntm_forward_pe",
132
+ "select_fy1_forward_period",
133
+ "reconcile_two_stage_bridge",
134
+ "format_numeric",
135
+ "ISO_4217_ALPHA_CODES",
136
+ "InclusiveIntegerBoundsV1",
137
+ "NumericDisplaySpec",
138
+ "NumericKind",
139
+ "NumericScale",
140
+ "normalize_declared_numeric",
141
+ "numeric_unit_tag",
142
+ "PeriodFieldV1",
143
+ "PeriodRange",
144
+ "PeriodRangeRulesV1",
145
+ "PeriodRef",
146
+ "PeriodRepresentationV1",
147
+ "PeriodVariantV1",
148
+ "Quantity",
149
+ "ScaleFactorV1",
150
+ "TwoStageReconciliationAvailable",
151
+ "TwoStageReconciliationResult",
152
+ "TwoStageReconciliationUnavailable",
153
+ "TwoStageReconciliationUnavailableReason",
154
+ "UnitNumericKindBindingV1",
155
+ "WeightRuleV1",
156
+ "normalize_decimal_v1",
157
+ ]
@@ -0,0 +1,99 @@
1
+ """Display-declaration guards for manifest-driven comps producers.
2
+
3
+ Relocated verbatim from risk_module/utils/comps_manifest_display.py (single source).
4
+ Self-contained + stdlib-only so a clean AI-excel-addin checkout can import it without
5
+ pulling risk_module's `config` package or the fmp-mcp-dist gap. FROZEN contract module.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import ast
11
+ from typing import Any
12
+
13
+
14
+ _WITHHELD_SOURCE_KINDS = frozenset({"kpi", "transcript_kpi"})
15
+
16
+
17
+ def ast_referenced_names(expression: ast.AST | str) -> frozenset[str]:
18
+ """Return the names consumed by the derived-formula evaluator."""
19
+
20
+ parsed = ast.parse(expression, mode="eval") if isinstance(expression, str) else expression
21
+ return frozenset(
22
+ node.id for node in ast.walk(parsed) if isinstance(node, ast.Name)
23
+ )
24
+
25
+
26
+ def namespace_names_for(key: str) -> tuple[str, ...]:
27
+ """Names under which one resolved metric can enter a derived formula."""
28
+
29
+ return (key, f"{key}_prior", f"{key}_prev")
30
+
31
+
32
+ def withheld_display_metric_keys(
33
+ manifest: Any,
34
+ ) -> frozenset[str]:
35
+ """Close transcript-tainted manifest metrics over derived dependencies."""
36
+
37
+ metrics = [metric for section in manifest.sections for metric in section.metrics]
38
+ withheld = {
39
+ metric.key
40
+ for metric in metrics
41
+ if metric.source.kind in _WITHHELD_SOURCE_KINDS
42
+ and not (
43
+ metric.display is not None
44
+ and metric.display.numeric_kind == "percentage"
45
+ )
46
+ }
47
+
48
+ changed = True
49
+ while changed:
50
+ changed = False
51
+ tainted_names = {
52
+ name for key in withheld for name in namespace_names_for(key)
53
+ }
54
+ for metric in metrics:
55
+ if metric.source.kind != "derived" or metric.key in withheld:
56
+ continue
57
+ formula = metric.source.derived_formula
58
+ if formula and ast_referenced_names(formula).intersection(tainted_names):
59
+ withheld.add(metric.key)
60
+ changed = True
61
+
62
+ return frozenset(withheld)
63
+
64
+
65
+ def display_for_metric(metric: Any, withheld: frozenset[str]) -> Any:
66
+ """Return the declaration safe to stamp at every metric construction site."""
67
+
68
+ if metric.key in withheld:
69
+ return None
70
+ return metric.display
71
+
72
+
73
+ def enforce_withheld_display(
74
+ metric: Any,
75
+ withheld: frozenset[str],
76
+ stamped_display: Any,
77
+ ) -> None:
78
+ """Reject any display stamp on a metric closed into the withheld set."""
79
+
80
+ if metric.key in withheld and stamped_display is not None:
81
+ raise ValueError(
82
+ f"withheld metric {metric.key!r} must not carry a display spec"
83
+ )
84
+
85
+
86
+ def require_snapshot_compatible_manifest(manifest: Any) -> None:
87
+ """Reject source kinds the snapshot producer cannot dispatch safely."""
88
+
89
+ unsupported = sorted(
90
+ metric.key
91
+ for section in manifest.sections
92
+ for metric in section.metrics
93
+ if metric.source.kind in _WITHHELD_SOURCE_KINDS
94
+ )
95
+ if unsupported:
96
+ raise ValueError(
97
+ "snapshot comps manifest cannot bind kpi/transcript_kpi sources: "
98
+ + ", ".join(unsupported)
99
+ )