Skip to content

Data types

Introduction

Project Haystack defines a fixed set of data types called kinds, which are mapped to Python objects in Phable.

Map for singleton data types

Project Haystack Phable
Marker phable.Marker
NA phable.NA
Remove phable.Remove

Map for scalar atomic data types

Project Haystack Phable
Bool bool
Number phable.Number
Str str
Uri phable.Uri
Ref phable.Ref
Symbol phable.Symbol
Date datetime.date
Time datetime.time
DateTime datetime.datetime
Coord phable.Coord
XStr phable.XStr

Note: Phable's datetime.datetime must be timezone aware to represent Project Haystack's DateTime.

Map for collection data types

Project Haystack Phable
List list
Dict dict
Grid phable.Grid

Data Types in Phable Only

As a convenience, Phable defines these data types, which are not defined in Project Haystack:

  • phable.DateRange
  • phable.DateTimeRange

Marker

Marker data type defined by Project Haystack here. Marker is a singleton used to create "label" tags.

Example:

from phable.kinds import Marker

meter_equip = {"meter": Marker(), "equip": Marker()}
Source code in phable/kinds.py
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
class Marker:
    """`Marker` data type defined by Project Haystack
    [here](https://project-haystack.org/doc/docHaystack/Kinds#marker). `Marker` is a
    singleton used to create "label" tags.

    **Example:**
    ```python
    from phable.kinds import Marker

    meter_equip = {"meter": Marker(), "equip": Marker()}
    ```
    """

    __instance = None

    def __new__(cls):
        if Marker.__instance is None:
            Marker.__instance = object.__new__(cls)
        return Marker.__instance

    def __str__(self):
        return "\u2713"

NA

NA data type defined by Project Haystack here. NA is a singleton to indicate a data value that is not available. In Project Haystack it is most often used in historized data to indicate a timestamp sample is in error.

Source code in phable/kinds.py
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
class NA:
    """`NA` data type defined by Project Haystack
    [here](https://project-haystack.org/doc/docHaystack/Kinds#na). `NA` is a
    singleton to indicate a data value that is not available. In Project Haystack it is
    most often used in historized data to indicate a timestamp sample is in error.
    """

    __instance = None

    def __new__(cls):
        if NA.__instance is None:
            NA.__instance = object.__new__(cls)
        return NA.__instance

    def __str__(self):
        return "NA"

Remove

Remove data type defined by Project Haystack here. Remove is a singleton used in a dict to indicate removal of a tag.

Source code in phable/kinds.py
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
class Remove:
    """`Remove` data type defined by Project Haystack
    [here](https://project-haystack.org/doc/docHaystack/Kinds#remove). `Remove` is a
    singleton used in a `dict` to indicate removal of a tag.
    """

    __instance = None

    def __new__(cls):
        if Remove.__instance is None:
            Remove.__instance = object.__new__(cls)
        return Remove.__instance

    def __str__(self):
        return "remove"

Number dataclass

Number data type defined by Project Haystack here.

Parameters:

Name Type Description Default
val float

Floating point value.

required
unit str | None

Optional unit of measurement defined in Project Haystack's standard unit database here.

Note: Phable does not validate a defined unit at this time.

None
Source code in phable/kinds.py
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
@dataclass(frozen=True, slots=True)
class Number:
    """`Number` data type defined by Project Haystack
    [here](https://project-haystack.org/doc/docHaystack/Kinds#number).

    Parameters:
        val: Floating point value.
        unit:
            Optional unit of measurement defined in Project Haystack's standard unit
            database [here](https://project-haystack.org/doc/docHaystack/Units).

            **Note**: Phable does not validate a defined unit at this time.
    """

    val: float
    unit: str | None = None

    def __str__(self):
        if self.unit is not None:
            return f"{self.val}{self.unit}"
        else:
            return f"{self.val}"

Uri dataclass

Uri data type defined by Project Haystack here.

Example:

from phable.kinds import Uri

uri = Uri("http://project-haystack.org/")

Parameters:

Name Type Description Default
val str

Universal Resource Identifier according to RFC 3986.

required
Source code in phable/kinds.py
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
@dataclass(frozen=True, slots=True)
class Uri:
    """`Uri` data type defined by Project Haystack
    [here](https://project-haystack.org/doc/docHaystack/Kinds#uri).

    **Example:**
    ```python
    from phable.kinds import Uri

    uri = Uri("http://project-haystack.org/")
    ```

    Parameters:
        val:
            Universal Resource Identifier according to
            [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986).
    """

    val: str

    def __str__(self):
        return self.val

Ref dataclass

Ref data type defined by Project Haystack here.

Parameters:

Name Type Description Default
val str

Unique identifier for an entity.

required
dis str | None

Optional human display name.

None
Source code in phable/kinds.py
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
@dataclass(frozen=True, slots=True)
class Ref:
    """`Ref` data type defined by Project Haystack
    [here](https://project-haystack.org/doc/docHaystack/Kinds#ref).

    Parameters:
        val: Unique identifier for an entity.
        dis: Optional human display name.
    """

    val: str
    dis: str | None = None

    def __str__(self) -> str:
        if self.dis is not None:
            return self.dis
        else:
            return f"@{self.val}"

Symbol dataclass

Symbol data type defined by Project Haystack here.

Parameters:

Name Type Description Default
val str

def identifier. Consists of only ASCII letters, digits, underbar, colon, dash, period, or tilde.

required
Source code in phable/kinds.py
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
@dataclass(frozen=True, slots=True)
class Symbol:
    """`Symbol` data type defined by Project Haystack
    [here](https://project-haystack.org/doc/docHaystack/Kinds#symbol).

    Parameters:
        val:
            [def](https://project-haystack.org/doc/docHaystack/Defs) identifier.
            Consists of only ASCII letters, digits, underbar, colon, dash, period, or
            tilde.
    """

    val: str

    def __str__(self):
        return f"^{self.val}"

Coord dataclass

Coord data type defined by Project Haystack here.

Parameters:

Name Type Description Default
lat decimal.Decimal

Latitude represented in decimal degrees.

required
lng decimal.Decimal

Longitude represented in decimal degrees.

required
Source code in phable/kinds.py
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
@dataclass(frozen=True, slots=True)
class Coord:
    """`Coord` data type defined by Project Haystack
    [here](https://project-haystack.org/doc/docHaystack/Kinds#coord).

    Parameters:
        lat:
            Latitude represented in
            [decimal degrees](https://en.wikipedia.org/wiki/Decimal_degrees).
        lng:
            Longitude represented in
            [decimal degrees](https://en.wikipedia.org/wiki/Decimal_degrees).
    """

    lat: Decimal
    lng: Decimal

    def __str__(self):
        getcontext().prec = 6
        return f"C({self.lat}, {self.lng})"

XStr dataclass

XStr data type defined by Project Haystack here.

Parameters:

Name Type Description Default
type str

Type name that follows Project Haystack's tag naming rules, except it must start with an ASCII uppercase letter (A-Z).

required
val str

String encoded value.

required
Source code in phable/kinds.py
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
@dataclass(frozen=True, slots=True)
class XStr:
    """`XStr` data type defined by Project Haystack
    [here](https://project-haystack.org/doc/docHaystack/Kinds#xstr).

    Parameters:
        type:
            Type name that follows Project Haystack's
            [tag naming](https://project-haystack.org/doc/docHaystack/Kinds#names)
            rules, except it must start with an ASCII uppercase letter (A-Z).
        val: String encoded value.
    """

    type: str
    val: str

    def __str__(self):
        return f"({self.type}, {self.val})"

Grid dataclass

Grid data type defined by Project Haystack here.

Parameters:

Name Type Description Default
meta dict[str, typing.Any]

Metadata for the entire Grid.

required
cols list[dict[str, typing.Any]]

Metadata for columns within the Grid.

required
rows list[dict[str, typing.Any]]

Row data for Grid.

required
Source code in phable/kinds.py
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
@dataclass(frozen=True, slots=True)
class Grid:
    """`Grid` data type defined by Project Haystack
    [here](https://project-haystack.org/doc/docHaystack/Kinds#grid).

    Parameters:
        meta: Metadata for the entire `Grid`.
        cols: Metadata for columns within the `Grid`.
        rows: Row data for `Grid`.
    """

    meta: dict[str, Any]
    cols: list[dict[str, Any]]
    rows: list[dict[str, Any]]

    def __str__(self):
        return "Haystack Grid"

    @staticmethod
    def to_grid(
        rows: dict[str, Any] | list[dict[str, Any]],
        meta: dict[str, Any] | None = None,
    ) -> Grid:
        """Creates a `Grid` using row data and optional metadata.

        If parameters include history data, assumes the history rows are in
        chronological order to establish `hisStart` and `hisEnd` in `meta`.

        Parameters:
            rows: Row data for `Grid`.
            meta: Optional metadata for the entire `Grid`.
        """
        if isinstance(rows, dict):
            rows = [rows]

        # might be able to find a nicer way to do this
        col_names: list[str] = []
        for row in rows:
            for col_name in row.keys():
                if col_name not in col_names:
                    col_names.append(col_name)

        cols = [{"name": name} for name in col_names]

        grid_meta = {"ver": "3.0"}

        if meta is not None:
            grid_meta = grid_meta | meta

        his_start = rows[0].get("ts", None)
        his_end = rows[-1].get("ts", None)

        if his_start is not None and his_end is not None:
            grid_meta["hisStart"] = his_start
            grid_meta["hisEnd"] = his_end + timedelta(minutes=1)

        return Grid(meta=grid_meta, cols=cols, rows=rows)

    def get_df_meta(self) -> dict[str, dict[str, Any] | list[dict[str, Any]]]:
        """Gets metadata for a DataFrame describing data from a `Grid`.

        In the returned dictionary:

         - Value for `meta` key is data used in Grid's `meta` attribute.
         - Value for `cols` key is data used in Grid's `cols` attribute.

        Returns:
            Dictionary with keys `meta` and `cols`.
        """

        df_meta = {}
        df_meta["meta"] = self.meta.copy()
        df_meta["cols"] = self.cols.copy()
        return df_meta

    def to_pandas(self):
        """Converts rows in the `Grid` to a Pandas DataFrame.

        Requires Phable's optional Pandas dependency to be installed.

        For Grids with rows that do not have history data, Phable defined data types
        are passed as the `data` input to the DataFrame.

        For Grids with rows that have history data, an opinionated mashing process is
        applied to data passed to the DataFrame's `data` input:

         - Phable's `NA` objects are converted to `None`
         - Missing column values are converted to `None`
         - `Number` objects are converted to unitless `float` values

        The resultant Pandas DataFrame's data types are converted to the `pyarrow` data
        format.

        **Notes:**

         - This method is experimental and subject to change.
         - This method assumes all `Number` objects in a given column has the same unit.

        **Example:**

        ```python
        from datetime import datetime, timedelta

        from phable import Grid, Number

        ts_now = datetime.now()
        data = [
            {"ts": ts_now - timedelta(minutes=30), "val": Number(30, "kW")},
            {"ts": ts_now, "val": Number(38, "kW")},
        ]
        data = Grid.to_grid(data)
        df = data.to_pandas()
        ```
        """
        import pandas as pd

        data = _get_data_for_df(self)
        df = pd.DataFrame(data=data).convert_dtypes(dtype_backend="pyarrow")

        return df

    def to_pandas_all(self):
        """Returns a tuple:  `(Grid.get_df_meta(), Grid.to_pandas())`

        **Example:**

        ```python
        from datetime import datetime, timedelta

        from phable import Grid, Number

        ts_now = datetime.now()
        data = [
            {"ts": ts_now - timedelta(minutes=30), "val": Number(30, "kW")},
            {"ts": ts_now, "val": Number(38, "kW")},
        ]
        data = Grid.to_grid(data)
        df_meta, df = data.to_pandas_all()
        ```
        """
        return self.get_df_meta(), self.to_pandas()

    def to_polars(self):
        """Converts rows in the `Grid` to a Polars DataFrame.

        Requires Phable's optional Polars dependency to be installed.

        For Grids with rows that do not have history data, Phable defined data types
        are passed as the `data` input to the DataFrame.

        For Grids with rows that have history data, an opinionated mashing process is
        applied to data passed to the DataFrame's `data` input:

         - Phable's `NA` objects are converted to `None`
         - Missing column values are converted to `None`
         - `Number` objects are converted to unitless `float` values

        **Notes:**

         - This method is experimental and subject to change.
         - This method assumes all `Number` objects in a given column has the same unit.

        **Example:**

        ```python
        from datetime import datetime, timedelta

        from phable import Grid, Number

        ts_now = datetime.now()
        data = [
            {"ts": ts_now - timedelta(minutes=30), "val": Number(30, "kW")},
            {"ts": ts_now, "val": Number(38, "kW")},
        ]
        data = Grid.to_grid(data)
        df = data.to_polars()
        ```
        """

        import polars as pl

        data = _get_data_for_df(self)
        df = pl.DataFrame(data=data)

        return df

    def to_polars_all(self):
        """Returns a tuple:  `(Grid.get_df_meta(), Grid.to_polars())`

        **Example:**

        ```python
        from datetime import datetime, timedelta

        from phable import Grid, Number

        ts_now = datetime.now()
        data = [
            {"ts": ts_now - timedelta(minutes=30), "val": Number(30, "kW")},
            {"ts": ts_now, "val": Number(38, "kW")},
        ]
        data = Grid.to_grid(data)
        df_meta, df = data.to_polars_all()
        ```
        """
        return self.get_df_meta(), self.to_polars()

get_df_meta

get_df_meta()

Gets metadata for a DataFrame describing data from a Grid.

In the returned dictionary:

  • Value for meta key is data used in Grid's meta attribute.
  • Value for cols key is data used in Grid's cols attribute.

Returns:

Type Description
dict[str, dict[str, typing.Any] | list[dict[str, typing.Any]]]

Dictionary with keys meta and cols.

Source code in phable/kinds.py
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
def get_df_meta(self) -> dict[str, dict[str, Any] | list[dict[str, Any]]]:
    """Gets metadata for a DataFrame describing data from a `Grid`.

    In the returned dictionary:

     - Value for `meta` key is data used in Grid's `meta` attribute.
     - Value for `cols` key is data used in Grid's `cols` attribute.

    Returns:
        Dictionary with keys `meta` and `cols`.
    """

    df_meta = {}
    df_meta["meta"] = self.meta.copy()
    df_meta["cols"] = self.cols.copy()
    return df_meta

to_grid staticmethod

to_grid(rows, meta=None)

Creates a Grid using row data and optional metadata.

If parameters include history data, assumes the history rows are in chronological order to establish hisStart and hisEnd in meta.

Parameters:

Name Type Description Default
rows dict[str, typing.Any] | list[dict[str, typing.Any]]

Row data for Grid.

required
meta dict[str, typing.Any] | None

Optional metadata for the entire Grid.

None
Source code in phable/kinds.py
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
@staticmethod
def to_grid(
    rows: dict[str, Any] | list[dict[str, Any]],
    meta: dict[str, Any] | None = None,
) -> Grid:
    """Creates a `Grid` using row data and optional metadata.

    If parameters include history data, assumes the history rows are in
    chronological order to establish `hisStart` and `hisEnd` in `meta`.

    Parameters:
        rows: Row data for `Grid`.
        meta: Optional metadata for the entire `Grid`.
    """
    if isinstance(rows, dict):
        rows = [rows]

    # might be able to find a nicer way to do this
    col_names: list[str] = []
    for row in rows:
        for col_name in row.keys():
            if col_name not in col_names:
                col_names.append(col_name)

    cols = [{"name": name} for name in col_names]

    grid_meta = {"ver": "3.0"}

    if meta is not None:
        grid_meta = grid_meta | meta

    his_start = rows[0].get("ts", None)
    his_end = rows[-1].get("ts", None)

    if his_start is not None and his_end is not None:
        grid_meta["hisStart"] = his_start
        grid_meta["hisEnd"] = his_end + timedelta(minutes=1)

    return Grid(meta=grid_meta, cols=cols, rows=rows)

to_pandas

to_pandas()

Converts rows in the Grid to a Pandas DataFrame.

Requires Phable's optional Pandas dependency to be installed.

For Grids with rows that do not have history data, Phable defined data types are passed as the data input to the DataFrame.

For Grids with rows that have history data, an opinionated mashing process is applied to data passed to the DataFrame's data input:

  • Phable's NA objects are converted to None
  • Missing column values are converted to None
  • Number objects are converted to unitless float values

The resultant Pandas DataFrame's data types are converted to the pyarrow data format.

Notes:

  • This method is experimental and subject to change.
  • This method assumes all Number objects in a given column has the same unit.

Example:

from datetime import datetime, timedelta

from phable import Grid, Number

ts_now = datetime.now()
data = [
    {"ts": ts_now - timedelta(minutes=30), "val": Number(30, "kW")},
    {"ts": ts_now, "val": Number(38, "kW")},
]
data = Grid.to_grid(data)
df = data.to_pandas()
Source code in phable/kinds.py
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
def to_pandas(self):
    """Converts rows in the `Grid` to a Pandas DataFrame.

    Requires Phable's optional Pandas dependency to be installed.

    For Grids with rows that do not have history data, Phable defined data types
    are passed as the `data` input to the DataFrame.

    For Grids with rows that have history data, an opinionated mashing process is
    applied to data passed to the DataFrame's `data` input:

     - Phable's `NA` objects are converted to `None`
     - Missing column values are converted to `None`
     - `Number` objects are converted to unitless `float` values

    The resultant Pandas DataFrame's data types are converted to the `pyarrow` data
    format.

    **Notes:**

     - This method is experimental and subject to change.
     - This method assumes all `Number` objects in a given column has the same unit.

    **Example:**

    ```python
    from datetime import datetime, timedelta

    from phable import Grid, Number

    ts_now = datetime.now()
    data = [
        {"ts": ts_now - timedelta(minutes=30), "val": Number(30, "kW")},
        {"ts": ts_now, "val": Number(38, "kW")},
    ]
    data = Grid.to_grid(data)
    df = data.to_pandas()
    ```
    """
    import pandas as pd

    data = _get_data_for_df(self)
    df = pd.DataFrame(data=data).convert_dtypes(dtype_backend="pyarrow")

    return df

to_pandas_all

to_pandas_all()

Returns a tuple: (Grid.get_df_meta(), Grid.to_pandas())

Example:

from datetime import datetime, timedelta

from phable import Grid, Number

ts_now = datetime.now()
data = [
    {"ts": ts_now - timedelta(minutes=30), "val": Number(30, "kW")},
    {"ts": ts_now, "val": Number(38, "kW")},
]
data = Grid.to_grid(data)
df_meta, df = data.to_pandas_all()
Source code in phable/kinds.py
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
def to_pandas_all(self):
    """Returns a tuple:  `(Grid.get_df_meta(), Grid.to_pandas())`

    **Example:**

    ```python
    from datetime import datetime, timedelta

    from phable import Grid, Number

    ts_now = datetime.now()
    data = [
        {"ts": ts_now - timedelta(minutes=30), "val": Number(30, "kW")},
        {"ts": ts_now, "val": Number(38, "kW")},
    ]
    data = Grid.to_grid(data)
    df_meta, df = data.to_pandas_all()
    ```
    """
    return self.get_df_meta(), self.to_pandas()

to_polars

to_polars()

Converts rows in the Grid to a Polars DataFrame.

Requires Phable's optional Polars dependency to be installed.

For Grids with rows that do not have history data, Phable defined data types are passed as the data input to the DataFrame.

For Grids with rows that have history data, an opinionated mashing process is applied to data passed to the DataFrame's data input:

  • Phable's NA objects are converted to None
  • Missing column values are converted to None
  • Number objects are converted to unitless float values

Notes:

  • This method is experimental and subject to change.
  • This method assumes all Number objects in a given column has the same unit.

Example:

from datetime import datetime, timedelta

from phable import Grid, Number

ts_now = datetime.now()
data = [
    {"ts": ts_now - timedelta(minutes=30), "val": Number(30, "kW")},
    {"ts": ts_now, "val": Number(38, "kW")},
]
data = Grid.to_grid(data)
df = data.to_polars()
Source code in phable/kinds.py
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
def to_polars(self):
    """Converts rows in the `Grid` to a Polars DataFrame.

    Requires Phable's optional Polars dependency to be installed.

    For Grids with rows that do not have history data, Phable defined data types
    are passed as the `data` input to the DataFrame.

    For Grids with rows that have history data, an opinionated mashing process is
    applied to data passed to the DataFrame's `data` input:

     - Phable's `NA` objects are converted to `None`
     - Missing column values are converted to `None`
     - `Number` objects are converted to unitless `float` values

    **Notes:**

     - This method is experimental and subject to change.
     - This method assumes all `Number` objects in a given column has the same unit.

    **Example:**

    ```python
    from datetime import datetime, timedelta

    from phable import Grid, Number

    ts_now = datetime.now()
    data = [
        {"ts": ts_now - timedelta(minutes=30), "val": Number(30, "kW")},
        {"ts": ts_now, "val": Number(38, "kW")},
    ]
    data = Grid.to_grid(data)
    df = data.to_polars()
    ```
    """

    import polars as pl

    data = _get_data_for_df(self)
    df = pl.DataFrame(data=data)

    return df

to_polars_all

to_polars_all()

Returns a tuple: (Grid.get_df_meta(), Grid.to_polars())

Example:

from datetime import datetime, timedelta

from phable import Grid, Number

ts_now = datetime.now()
data = [
    {"ts": ts_now - timedelta(minutes=30), "val": Number(30, "kW")},
    {"ts": ts_now, "val": Number(38, "kW")},
]
data = Grid.to_grid(data)
df_meta, df = data.to_polars_all()
Source code in phable/kinds.py
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
def to_polars_all(self):
    """Returns a tuple:  `(Grid.get_df_meta(), Grid.to_polars())`

    **Example:**

    ```python
    from datetime import datetime, timedelta

    from phable import Grid, Number

    ts_now = datetime.now()
    data = [
        {"ts": ts_now - timedelta(minutes=30), "val": Number(30, "kW")},
        {"ts": ts_now, "val": Number(38, "kW")},
    ]
    data = Grid.to_grid(data)
    df_meta, df = data.to_polars_all()
    ```
    """
    return self.get_df_meta(), self.to_polars()

DateRange dataclass

DateRange data type, defined by Phable, describes a time range using dates.

Note: Project Haystack does not define a kind for DateRange.

Parameters:

Name Type Description Default
start datetime.date

Midnight of the start date (inclusive) for the range.

required
end datetime.date

Midnight of the end date (exclusive) for the range.

required
Source code in phable/kinds.py
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
@dataclass(frozen=True, slots=True)
class DateRange:
    """`DateRange` data type, defined by `Phable`, describes a time range using dates.

    **Note:** Project Haystack does not define a kind for `DateRange`.

    Parameters:
        start: Midnight of the start date (inclusive) for the range.
        end: Midnight of the end date (exclusive) for the range.
    """

    start: date
    end: date

    def __str__(self):
        return self.start.isoformat() + "," + self.end.isoformat()

DateTimeRange dataclass

DateTimeRange data type, defined by Phable, describes a time range using date, time, and timezone information.

Note: Project Haystack does not define a kind for DateTimeRange.

Parameters:

Name Type Description Default
start datetime.datetime

Start timestamp (inclusive) which is timezone aware.

required
end datetime.datetime | None

Optional end timestamp (exclusive) which is timezone aware. If end is undefined, then assume end to be when the last data value was recorded.

None
Source code in phable/kinds.py
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
@dataclass(frozen=True, slots=True)
class DateTimeRange:
    """`DateTimeRange` data type, defined by `Phable`, describes a time range using
    date, time, and timezone information.

    **Note:** Project Haystack does not define a kind for `DateTimeRange`.

    Parameters:
        start: Start timestamp (inclusive) which is timezone aware.
        end:
            Optional end timestamp (exclusive) which is timezone aware. If end is
            undefined, then assume end to be when the last data value was recorded.
    """

    start: datetime
    end: datetime | None = None

    def __str__(self):
        if self.end is None:
            return _to_haystack_datetime(self.start)
        else:
            return (
                _to_haystack_datetime(self.start)
                + ","
                + _to_haystack_datetime(self.end)
            )