Metadata-Version: 2.1
Name: dfbrowse
Version: 0.1.1
Summary: 
Author: Peter Gaultney
Author-email: petergaultney@gmail.com
Requires-Python: >=3.8,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: numpy (>=1.0)
Requires-Dist: pandas (>=1.0)
Requires-Dist: urwid (>=2.0)
Description-Content-Type: text/markdown

# dfbrowse

Python library that provides spreadsheet-style browsing of a Pandas
dataframe within a terminal/curses environment.

It was borne out of my love for curses-style/modal interfaces, and a
frustration with how difficult it is to really navigate/browse/inspect
a large dataframe while you're operating on it within IPython.

![Image visible on GitHub](./.images/see-it.png)

## Installation

`pip install dfbrowse`

## Getting started

dfbrowse is generally intended to be used _inside_ IPython. Start by
launching IPython, then import the IPython magics:

```
import dfbrowse.ipython_main
```

If you want to jump straight into browsing, load a parquet or CSV directly:

```
%csv ~/work/project1/employees.csv emp
%pq ~/work/project2/my_data.parquet data
```

If you've already loaded a dataframe, browse it like so:
```
import pandas as pd

emp = pd.read_parquet('~/work/project2/my_data.parquet')

%show emp
```

### Inside the browser

Once inside the browser, you can navigate with arrow keys and the mouse.

Press `?` to find out about some basic browsing commands. You can
resize columns, hide them, reorder them, and even search the row
contents, with a few keystrokes.

There are many other commands that you can discover in `keybindings.py`.

There are even more commands that can be discovered by typing `/` and
then pressing TAB. These are pre-registered functions, such as
`str_match` and `query`, that perform some operation on a
dataframe. The returned dataframe will be rendered in the browser.

In theory it is possible to write and register your own dataframe
functions as well, but this is a topic for a much larger document and
I'm not sure how well it's working anyway. If you want to do complex
transforms on your dataframe, you're probably better off to drop back
into the IPython 'shell', do your work, and then jump back into the
browser with one of the options above.

### quitting and reentering

You can use `q` on your keyboard to go back to the shell/ipython session.

Re-enter the browser via `%show <df_name>`, or `%fg` to foreground the
most recent dataframe.

## bugs

There are lots. I even know about some of them. Please feel free to
report any you find on GitHub.

