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.
- value_semantics_core/__init__.py +157 -0
- value_semantics_core/comps_manifest_display.py +99 -0
- value_semantics_core/conventions_ir_v1.py +503 -0
- value_semantics_core/decimal_wire.py +43 -0
- value_semantics_core/enterprise_value.py +223 -0
- value_semantics_core/formatting.py +220 -0
- value_semantics_core/forward_ev_adjusted_ebitda.py +669 -0
- value_semantics_core/forward_pe.py +751 -0
- value_semantics_core/numeric_display.py +129 -0
- value_semantics_core/period_ref.py +120 -0
- value_semantics_core/quantity.py +18 -0
- value_semantics_core/reconciliation.py +362 -0
- value_semantics_core-2.1.0.dist-info/METADATA +6 -0
- value_semantics_core-2.1.0.dist-info/RECORD +16 -0
- value_semantics_core-2.1.0.dist-info/WHEEL +5 -0
- value_semantics_core-2.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,669 @@
|
|
|
1
|
+
"""Exact forward enterprise-value / adjusted-EBITDA arithmetic.
|
|
2
|
+
|
|
3
|
+
This module owns only provider-neutral Decimal semantics. Source identity,
|
|
4
|
+
fiscal alignment, currency, estimate definition, and issuer reconciliation are
|
|
5
|
+
validated by the calling product contract before this primitive is invoked.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from collections import Counter
|
|
11
|
+
from collections.abc import Sequence
|
|
12
|
+
from dataclasses import dataclass, field
|
|
13
|
+
from datetime import date, timedelta
|
|
14
|
+
from decimal import Decimal, ROUND_HALF_EVEN, localcontext
|
|
15
|
+
from typing import Literal, TypeAlias
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
ForwardEvAdjustedEbitdaUnavailableReason: TypeAlias = Literal[
|
|
19
|
+
"non_positive_enterprise_value",
|
|
20
|
+
"non_positive_adjusted_ebitda",
|
|
21
|
+
]
|
|
22
|
+
|
|
23
|
+
NtmForwardEvAdjustedEbitdaUnavailableReason: TypeAlias = Literal[
|
|
24
|
+
"missing_fiscal_anchor",
|
|
25
|
+
"missing_close_date",
|
|
26
|
+
"fiscal_anchor_postdates_close",
|
|
27
|
+
"invalid_enterprise_value",
|
|
28
|
+
"insufficient_future_quarters",
|
|
29
|
+
"duplicate_future_period",
|
|
30
|
+
"overlapping_future_periods",
|
|
31
|
+
"gapped_future_periods",
|
|
32
|
+
"non_quarterly_period_cadence",
|
|
33
|
+
"non_positive_aggregate_adjusted_ebitda",
|
|
34
|
+
]
|
|
35
|
+
|
|
36
|
+
_NTM_UNAVAILABLE_REASONS = frozenset(
|
|
37
|
+
{
|
|
38
|
+
"missing_fiscal_anchor",
|
|
39
|
+
"missing_close_date",
|
|
40
|
+
"fiscal_anchor_postdates_close",
|
|
41
|
+
"invalid_enterprise_value",
|
|
42
|
+
"insufficient_future_quarters",
|
|
43
|
+
"duplicate_future_period",
|
|
44
|
+
"overlapping_future_periods",
|
|
45
|
+
"gapped_future_periods",
|
|
46
|
+
"non_quarterly_period_cadence",
|
|
47
|
+
"non_positive_aggregate_adjusted_ebitda",
|
|
48
|
+
}
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
_MIN_INCLUSIVE_QUARTER_DAYS = 70
|
|
52
|
+
_MAX_INCLUSIVE_QUARTER_DAYS = 105
|
|
53
|
+
_MIN_FOUR_QUARTER_HORIZON_DAYS = 350
|
|
54
|
+
_MAX_FOUR_QUARTER_HORIZON_DAYS = 385
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def _require_finite_decimal(value: Decimal, *, field_name: str) -> None:
|
|
58
|
+
if not isinstance(value, Decimal):
|
|
59
|
+
raise TypeError(f"{field_name} must be Decimal")
|
|
60
|
+
if not value.is_finite():
|
|
61
|
+
raise ValueError(f"{field_name} must be finite")
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def _require_quantum(quantum: Decimal) -> None:
|
|
65
|
+
_require_finite_decimal(quantum, field_name="quantum")
|
|
66
|
+
if quantum <= 0:
|
|
67
|
+
raise ValueError("quantum must be positive")
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def _quantization_precision(
|
|
71
|
+
enterprise_value: Decimal,
|
|
72
|
+
adjusted_ebitda: Decimal,
|
|
73
|
+
quantum: Decimal,
|
|
74
|
+
) -> int:
|
|
75
|
+
quotient_integer_digits = max(
|
|
76
|
+
1,
|
|
77
|
+
enterprise_value.adjusted() - adjusted_ebitda.adjusted() + 2,
|
|
78
|
+
)
|
|
79
|
+
quantum_fractional_digits = max(0, -int(quantum.as_tuple().exponent))
|
|
80
|
+
operand_digits = len(enterprise_value.as_tuple().digits) + len(
|
|
81
|
+
adjusted_ebitda.as_tuple().digits
|
|
82
|
+
)
|
|
83
|
+
return max(
|
|
84
|
+
28,
|
|
85
|
+
quotient_integer_digits + quantum_fractional_digits + operand_digits + 8,
|
|
86
|
+
)
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def _derive_ev_multiple(
|
|
90
|
+
*,
|
|
91
|
+
enterprise_value: Decimal,
|
|
92
|
+
adjusted_ebitda: Decimal,
|
|
93
|
+
quantum: Decimal,
|
|
94
|
+
) -> Decimal:
|
|
95
|
+
"""Divide positive Decimal operands using one canonical rounding path."""
|
|
96
|
+
|
|
97
|
+
with localcontext() as context:
|
|
98
|
+
context.prec = _quantization_precision(
|
|
99
|
+
enterprise_value,
|
|
100
|
+
adjusted_ebitda,
|
|
101
|
+
quantum,
|
|
102
|
+
)
|
|
103
|
+
return (enterprise_value / adjusted_ebitda).quantize(
|
|
104
|
+
quantum,
|
|
105
|
+
rounding=ROUND_HALF_EVEN,
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
@dataclass(frozen=True, slots=True)
|
|
110
|
+
class ForwardEvAdjustedEbitdaAvailable:
|
|
111
|
+
"""One exact multiple and the two normalized arithmetic operands."""
|
|
112
|
+
|
|
113
|
+
multiple: Decimal
|
|
114
|
+
enterprise_value: Decimal
|
|
115
|
+
adjusted_ebitda: Decimal
|
|
116
|
+
status: Literal["available"] = field(default="available", init=False)
|
|
117
|
+
|
|
118
|
+
def __post_init__(self) -> None:
|
|
119
|
+
for field_name, value in (
|
|
120
|
+
("multiple", self.multiple),
|
|
121
|
+
("enterprise_value", self.enterprise_value),
|
|
122
|
+
("adjusted_ebitda", self.adjusted_ebitda),
|
|
123
|
+
):
|
|
124
|
+
_require_finite_decimal(value, field_name=field_name)
|
|
125
|
+
if self.multiple <= 0:
|
|
126
|
+
raise ValueError("multiple must be positive")
|
|
127
|
+
if self.enterprise_value <= 0:
|
|
128
|
+
raise ValueError("enterprise_value must be positive")
|
|
129
|
+
if self.adjusted_ebitda <= 0:
|
|
130
|
+
raise ValueError("adjusted_ebitda must be positive")
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
@dataclass(frozen=True, slots=True)
|
|
134
|
+
class ForwardEvAdjustedEbitdaUnavailable:
|
|
135
|
+
"""A closed domain reason that the multiple cannot be calculated."""
|
|
136
|
+
|
|
137
|
+
reason: ForwardEvAdjustedEbitdaUnavailableReason
|
|
138
|
+
enterprise_value: Decimal
|
|
139
|
+
adjusted_ebitda: Decimal
|
|
140
|
+
status: Literal["unavailable"] = field(default="unavailable", init=False)
|
|
141
|
+
|
|
142
|
+
def __post_init__(self) -> None:
|
|
143
|
+
if self.reason not in {
|
|
144
|
+
"non_positive_enterprise_value",
|
|
145
|
+
"non_positive_adjusted_ebitda",
|
|
146
|
+
}:
|
|
147
|
+
raise ValueError("unsupported forward EV/adjusted-EBITDA reason")
|
|
148
|
+
_require_finite_decimal(
|
|
149
|
+
self.enterprise_value,
|
|
150
|
+
field_name="enterprise_value",
|
|
151
|
+
)
|
|
152
|
+
_require_finite_decimal(
|
|
153
|
+
self.adjusted_ebitda,
|
|
154
|
+
field_name="adjusted_ebitda",
|
|
155
|
+
)
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
ForwardEvAdjustedEbitdaResult: TypeAlias = (
|
|
159
|
+
ForwardEvAdjustedEbitdaAvailable | ForwardEvAdjustedEbitdaUnavailable
|
|
160
|
+
)
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def derive_forward_ev_adjusted_ebitda(
|
|
164
|
+
*,
|
|
165
|
+
enterprise_value: Decimal,
|
|
166
|
+
adjusted_ebitda: Decimal,
|
|
167
|
+
quantum: Decimal,
|
|
168
|
+
) -> ForwardEvAdjustedEbitdaResult:
|
|
169
|
+
"""Divide exact positive EV by exact positive adjusted EBITDA."""
|
|
170
|
+
|
|
171
|
+
_require_finite_decimal(enterprise_value, field_name="enterprise_value")
|
|
172
|
+
_require_finite_decimal(adjusted_ebitda, field_name="adjusted_ebitda")
|
|
173
|
+
_require_quantum(quantum)
|
|
174
|
+
if enterprise_value <= 0:
|
|
175
|
+
return ForwardEvAdjustedEbitdaUnavailable(
|
|
176
|
+
reason="non_positive_enterprise_value",
|
|
177
|
+
enterprise_value=enterprise_value,
|
|
178
|
+
adjusted_ebitda=adjusted_ebitda,
|
|
179
|
+
)
|
|
180
|
+
if adjusted_ebitda <= 0:
|
|
181
|
+
return ForwardEvAdjustedEbitdaUnavailable(
|
|
182
|
+
reason="non_positive_adjusted_ebitda",
|
|
183
|
+
enterprise_value=enterprise_value,
|
|
184
|
+
adjusted_ebitda=adjusted_ebitda,
|
|
185
|
+
)
|
|
186
|
+
multiple = _derive_ev_multiple(
|
|
187
|
+
enterprise_value=enterprise_value,
|
|
188
|
+
adjusted_ebitda=adjusted_ebitda,
|
|
189
|
+
quantum=quantum,
|
|
190
|
+
)
|
|
191
|
+
return ForwardEvAdjustedEbitdaAvailable(
|
|
192
|
+
multiple=multiple,
|
|
193
|
+
enterprise_value=enterprise_value,
|
|
194
|
+
adjusted_ebitda=adjusted_ebitda,
|
|
195
|
+
)
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
def _require_date(value: date, *, field_name: str) -> None:
|
|
199
|
+
if type(value) is not date:
|
|
200
|
+
raise TypeError(f"{field_name} must be date")
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
def _require_analyst_count(value: int | None) -> None:
|
|
204
|
+
if value is None:
|
|
205
|
+
return
|
|
206
|
+
if type(value) is not int or value < 0:
|
|
207
|
+
raise ValueError("analyst_count must be a non-negative int or None")
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
@dataclass(frozen=True, slots=True)
|
|
211
|
+
class QuarterlyForwardAdjustedEbitdaEstimate:
|
|
212
|
+
"""One sourced quarterly adjusted-EBITDA estimate with exact boundaries."""
|
|
213
|
+
|
|
214
|
+
fact_id: str
|
|
215
|
+
period_start: date
|
|
216
|
+
period_end: date
|
|
217
|
+
adjusted_ebitda: Decimal
|
|
218
|
+
analyst_count: int | None = None
|
|
219
|
+
|
|
220
|
+
def __post_init__(self) -> None:
|
|
221
|
+
if not isinstance(self.fact_id, str) or not self.fact_id.strip():
|
|
222
|
+
raise ValueError("fact_id must be a non-empty str")
|
|
223
|
+
if self.fact_id != self.fact_id.strip():
|
|
224
|
+
raise ValueError("fact_id must not have surrounding whitespace")
|
|
225
|
+
_require_date(self.period_start, field_name="period_start")
|
|
226
|
+
_require_date(self.period_end, field_name="period_end")
|
|
227
|
+
if self.period_start >= self.period_end:
|
|
228
|
+
raise ValueError("quarter period requires period_start < period_end")
|
|
229
|
+
_require_finite_decimal(
|
|
230
|
+
self.adjusted_ebitda,
|
|
231
|
+
field_name="adjusted_ebitda",
|
|
232
|
+
)
|
|
233
|
+
_require_analyst_count(self.analyst_count)
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
def _ambiguous_quarter_estimates(
|
|
237
|
+
estimates: Sequence[QuarterlyForwardAdjustedEbitdaEstimate],
|
|
238
|
+
*,
|
|
239
|
+
selected: Sequence[QuarterlyForwardAdjustedEbitdaEstimate],
|
|
240
|
+
) -> tuple[QuarterlyForwardAdjustedEbitdaEstimate, ...]:
|
|
241
|
+
"""Return facts that conflict with a selected horizon dimension."""
|
|
242
|
+
|
|
243
|
+
fact_id_counts = Counter(estimate.fact_id for estimate in estimates)
|
|
244
|
+
period_start_counts = Counter(estimate.period_start for estimate in estimates)
|
|
245
|
+
period_end_counts = Counter(estimate.period_end for estimate in estimates)
|
|
246
|
+
ambiguous_fact_ids = {
|
|
247
|
+
estimate.fact_id
|
|
248
|
+
for estimate in selected
|
|
249
|
+
if fact_id_counts[estimate.fact_id] > 1
|
|
250
|
+
}
|
|
251
|
+
ambiguous_period_starts = {
|
|
252
|
+
estimate.period_start
|
|
253
|
+
for estimate in selected
|
|
254
|
+
if period_start_counts[estimate.period_start] > 1
|
|
255
|
+
}
|
|
256
|
+
ambiguous_period_ends = {
|
|
257
|
+
estimate.period_end
|
|
258
|
+
for estimate in selected
|
|
259
|
+
if period_end_counts[estimate.period_end] > 1
|
|
260
|
+
}
|
|
261
|
+
return tuple(
|
|
262
|
+
estimate
|
|
263
|
+
for estimate in sorted(
|
|
264
|
+
estimates,
|
|
265
|
+
key=lambda candidate: (
|
|
266
|
+
candidate.period_start,
|
|
267
|
+
candidate.period_end,
|
|
268
|
+
candidate.fact_id,
|
|
269
|
+
),
|
|
270
|
+
)
|
|
271
|
+
if estimate.fact_id in ambiguous_fact_ids
|
|
272
|
+
or estimate.period_start in ambiguous_period_starts
|
|
273
|
+
or estimate.period_end in ambiguous_period_ends
|
|
274
|
+
)
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
def _has_bounded_quarterly_cadence(
|
|
278
|
+
estimates: Sequence[QuarterlyForwardAdjustedEbitdaEstimate],
|
|
279
|
+
) -> bool:
|
|
280
|
+
"""Admit conventional calendar and 52/53-week issuer quarter cadence.
|
|
281
|
+
|
|
282
|
+
The deliberately conservative 10..15-week per-period and 50..55-week
|
|
283
|
+
aggregate bounds fail closed for skipped, stub, or multi-quarter periods
|
|
284
|
+
without consulting an issuer calendar or ambient service.
|
|
285
|
+
"""
|
|
286
|
+
|
|
287
|
+
if len(estimates) != 4:
|
|
288
|
+
return False
|
|
289
|
+
inclusive_period_days = tuple(
|
|
290
|
+
(estimate.period_end - estimate.period_start).days + 1 for estimate in estimates
|
|
291
|
+
)
|
|
292
|
+
if any(
|
|
293
|
+
not _MIN_INCLUSIVE_QUARTER_DAYS <= period_days <= _MAX_INCLUSIVE_QUARTER_DAYS
|
|
294
|
+
for period_days in inclusive_period_days
|
|
295
|
+
):
|
|
296
|
+
return False
|
|
297
|
+
covered_days = (estimates[-1].period_end - estimates[0].period_start).days + 1
|
|
298
|
+
return (
|
|
299
|
+
_MIN_FOUR_QUARTER_HORIZON_DAYS <= covered_days <= _MAX_FOUR_QUARTER_HORIZON_DAYS
|
|
300
|
+
)
|
|
301
|
+
|
|
302
|
+
|
|
303
|
+
def _sum_adjusted_ebitda(
|
|
304
|
+
estimates: Sequence[QuarterlyForwardAdjustedEbitdaEstimate],
|
|
305
|
+
) -> Decimal:
|
|
306
|
+
"""Sum finite Decimal adjusted-EBITDA operands under an isolated context."""
|
|
307
|
+
|
|
308
|
+
values = tuple(estimate.adjusted_ebitda for estimate in estimates)
|
|
309
|
+
if not values:
|
|
310
|
+
return Decimal(0)
|
|
311
|
+
minimum_exponent = min(int(value.as_tuple().exponent) for value in values)
|
|
312
|
+
maximum_adjusted = max(value.adjusted() for value in values)
|
|
313
|
+
carry_digits = len(str(len(values)))
|
|
314
|
+
with localcontext() as context:
|
|
315
|
+
context.prec = max(
|
|
316
|
+
28,
|
|
317
|
+
maximum_adjusted - minimum_exponent + carry_digits + 2,
|
|
318
|
+
)
|
|
319
|
+
return sum(values, start=Decimal(0))
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
@dataclass(frozen=True, slots=True)
|
|
323
|
+
class NtmForwardEvAdjustedEbitdaAvailable:
|
|
324
|
+
"""Exact next-four-quarter EV/adjusted-EBITDA with its full operand set."""
|
|
325
|
+
|
|
326
|
+
multiple: Decimal
|
|
327
|
+
enterprise_value: Decimal
|
|
328
|
+
adjusted_ebitda: Decimal
|
|
329
|
+
close_date: date
|
|
330
|
+
last_reported_period_end: date
|
|
331
|
+
covered_period_start: date
|
|
332
|
+
covered_period_end: date
|
|
333
|
+
covered_days: int
|
|
334
|
+
quarters: tuple[QuarterlyForwardAdjustedEbitdaEstimate, ...]
|
|
335
|
+
status: Literal["available"] = field(default="available", init=False)
|
|
336
|
+
|
|
337
|
+
def __post_init__(self) -> None:
|
|
338
|
+
for field_name, value in (
|
|
339
|
+
("multiple", self.multiple),
|
|
340
|
+
("enterprise_value", self.enterprise_value),
|
|
341
|
+
("adjusted_ebitda", self.adjusted_ebitda),
|
|
342
|
+
):
|
|
343
|
+
_require_finite_decimal(value, field_name=field_name)
|
|
344
|
+
_require_date(self.close_date, field_name="close_date")
|
|
345
|
+
_require_date(
|
|
346
|
+
self.last_reported_period_end,
|
|
347
|
+
field_name="last_reported_period_end",
|
|
348
|
+
)
|
|
349
|
+
_require_date(self.covered_period_start, field_name="covered_period_start")
|
|
350
|
+
_require_date(self.covered_period_end, field_name="covered_period_end")
|
|
351
|
+
if self.last_reported_period_end > self.close_date:
|
|
352
|
+
raise ValueError("last_reported_period_end must not postdate close_date")
|
|
353
|
+
if self.enterprise_value <= 0:
|
|
354
|
+
raise ValueError("enterprise_value must be positive")
|
|
355
|
+
if self.adjusted_ebitda <= 0:
|
|
356
|
+
raise ValueError("adjusted_ebitda must be positive")
|
|
357
|
+
if self.multiple < 0:
|
|
358
|
+
raise ValueError("multiple must be non-negative")
|
|
359
|
+
if type(self.quarters) is not tuple or any(
|
|
360
|
+
not isinstance(quarter, QuarterlyForwardAdjustedEbitdaEstimate)
|
|
361
|
+
for quarter in self.quarters
|
|
362
|
+
):
|
|
363
|
+
raise TypeError(
|
|
364
|
+
"quarters must be a tuple of "
|
|
365
|
+
"QuarterlyForwardAdjustedEbitdaEstimate values"
|
|
366
|
+
)
|
|
367
|
+
if len(self.quarters) != 4:
|
|
368
|
+
raise ValueError("quarters must contain exactly four estimates")
|
|
369
|
+
if _ambiguous_quarter_estimates(self.quarters, selected=self.quarters):
|
|
370
|
+
raise ValueError(
|
|
371
|
+
"quarter fact IDs, period starts, and period ends must be unique"
|
|
372
|
+
)
|
|
373
|
+
if type(self.covered_days) is not int or self.covered_days <= 0:
|
|
374
|
+
raise ValueError("covered_days must be a positive int")
|
|
375
|
+
if self.covered_period_start != self.quarters[0].period_start:
|
|
376
|
+
raise ValueError("covered_period_start must match the first quarter")
|
|
377
|
+
if self.covered_period_end != self.quarters[-1].period_end:
|
|
378
|
+
raise ValueError("covered_period_end must match the last quarter")
|
|
379
|
+
expected_days = (self.covered_period_end - self.covered_period_start).days + 1
|
|
380
|
+
if self.covered_days != expected_days:
|
|
381
|
+
raise ValueError("covered_days must match the inclusive covered period")
|
|
382
|
+
if self.covered_period_start != self.last_reported_period_end + timedelta(
|
|
383
|
+
days=1
|
|
384
|
+
):
|
|
385
|
+
raise ValueError(
|
|
386
|
+
"covered period must begin immediately after the fiscal anchor"
|
|
387
|
+
)
|
|
388
|
+
for previous, current in zip(self.quarters, self.quarters[1:]):
|
|
389
|
+
if current.period_start != previous.period_end + timedelta(days=1):
|
|
390
|
+
raise ValueError("quarters must be contiguous and non-overlapping")
|
|
391
|
+
if not _has_bounded_quarterly_cadence(self.quarters):
|
|
392
|
+
raise ValueError("quarters must have bounded quarterly period cadence")
|
|
393
|
+
if self.adjusted_ebitda != _sum_adjusted_ebitda(self.quarters):
|
|
394
|
+
raise ValueError(
|
|
395
|
+
"adjusted_ebitda must equal the exact sum of the four quarters"
|
|
396
|
+
)
|
|
397
|
+
|
|
398
|
+
@property
|
|
399
|
+
def fact_ids(self) -> tuple[str, ...]:
|
|
400
|
+
"""Return the exact source-fact identities included in the derivation."""
|
|
401
|
+
|
|
402
|
+
return tuple(quarter.fact_id for quarter in self.quarters)
|
|
403
|
+
|
|
404
|
+
|
|
405
|
+
@dataclass(frozen=True, slots=True)
|
|
406
|
+
class NtmForwardEvAdjustedEbitdaUnavailable:
|
|
407
|
+
"""A closed reason exact next-four-quarter EV/EBITDA cannot be derived."""
|
|
408
|
+
|
|
409
|
+
reason: NtmForwardEvAdjustedEbitdaUnavailableReason
|
|
410
|
+
close_date: date | None = None
|
|
411
|
+
last_reported_period_end: date | None = None
|
|
412
|
+
enterprise_value: Decimal | None = None
|
|
413
|
+
adjusted_ebitda: Decimal | None = None
|
|
414
|
+
quarters: tuple[QuarterlyForwardAdjustedEbitdaEstimate, ...] = ()
|
|
415
|
+
status: Literal["unavailable"] = field(default="unavailable", init=False)
|
|
416
|
+
|
|
417
|
+
def __post_init__(self) -> None:
|
|
418
|
+
if self.reason not in _NTM_UNAVAILABLE_REASONS:
|
|
419
|
+
raise ValueError(
|
|
420
|
+
f"unsupported NTM EV/adjusted-EBITDA reason: {self.reason!r}"
|
|
421
|
+
)
|
|
422
|
+
if self.close_date is not None:
|
|
423
|
+
_require_date(self.close_date, field_name="close_date")
|
|
424
|
+
if self.last_reported_period_end is not None:
|
|
425
|
+
_require_date(
|
|
426
|
+
self.last_reported_period_end,
|
|
427
|
+
field_name="last_reported_period_end",
|
|
428
|
+
)
|
|
429
|
+
if self.enterprise_value is not None:
|
|
430
|
+
_require_finite_decimal(
|
|
431
|
+
self.enterprise_value,
|
|
432
|
+
field_name="enterprise_value",
|
|
433
|
+
)
|
|
434
|
+
if self.adjusted_ebitda is not None:
|
|
435
|
+
_require_finite_decimal(
|
|
436
|
+
self.adjusted_ebitda,
|
|
437
|
+
field_name="adjusted_ebitda",
|
|
438
|
+
)
|
|
439
|
+
if type(self.quarters) is not tuple or any(
|
|
440
|
+
not isinstance(quarter, QuarterlyForwardAdjustedEbitdaEstimate)
|
|
441
|
+
for quarter in self.quarters
|
|
442
|
+
):
|
|
443
|
+
raise TypeError(
|
|
444
|
+
"quarters must be a tuple of "
|
|
445
|
+
"QuarterlyForwardAdjustedEbitdaEstimate values"
|
|
446
|
+
)
|
|
447
|
+
|
|
448
|
+
@property
|
|
449
|
+
def fact_ids(self) -> tuple[str, ...]:
|
|
450
|
+
"""Return source-fact identities retained on a failed derivation."""
|
|
451
|
+
|
|
452
|
+
return tuple(quarter.fact_id for quarter in self.quarters)
|
|
453
|
+
|
|
454
|
+
|
|
455
|
+
NtmForwardEvAdjustedEbitdaResult: TypeAlias = (
|
|
456
|
+
NtmForwardEvAdjustedEbitdaAvailable | NtmForwardEvAdjustedEbitdaUnavailable
|
|
457
|
+
)
|
|
458
|
+
|
|
459
|
+
|
|
460
|
+
def derive_ntm_forward_ev_adjusted_ebitda(
|
|
461
|
+
*,
|
|
462
|
+
enterprise_value: Decimal | None,
|
|
463
|
+
close_date: date | None,
|
|
464
|
+
estimates: Sequence[QuarterlyForwardAdjustedEbitdaEstimate],
|
|
465
|
+
last_reported_period_end: date | None,
|
|
466
|
+
quantum: Decimal,
|
|
467
|
+
) -> NtmForwardEvAdjustedEbitdaResult:
|
|
468
|
+
"""Divide dated EV by the earliest four complete quarters after an anchor.
|
|
469
|
+
|
|
470
|
+
A selected quarter is never replaced to conceal a duplicate, overlap, gap,
|
|
471
|
+
or non-positive aggregate. The supplied close date is retained so an outer
|
|
472
|
+
peer policy can require one common close across independently derived
|
|
473
|
+
issuers. The estimate basis, currency, provider definition, and issuer
|
|
474
|
+
reconciliation are the calling contract's responsibility, not this
|
|
475
|
+
primitive's.
|
|
476
|
+
"""
|
|
477
|
+
|
|
478
|
+
_require_quantum(quantum)
|
|
479
|
+
if last_reported_period_end is None:
|
|
480
|
+
return NtmForwardEvAdjustedEbitdaUnavailable(reason="missing_fiscal_anchor")
|
|
481
|
+
_require_date(last_reported_period_end, field_name="last_reported_period_end")
|
|
482
|
+
if close_date is None:
|
|
483
|
+
return NtmForwardEvAdjustedEbitdaUnavailable(
|
|
484
|
+
reason="missing_close_date",
|
|
485
|
+
last_reported_period_end=last_reported_period_end,
|
|
486
|
+
)
|
|
487
|
+
_require_date(close_date, field_name="close_date")
|
|
488
|
+
if last_reported_period_end > close_date:
|
|
489
|
+
return NtmForwardEvAdjustedEbitdaUnavailable(
|
|
490
|
+
reason="fiscal_anchor_postdates_close",
|
|
491
|
+
close_date=close_date,
|
|
492
|
+
last_reported_period_end=last_reported_period_end,
|
|
493
|
+
)
|
|
494
|
+
if (
|
|
495
|
+
not isinstance(enterprise_value, Decimal)
|
|
496
|
+
or not enterprise_value.is_finite()
|
|
497
|
+
or enterprise_value <= 0
|
|
498
|
+
):
|
|
499
|
+
return NtmForwardEvAdjustedEbitdaUnavailable(
|
|
500
|
+
reason="invalid_enterprise_value",
|
|
501
|
+
close_date=close_date,
|
|
502
|
+
last_reported_period_end=last_reported_period_end,
|
|
503
|
+
)
|
|
504
|
+
|
|
505
|
+
normalized_estimates = tuple(estimates)
|
|
506
|
+
if any(
|
|
507
|
+
not isinstance(estimate, QuarterlyForwardAdjustedEbitdaEstimate)
|
|
508
|
+
for estimate in normalized_estimates
|
|
509
|
+
):
|
|
510
|
+
raise TypeError(
|
|
511
|
+
"estimates must contain QuarterlyForwardAdjustedEbitdaEstimate values"
|
|
512
|
+
)
|
|
513
|
+
|
|
514
|
+
future_estimates = tuple(
|
|
515
|
+
estimate
|
|
516
|
+
for estimate in normalized_estimates
|
|
517
|
+
if estimate.period_end > last_reported_period_end
|
|
518
|
+
)
|
|
519
|
+
estimates_by_period: dict[
|
|
520
|
+
tuple[date, date],
|
|
521
|
+
list[QuarterlyForwardAdjustedEbitdaEstimate],
|
|
522
|
+
] = {}
|
|
523
|
+
for estimate in future_estimates:
|
|
524
|
+
estimates_by_period.setdefault(
|
|
525
|
+
(estimate.period_start, estimate.period_end),
|
|
526
|
+
[],
|
|
527
|
+
).append(estimate)
|
|
528
|
+
ordered_periods = sorted(estimates_by_period)
|
|
529
|
+
selected_periods = ordered_periods[:4]
|
|
530
|
+
selected_scope = tuple(
|
|
531
|
+
estimate
|
|
532
|
+
for period in selected_periods
|
|
533
|
+
for estimate in estimates_by_period[period]
|
|
534
|
+
)
|
|
535
|
+
ambiguous_estimates = _ambiguous_quarter_estimates(
|
|
536
|
+
future_estimates,
|
|
537
|
+
selected=selected_scope,
|
|
538
|
+
)
|
|
539
|
+
if ambiguous_estimates:
|
|
540
|
+
return NtmForwardEvAdjustedEbitdaUnavailable(
|
|
541
|
+
reason="duplicate_future_period",
|
|
542
|
+
close_date=close_date,
|
|
543
|
+
last_reported_period_end=last_reported_period_end,
|
|
544
|
+
enterprise_value=enterprise_value,
|
|
545
|
+
quarters=ambiguous_estimates,
|
|
546
|
+
)
|
|
547
|
+
crossing_anchor = tuple(
|
|
548
|
+
estimate
|
|
549
|
+
for estimate in future_estimates
|
|
550
|
+
if estimate.period_start <= last_reported_period_end
|
|
551
|
+
)
|
|
552
|
+
if crossing_anchor:
|
|
553
|
+
return NtmForwardEvAdjustedEbitdaUnavailable(
|
|
554
|
+
reason="overlapping_future_periods",
|
|
555
|
+
close_date=close_date,
|
|
556
|
+
last_reported_period_end=last_reported_period_end,
|
|
557
|
+
enterprise_value=enterprise_value,
|
|
558
|
+
quarters=tuple(
|
|
559
|
+
sorted(
|
|
560
|
+
crossing_anchor,
|
|
561
|
+
key=lambda estimate: (
|
|
562
|
+
estimate.period_start,
|
|
563
|
+
estimate.period_end,
|
|
564
|
+
estimate.fact_id,
|
|
565
|
+
),
|
|
566
|
+
)
|
|
567
|
+
),
|
|
568
|
+
)
|
|
569
|
+
|
|
570
|
+
if len(selected_periods) < 4:
|
|
571
|
+
return NtmForwardEvAdjustedEbitdaUnavailable(
|
|
572
|
+
reason="insufficient_future_quarters",
|
|
573
|
+
close_date=close_date,
|
|
574
|
+
last_reported_period_end=last_reported_period_end,
|
|
575
|
+
enterprise_value=enterprise_value,
|
|
576
|
+
quarters=tuple(
|
|
577
|
+
estimates_by_period[period][0] for period in selected_periods
|
|
578
|
+
),
|
|
579
|
+
)
|
|
580
|
+
|
|
581
|
+
selected = tuple(estimates_by_period[period][0] for period in selected_periods)
|
|
582
|
+
expected_first_start = last_reported_period_end + timedelta(days=1)
|
|
583
|
+
if selected[0].period_start > expected_first_start:
|
|
584
|
+
return NtmForwardEvAdjustedEbitdaUnavailable(
|
|
585
|
+
reason="gapped_future_periods",
|
|
586
|
+
close_date=close_date,
|
|
587
|
+
last_reported_period_end=last_reported_period_end,
|
|
588
|
+
enterprise_value=enterprise_value,
|
|
589
|
+
quarters=selected,
|
|
590
|
+
)
|
|
591
|
+
if selected[0].period_start < expected_first_start:
|
|
592
|
+
return NtmForwardEvAdjustedEbitdaUnavailable(
|
|
593
|
+
reason="overlapping_future_periods",
|
|
594
|
+
close_date=close_date,
|
|
595
|
+
last_reported_period_end=last_reported_period_end,
|
|
596
|
+
enterprise_value=enterprise_value,
|
|
597
|
+
quarters=selected,
|
|
598
|
+
)
|
|
599
|
+
for previous, current in zip(selected, selected[1:]):
|
|
600
|
+
expected_start = previous.period_end + timedelta(days=1)
|
|
601
|
+
if current.period_start < expected_start:
|
|
602
|
+
return NtmForwardEvAdjustedEbitdaUnavailable(
|
|
603
|
+
reason="overlapping_future_periods",
|
|
604
|
+
close_date=close_date,
|
|
605
|
+
last_reported_period_end=last_reported_period_end,
|
|
606
|
+
enterprise_value=enterprise_value,
|
|
607
|
+
quarters=selected,
|
|
608
|
+
)
|
|
609
|
+
if current.period_start > expected_start:
|
|
610
|
+
return NtmForwardEvAdjustedEbitdaUnavailable(
|
|
611
|
+
reason="gapped_future_periods",
|
|
612
|
+
close_date=close_date,
|
|
613
|
+
last_reported_period_end=last_reported_period_end,
|
|
614
|
+
enterprise_value=enterprise_value,
|
|
615
|
+
quarters=selected,
|
|
616
|
+
)
|
|
617
|
+
|
|
618
|
+
if not _has_bounded_quarterly_cadence(selected):
|
|
619
|
+
return NtmForwardEvAdjustedEbitdaUnavailable(
|
|
620
|
+
reason="non_quarterly_period_cadence",
|
|
621
|
+
close_date=close_date,
|
|
622
|
+
last_reported_period_end=last_reported_period_end,
|
|
623
|
+
enterprise_value=enterprise_value,
|
|
624
|
+
quarters=selected,
|
|
625
|
+
)
|
|
626
|
+
|
|
627
|
+
aggregate_adjusted_ebitda = _sum_adjusted_ebitda(selected)
|
|
628
|
+
if aggregate_adjusted_ebitda <= 0:
|
|
629
|
+
return NtmForwardEvAdjustedEbitdaUnavailable(
|
|
630
|
+
reason="non_positive_aggregate_adjusted_ebitda",
|
|
631
|
+
close_date=close_date,
|
|
632
|
+
last_reported_period_end=last_reported_period_end,
|
|
633
|
+
enterprise_value=enterprise_value,
|
|
634
|
+
adjusted_ebitda=aggregate_adjusted_ebitda,
|
|
635
|
+
quarters=selected,
|
|
636
|
+
)
|
|
637
|
+
|
|
638
|
+
covered_period_start = selected[0].period_start
|
|
639
|
+
covered_period_end = selected[-1].period_end
|
|
640
|
+
return NtmForwardEvAdjustedEbitdaAvailable(
|
|
641
|
+
multiple=_derive_ev_multiple(
|
|
642
|
+
enterprise_value=enterprise_value,
|
|
643
|
+
adjusted_ebitda=aggregate_adjusted_ebitda,
|
|
644
|
+
quantum=quantum,
|
|
645
|
+
),
|
|
646
|
+
enterprise_value=enterprise_value,
|
|
647
|
+
adjusted_ebitda=aggregate_adjusted_ebitda,
|
|
648
|
+
close_date=close_date,
|
|
649
|
+
last_reported_period_end=last_reported_period_end,
|
|
650
|
+
covered_period_start=covered_period_start,
|
|
651
|
+
covered_period_end=covered_period_end,
|
|
652
|
+
covered_days=(covered_period_end - covered_period_start).days + 1,
|
|
653
|
+
quarters=selected,
|
|
654
|
+
)
|
|
655
|
+
|
|
656
|
+
|
|
657
|
+
__all__ = [
|
|
658
|
+
"ForwardEvAdjustedEbitdaAvailable",
|
|
659
|
+
"ForwardEvAdjustedEbitdaResult",
|
|
660
|
+
"ForwardEvAdjustedEbitdaUnavailable",
|
|
661
|
+
"ForwardEvAdjustedEbitdaUnavailableReason",
|
|
662
|
+
"NtmForwardEvAdjustedEbitdaAvailable",
|
|
663
|
+
"NtmForwardEvAdjustedEbitdaResult",
|
|
664
|
+
"NtmForwardEvAdjustedEbitdaUnavailable",
|
|
665
|
+
"NtmForwardEvAdjustedEbitdaUnavailableReason",
|
|
666
|
+
"QuarterlyForwardAdjustedEbitdaEstimate",
|
|
667
|
+
"derive_forward_ev_adjusted_ebitda",
|
|
668
|
+
"derive_ntm_forward_ev_adjusted_ebitda",
|
|
669
|
+
]
|