reactive.file_reader

reactive.file_reader(filepath, interval_secs=1, *, priority=1, session=MISSING)

Create a reactive file reader.

This is a decorator, meant to be applied to a no-argument function that reads data from a file on disk. Whenever the file changes (or to be precise, the file size or last modified time changes), past readers of the data are reactively invalidated. This makes it incredibly easy to write apps that automatically update all of their outputs as soon as files on disk change.

Note that file_reader works only on single files, not directories of files.

Both the filepath function and the decorated (file reading) function can read reactive values and calc objects. Any invalidations triggered by reactive dependencies will apply to the reactive file reader object immediately (not waiting for the interval_secs delay to expire).

Parameters

filepath : str | os.PathLike[str] | Callable[[], str] | Callable[[], os.PathLike[str]]

Either a string indicating the file path to be monitored, or, a no-argument function that returns such a string. The latter is useful if the file to be monitored depends on some user input, the current date/time, etc. The file path provided MUST exist, otherwise Shiny will treat it as an unhandled error and close the session. If a function is used, make sure it is high performance (or is cached, i.e. use a :class:~shiny.reactive.calc), as it will be called very frequently.

interval_secs : float = 1

The number of seconds to wait after each time the file metadata is checked. Note: depending on what other tasks are executing, the actual wait time may far exceed this value.

priority : int = 1

Reactive polling is implemented using an effect to call poll_func on a timer; use the priority argument to control the order of this Effect’s execution versus other Effects in your app. See effect for more details.

session : MISSING_TYPE | Session | None = MISSING

A Session instance. If not provided, a session is inferred via get_current_session. If there is no current session (i.e. poll is being created outside of the server function), the lifetime of this reactive poll object will not be tied to any specific session.

Returns

: Callable[[Callable[[], T]], Callable[[], T]]

A decorator that should be applied to a no-argument function that (expensively)

: reads whatever data is desired. (This function may be a regular function or a
: co-routine function.) The result of the decorator is a reactive
: func:~shiny.reactive.calc that always returns up-to-date data, and invalidates
: callers when changes are detected via polling.

See Also

Examples

#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 400

## file: app.py
import pathlib

import pandas as pd

from shiny import App, Inputs, Outputs, Session, reactive, render, ui

dir = pathlib.Path(__file__).parent

app_ui = ui.page_fluid(ui.output_table("result"), class_="p-3")


@reactive.file_reader(dir / "mtcars.csv")
def read_file():
    return pd.read_csv(dir / "mtcars.csv")


def server(input: Inputs, output: Outputs, session: Session):
    @render.table
    def result():
        return read_file()


app = App(app_ui, server)


## file: mtcars.csv
mpg,cyl,disp,hp,drat,wt,qsec,vs,am,gear,carb
21,6,160,110,3.9,2.62,16.46,0,1,4,4
21,6,160,110,3.9,2.875,17.02,0,1,4,4
22.8,4,108,93,3.85,2.32,18.61,1,1,4,1
21.4,6,258,110,3.08,3.215,19.44,1,0,3,1
18.7,8,360,175,3.15,3.44,17.02,0,0,3,2
18.1,6,225,105,2.76,3.46,20.22,1,0,3,1
14.3,8,360,245,3.21,3.57,15.84,0,0,3,4
24.4,4,146.7,62,3.69,3.19,20,1,0,4,2
22.8,4,140.8,95,3.92,3.15,22.9,1,0,4,2
19.2,6,167.6,123,3.92,3.44,18.3,1,0,4,4
17.8,6,167.6,123,3.92,3.44,18.9,1,0,4,4
16.4,8,275.8,180,3.07,4.07,17.4,0,0,3,3
17.3,8,275.8,180,3.07,3.73,17.6,0,0,3,3
15.2,8,275.8,180,3.07,3.78,18,0,0,3,3
10.4,8,472,205,2.93,5.25,17.98,0,0,3,4
10.4,8,460,215,3,5.424,17.82,0,0,3,4
14.7,8,440,230,3.23,5.345,17.42,0,0,3,4
32.4,4,78.7,66,4.08,2.2,19.47,1,1,4,1
30.4,4,75.7,52,4.93,1.615,18.52,1,1,4,2
33.9,4,71.1,65,4.22,1.835,19.9,1,1,4,1
21.5,4,120.1,97,3.7,2.465,20.01,1,0,3,1
15.5,8,318,150,2.76,3.52,16.87,0,0,3,2
15.2,8,304,150,3.15,3.435,17.3,0,0,3,2
13.3,8,350,245,3.73,3.84,15.41,0,0,3,4
19.2,8,400,175,3.08,3.845,17.05,0,0,3,2
27.3,4,79,66,4.08,1.935,18.9,1,1,4,1
26,4,120.3,91,4.43,2.14,16.7,0,1,5,2
30.4,4,95.1,113,3.77,1.513,16.9,1,1,5,2
15.8,8,351,264,4.22,3.17,14.5,0,1,5,4
19.7,6,145,175,3.62,2.77,15.5,0,1,5,6
15,8,301,335,3.54,3.57,14.6,0,1,5,8
21.4,4,121,109,4.11,2.78,18.6,1,1,4,2