@@ -10,9 +10,9 @@ dependency is included with the package.
1010
1111## Assign Session Dates
1212
13- ` SessionAssigner ` requires a Polars ` Datetime ` column named ` timestamp ` . Naive timestamps are
14- interpreted as UTC; timezone-aware timestamps are converted to UTC before they are matched to a
15- schedule .
13+ ` SessionAssigner ` accepts Polars ` Datetime ` instants or ` Date ` session labels in ` timestamp ` .
14+ Naive instants use UTC unless the feed declares a timezone; timezone-aware instants are matched in
15+ UTC. Ambiguous or nonexistent local times fail rather than being guessed .
1616
1717``` python
1818from datetime import datetime
@@ -55,6 +55,40 @@ fall within an open interval:
5555Set ` bar_frequency="daily" ` when timestamps are daily labels. The default, ` "auto" ` , treats a
5656series as daily when every non-null timestamp is midnight.
5757
58+ Explicit ` FeedSpec.timestamp_semantics ` overrides these heuristics: ` session_label ` preserves the
59+ civil label date, ` event_time ` matches an instant, and ` bar_close ` matches the ending bar boundary.
60+ Event intervals include the open and exclude the close; close-labeled bars exclude the open and
61+ include the close. The corresponding boundaries apply to lunch breaks and declared calendar
62+ interruptions. An explicit ` bar_label ` also selects the declared side; ` event_time ` alone does not
63+ infer a bar side. This assignment does
64+ not validate intraday grid completeness.
65+
66+ ` session_start_time ` is retained in metadata, but these schedule adapters reject a non-null override.
67+ Register and select an authoritative calendar with the required intervals instead of silently
68+ replacing a named exchange's session boundaries.
69+
70+ ``` python
71+ from ml4t.specs import FeedSpec
72+
73+ feed = FeedSpec(calendar = " 24/7" , timestamp_semantics = " event_time" , time_contract_version = 2 )
74+ assigned = SessionAssigner(feed_spec = feed).assign_sessions(bars)
75+ unchanged = SessionAssigner(calendar = None ).assign_sessions(bars)
76+ ```
77+
78+ Use the canonical ` calendar ` keyword on constructors and facade methods. Explicit selection wins
79+ over feed metadata, then NYSE applies. Explicit ` None ` returns observations unchanged, without
80+ adding a session column or reconstructing a continuous grid. ` calendar="24/7" ` remains a real
81+ schedule, including an event exactly at midnight in the new day's session. Unknown names fail.
82+ The positional calendar argument, ` calendar_name ` constructor keyword and explicit ` exchange `
83+ selector remain compatibility forms; contradictory explicit selectors raise an error. Descriptive
84+ exchange identity in feed metadata does not select a calendar.
85+
86+ Data's ` Metadata ` supports the same versioned temporal declaration. Version 1 retains legacy null
87+ inheritance; version 2 preserves omitted calendar versus explicit null through JSON, copying and
88+ shared FeedSpec projection. Use ` model_dump(mode="json") ` before a YAML writer, and ordinary
89+ ` model_dump_json() ` for JSON; do not deliberately exclude null fields when preserving a disable
90+ declaration. Declared timezone, timestamp semantics and fixed-grid fields survive these bridges.
91+
5892## Select an Exchange Calendar
5993
6094` SessionAssigner.from_exchange() ` recognizes these exchange codes:
@@ -100,8 +134,18 @@ The supported fill methods are `"forward"`, `"backward"`, and `"none"`. Forward
100134filling apply only within a session. ` zero_volume=True ` sets volume to zero for inserted rows.
101135
102136Session completion rejects duplicate or non-minute-aligned timestamps and observations outside the
103- selected schedule. Use session assignment first when you need to inspect how individual timestamps
104- map to the exchange calendar.
137+ selected schedule. Lunch breaks and declared calendar interruptions are excluded from the template;
138+ completion never inserts rows for those closures. Use session assignment first to inspect how
139+ timestamps map to the exchange calendar.
140+
141+ Completion remains a one-minute, open-labeled operation, not a general bar-grid validator. Explicit
142+ close-labeled or session-label metadata is rejected. ` calendar=None ` returns the input unchanged.
143+ Declared event-count bar types and frequencies other than one minute are also rejected.
144+ General bar-grid anchor/partial-bar policies are preserved as metadata but explicitly rejected by
145+ this native minute completer; they are not silently approximated by its legacy minute template.
146+ ` DataManager.complete_sessions(fill_gaps=False) ` performs assignment only and never expands rows,
147+ whether or not storage is configured. Feed declarations are accepted through the facade's
148+ ` feed_spec ` keyword with the same precedence as the low-level classes.
105149
106150## Use Session Dates in Validation
107151
0 commit comments