time_split.app.reexport#

Reexported members of the time_split_app namespace.

Warning

The application API may change without a major version bump.

See time_split_app.config for variable-based configuration options.

Module Attributes

SelectSplitParams

Type of SPLIT_SELECT_FN.

PlotFn

Type of PLOT_FN.

LinkFn

Type of LINK_FN.

Functions

load_dataset(config)

Load dataset from config.

load_dataset_configs(-> tuple[bytes, ...)

Read dataset configs from file.

select_datetime(-> ~datetime.datetime)

Prompt user to select datetime.

select_duration(label, *[, horizontal, ...])

See DurationWidget.select().

Classes

DataLoaderWidget()

Load or generate datasets that require user input.

Dataset(*, label, path, index, aggregations, ...)

A loaded preconfigured dataset.

DatasetConfig(*, label, path, index, ...)

Configuration type for datasets on disk.

DurationWidget(default_unit, *, periods)

Duration specified by unit and count.

QueryParams(*[, schedule, step, n_splits, ...])

Parameters which may be passed as arguments in the URL.

Exceptions

DuplicateIndexError(df[, head])

Error raised when unaggregated data is detected.
class DataLoaderWidget[source]#

Bases: ABC

Load or generate datasets that require user input.

abstractmethod get_title() → str[source]#

Title shown in the ⚙️ Configure data menu. Uses Markdown syntax.

abstractmethod get_description() → str[source]#

Brief description shown in the ⚙️ Configure data menu. Uses Markdown syntax.

get_prefix() → bytes | None[source]#

Return a loader prefix. Generated automatically if None.

Used to identify the loader when QueryParams.data is round-tripped.

abstractmethod load(params: bytes | None) → tuple[DataFrame, dict[str, str], bytes] | DataFrame[source]#

Load data.

Note

This method will be called many times due to the Streamlit data model.

You may want to use @streamlit.cache_data or @streamlit.cache_resource to improve performance. See https://docs.streamlit.io/develop/concepts/architecture/caching for more information.

The select_range()-method may be used to prompt the user for a date range in which to retrieve data. If any other input is needed, you may use the

Parameters:

params – Parameter preset as bytes. Handling is implementation-specific.

Returns:

A pandas.DataFrame or a tuple (data, aggregations, params), where the params: bytes may be given as the params argument to recreate the frame returned.

See QueryParams.data for more information regarding the params argument.

classmethod select_range(initial: tuple[datetime, datetime] | tuple[date, date] | None = None, *, date_only: Literal[False] = False, start_options: Collection[Literal['absolute', 'relative', 'now']] | None = None, end_options: Collection[Literal['absolute', 'relative', 'now']] | None = None) → tuple[datetime, datetime][source]#
classmethod select_range(initial: tuple[datetime, datetime] | tuple[date, date] | None = None, *, date_only: Literal[True], start_options: Collection[Literal['absolute', 'relative', 'now']] | None = None, end_options: Collection[Literal['absolute', 'relative', 'now']] | None = None) → tuple[date, date]

Support method for getting user date range input.

Parameters:

  • initial – Initial range used by the widget.

  • date_only – If True, disable the time selector and return dates. Default = based on config.

  • start_options – Start options to make available to the user. Default = all.

  • end_options – End options to make available to the user. Default = all.

Returns:

A tuple (start, end).

Raises:

TypeError – If start_options or start_options are invalid.

class Dataset(*, label: str, path: str, index: str = '__INDEX__', aggregations: dict[str, str]=<factory>, description: str = '', read_function_kwargs: dict[str, ~typing.Any]=<factory>, df: DataFrame)[source]#

Bases: DatasetConfig

A loaded preconfigured dataset.

df: DataFrame#
class DatasetConfig(*, label: str, path: str, index: str = '__INDEX__', aggregations: dict[str, str]=<factory>, description: str = '', read_function_kwargs: dict[str, ~typing.Any]=<factory>)[source]#

Bases: object

Configuration type for datasets on disk.

label: str#

Name shown in the UI (Markdown).

When using load_dataset_configs(), this will default to the section header.

path: str#

Dataset path. May be prefixed for remote paths, e.g. s3://my-bucket/my-data.csv.zip.

index: str = '__INDEX__'#

Index column. Must be datetime-like.

Use '__INDEX__' (default) if the dataset already has a suitable index.

aggregations: dict[str, str]#

Default column aggregations known to pandas, e.g. {'my-column': 'max'}. Users may override these in the UI.

description: str = ''#

A longer dataset description for the UI (Markdown). The first row will be used as a summary.

read_function_kwargs: dict[str, Any]#

Keyword arguments for the read function derived based on path, e.g. pandas.read_csv().

The path is always passed as a positional argument in the first position.

exception DuplicateIndexError(df: DataFrame, head: int = 5)[source]#

Bases: Exception

Error raised when unaggregated data is detected.

property samples: DataFrame#

Sample data with duplicated index values.

property n_duplicated: int#

Total number of duplicated index values.

property n_total: int#

Total number of rows in the original frame.

class DurationWidget(default_unit: str, *, periods: dict[str, int])[source]#

Bases: object

Duration specified by unit and count.

Parameters:

  • default_unit – Default unit; must be a key in periods.

  • periods – A dict {unit: default_periods}.

classmethod from_delta(delta: timedelta | int, date_only: bool | None = None) → Self[source]#
select(label: str, *, horizontal: bool = True, read_query_param: Literal['schedule', 'before', 'after'] | None = None) → timedelta[source]#

Prompt the user to select a duration.

Parameters:

  • label – Label to show.

  • horizontal – If True, show elements side-by-side.

  • read_query_param – Attribute of QueryParams from which to read the default.

Returns:

A timedelta.

LinkFn#

Type of LINK_FN.

alias of Callable[[…], str]

PlotFn#

Type of PLOT_FN.

alias of Callable[[…], Axes]

class QueryParams(*, schedule: str | None = None, step: int | None = None, n_splits: int | None = None, before: str | None = None, after: str | None = None, expand_limits: bool | str | None = None, filter: str | None = None, show_removed: bool | None = None, data: int | str | bytes | tuple[datetime, datetime] | None = None)[source]#

Bases: object

Parameters which may be passed as arguments in the URL.

For example http://localhost:8501/?n_splits=3&step=3&show_removed=true will give

QueryParams(step=3, n_splits=3, show_removed=True, ...)

The params are later used to set the initial values in various widgets.

schedule: str | None = None#
step: int | None = None#
n_splits: int | None = None#
before: str | None = None#
after: str | None = None#
expand_limits: bool | str | None = None#
filter: str | None = None#
show_removed: bool | None = None#
data: int | str | bytes | tuple[datetime, datetime] | None = None#

Data selection.

Built-in data loaders:

If an int or str, it is assumed to refer to a DatasetConfig.label, either by index or by the label itself. Labels are normalized using normalize_dataset().

May also be a tuple of UNIX timestamps, specified on the form <start>-<stop>, e.g. 1556668800-1557606600 for a range ('2019-05-01T00:00:00z', '2019-05-11T20:30:00z'). Tuples are converted using convert_timestamps(). Note that timestamps are coerced into 5-minute increments as naive UTC timestamps.

This is managed automatically when using the bundled functions.

Custom data loaders:

If bytes, these are assumed by the the parameters of a custom DataLoaderWidget. A prefix is prepended to the raw bytes object returned by DataLoaderWidget.load(). The prefix is used to identify loader instances.

The bytes data is round tripped (as a base 16 string prefixed by 0x) when using permalinks; serialization, deserialization and validation of the actual content is the responsibility of the implementation.

See also

The create_explorer_link() function.

classmethod normalize_dataset(data: str) → str[source]#

Normalize a dataset label.

classmethod convert_timestamps(start: int, end: int, *, utc: bool = False) → tuple[datetime, datetime][source]#

Convert a pair of UNIX timestamps into datetime instances.

Parameters:

  • start – Start of the range.

  • end – End of the range.

  • utc – If True, tz-aware UTC instances are returned.

Returns:

A tuple of two timestamps.

get_splitter_kwargs() → DatetimeIndexSplitterKwargs[source]#

Get split kwargs from query.

Returns:

A DatetimeIndexSplitterKwargs from query.

Raises:

ValueError – If DatetimeIndexSplitterKwargs cannot be constructed from the current query.

classmethod get() → Self[source]#

Get the session query parameters object.

classmethod set() → Self[source]#

Set the session query parameters object.

to_dict(prefix: str = '', filter: bool = True) → dict[str, int | bool | str][source]#

Return self as a dict with None values.

Parameters:

  • prefix – Key prefix.

  • filter – If True, remove None values.

Returns:

String representation of self.

classmethod make(**kwargs: Any) → Self[source]#

Construct a new instance keyword arguments.

SelectSplitParams#

Type of SPLIT_SELECT_FN.

See also

alias of Callable[[], DatetimeIndexSplitterKwargs]

load_dataset(config: DatasetConfig) → Dataset[source]#

Load dataset from config.

Parameters:

config – A dataset configuration object.

Returns:

A Dataset instance.

load_dataset_configs(file: str | Path, *, return_digest: Literal[True]) → tuple[bytes, list[DatasetConfig]][source]#
load_dataset_configs(file: str | Path, *, return_digest: Literal[False] = False) → list[DatasetConfig]

Read dataset configs from file.

Returns one DatasetConfig object per top-level section in file.

Parameters:

  • file – Path to a TOML file.

  • return_digest – If True, return hash digest of file.

Returns:

A tuple (hash_digest, [DatasetConfig, ...]), or just the configs if return_digest=False (default).

select_datetime(label: str, initial: datetime | date | None = None, *, header: bool = True, date_only: Literal[False] = False, disabled: bool = False) → datetime[source]#
select_datetime(label: str, initial: datetime | date | None = None, *, header: bool = True, date_only: Literal[True], disabled: bool = False) → date

Prompt user to select datetime.

Parameters:

  • label – Widget label.

  • initial – Initial date. Pass None for current time.

  • header – If True, show label in a Streamlit header.

  • date_only – If True, disable the time selector and return plain datetime.date instances.

  • disabled – If True, disable user input to the Streamlit widget.

  • horizontal – If True, show date and time side-by-side. Ignored when date_only is set.

Returns:

A datetime or date.

select_duration(label: str, *, horizontal: bool = True, delta: timedelta | int = 7, date_only: bool | None = None, read_query_param: Literal['schedule', 'before', 'after'] | None = None) → timedelta[source]#

See DurationWidget.select().