Hello grid in Python

There are two ways to work, and this page covers both. Start with the notebook widget if you live in Jupyter or VS Code. Move to the Dash track when you want the same grid inside a web app your whole team can open. The two share the same DataFrame handling, so what you learn on one carries straight over to the other.

In a notebook: prerequisites

You need Python 3.9 or newer with pip, and a notebook environment to run cells in. If you do not already have one, the install step below brings in JupyterLab for you. If you prefer VS Code, use its built-in notebook support with the same interpreter. The widget renders wherever ipywidgets do, so any of those is fine. On your own machine it runs free with no key.

pandas 1.5 or newer is what the grid reads its data from. You do not have to install it first; the next step brings it in for you.

1. Install JupyterLab and the grid widget

One command installs JupyterLab and the grid widget together. It brings in everything the widget needs to render in a notebook, including anywidget, ipywidgets, pandas and numpy, alongside the shared pandas layer both Python packages use.

pip install jupyterlab lattice-grid-jupyter

2. Start a notebook

Launch JupyterLab from the same environment you installed into, then create a new notebook, for example hello_grid.ipynb.

jupyter lab

If you work in VS Code instead, open a new .ipynb file and pick the same Python interpreter you installed the package into. Either way, you now have an empty cell to type in.

3. Render a DataFrame

Paste this into the first cell and run it. It builds a small DataFrame and hands it to LatticeGridWidget. Evaluating the widget on the last line of the cell is what draws it: a notebook shows the value of a cell's final expression, and here that value is the interactive grid.

import pandas as pd
from lattice_grid_jupyter import LatticeGridWidget

df = pd.DataFrame({"name": ["Ada", "Grace"], "score": [91, 88]})
grid = LatticeGridWidget(df)   # evaluate the widget in a cell to render it
grid                           # anywidget renders the interactive grid in the notebook

You should see a grid with two rows, Ada and Grace, and two columns, name and score. Click a column header to sort, and open a column's filter to narrow the rows. The score column arrives as a number, not text, because the grid follows your DataFrame's dtypes.

4. Edit a cell, then read it back

Double-click a score in the grid, type a new number, and commit the edit. Now read the frame back in a new cell:

grid.df   # read-only property -> the live DataFrame (reflects your edits)

grid.df is the live frame, so it already carries your edit. The value comes back cast to the column's dtype, so a number stays a number: an integer column stays an integer, not a string you would have to parse. There is no export step and no second copy to keep in step by hand.

5. Change it from Python too

The grid works both ways. As well as editing in the browser, you can drive it from code, and the grid repaints to match. Each call below is one you can run in a cell.

grid.apply_edit(key="0", col_id="score", value=100)   # returns None; row key "0" score -> 100 (int64 preserved)
grid.append_rows([{"name": "Alan", "score": 77}])      # returns ['2'] (the new row key(s))
grid.delete_rows(["2"])                                # returns the list of row keys removed
grid.set_data(pd.DataFrame({"name": ["X"], "score": [1]}))   # returns None; replaces the frame and repaints

• apply_edit(key, col_id, value) sets one cell by its row key and column, and returns nothing.
• append_rows(rows) adds rows from a list of dicts or a DataFrame, and returns the new row keys as strings.
• delete_rows(keys) removes rows by key, and returns the list of keys it removed.
• set_data(df) replaces the whole frame and repaints, and returns nothing.

Row keys are strings, starting at "0". Read the current frame at any point from grid.df.

What next

That is a working notebook grid. When you want the same grid in a web app, follow the Dash track below. For every constructor argument and method, with its signature and return, see the Python reference.

In a Dash app: prerequisites

You need Python 3.9 or newer with pip. That is all: the Dash track below runs a small app on your own machine, where the grid renders free with no key.

1. Install the component

One command again. It brings in Dash and the shared pandas layer, so you have both the app framework and the grid after this step.

pip install lattice-grid-dash

2. Write app.py

Create a file called app.py and paste this in. It puts the grid over a DataFrame, and wires a callback so that every committed edit updates the server-side frame and flows back to the grid, cast to the column's dtype.

import pandas as pd
from dash import Dash, callback, Input, Output
import lattice_grid_dash
from lattice_grid_dash import dataframe_to_data, apply_cell_edit

df = pd.DataFrame({"name": ["Ada", "Grace"], "score": [91, 88]})

app = Dash(__name__)
app.layout = lattice_grid_dash.LatticeGrid(
    id="grid",
    data=dataframe_to_data(df),
    options={"edit": True},
)

@callback(Output("grid", "data"), Input("grid", "cellChanged"), prevent_initial_call=True)
def on_edit(edit):
    global df
    df = apply_cell_edit(df, edit)     # dtype preserved
    return dataframe_to_data(df)

if __name__ == "__main__":
    app.run(debug=True)

The grid's front-end code ships inside the package, so this works offline with no build step and no request to a CDN at render time.

3. Run it and edit a cell

Start the app from the same environment you installed into:

python app.py

Open the address Dash prints, http://127.0.0.1:8050/, in your browser. Double-click a score, type a new value and commit it. That edit arrives at the cellChanged prop, which runs your callback; apply_cell_edit applies it to the DataFrame with the column's dtype preserved, and dataframe_to_data sends the updated frame back to the grid. The DataFrame on the server and the grid in the browser stay in step, typed, with one round-trip.

Troubleshooting

• An install or import fails. Check your Python is 3.9 or newer with python --version, and that you installed into the same environment you are running.
• The notebook cell runs but no grid appears, or jupyter is not found. The widget needs JupyterLab and anywidget, which pip install jupyterlab lattice-grid-jupyter pulls in. Run that command, make sure the notebook kernel is the environment you installed into, then re-run the cell so the widget is the last expression in it.
• The Dash app will not start on its port. If something already holds port 8050, stop it, or run the app on another port.

See also the Python data grid overview and the full Python reference.