Metadata-Version: 2.4
Name: arbtt-chart
Version: 1.0.3
Summary: Plot charts from arbtt-stats to terminal
Author-email: Tomáš Janoušek <tomi@nomi.cz>
License-Expression: MIT
Project-URL: Homepage, https://github.com/liskin/arbtt-chart
Project-URL: Release Notes, https://github.com/liskin/arbtt-chart/releases
Project-URL: Issues, https://github.com/liskin/arbtt-chart/issues
Project-URL: CI, https://github.com/liskin/arbtt-chart/actions
Project-URL: Donations (GitHub), https://github.com/sponsors/liskin
Project-URL: Donations (PayPal), https://www.paypal.me/lisknisi/5EUR
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5.3
Dynamic: license-file

# arbtt-chart

[![PyPI Python Version badge](https://img.shields.io/pypi/pyversions/arbtt-chart)](https://pypi.org/project/arbtt-chart/)
[![PyPI Version badge](https://img.shields.io/pypi/v/arbtt-chart)](https://pypi.org/project/arbtt-chart/)
![License badge](https://img.shields.io/github/license/liskin/arbtt-chart)

## Overview

**Textual chart for [arbtt][], the automatic, rule-based time tracker.**

Similar to [arbtt-graph][], just in plain monospace text.

![demo](https://user-images.githubusercontent.com/300342/109856066-57afba80-7c59-11eb-8771-9612ce478945.png)

(The above screenshot is generated using my [liskin-arbtt-stats][] which
provides a few handy commands and combines data from multiple X sessions and
Strava.)

Raw `arbtt-stats` output for the same time period looks something like this:

![arbtt-stats](https://user-images.githubusercontent.com/300342/109858182-caba3080-7c5b-11eb-890e-5bb9179bbd00.png)

[arbtt]: http://arbtt.nomeata.de/
[arbtt-graph]: https://github.com/rejuvyesh/arbtt-graph
[liskin-arbtt-stats]: https://github.com/liskin/dotfiles/blob/home/bin/liskin-arbtt-stats

## Getting started

1. [Install arbtt](http://arbtt.nomeata.de/#install) and make sure
   `arbtt-capture` runs in your graphical login session.

2. Configure arbtt rules in `~/.arbtt/categorize.cfg`.
   See [Configuring the arbtt categorizer][], [Effective Use of Arbtt][], and
   [sample categorize.cfg for arbtt-graph][].

3. [Install arbtt-chart](#installation).

4. Try `arbtt-stats --output-format=csv --each-category | arbtt-chart` or
   `arbtt-stats --output-format=csv --category=Graph | arbtt-chart`

[Configuring the arbtt categorizer]: http://arbtt.nomeata.de/doc/users_guide/configuration.html
[Effective Use of Arbtt]: http://arbtt.nomeata.de/doc/users_guide/effective-use.html
[sample categorize.cfg for arbtt-graph]: https://github.com/rejuvyesh/arbtt-graph/blob/master/categorize.cfg

## Installation

Using [uv][]:

```console
$ uv tool install arbtt-chart
```

Using [pipx][]:

```console
$ pipx ensurepath
$ pipx install arbtt-chart
```

From a git clone:

```console
$ git clone https://github.com/liskin/arbtt-chart
$ uv tool install ./arbtt-chart
```

Or, since the only dependency is [pandas][], you can just `sudo apt install
python3-pandas` and run `arbtt_chart.py` directly. :-)

[uv]: https://docs.astral.sh/uv/
[pipx]: https://github.com/pypa/pipx
[pandas]: https://pandas.pydata.org/

## Usage

<!-- include tests/readme/help.md -->
<!-- common
    $ . "$TESTDIR"/common.sh
-->

    $ arbtt-chart --help
    usage: arbtt-chart [-h] [--no-stacked] [--subtags] [--totals-re RE]
    
    Plot charts from arbtt-stats to terminal. Expects `arbtt-stats --output-
    format=csv --category=…` or `arbtt-stats --output-format=csv --each-category`
    output on stdin.
    
    options:
      -h, --help      show this help message and exit
      --no-stacked    don't stack bar chart
      --subtags       recognize subtags (separated by '-') and sort them together
      --totals-re RE  totals row regexp, default: ^\(total time\)$
<!-- end include tests/readme/help.md -->

## Examples

### single category

```
$ arbtt-stats --filter='$date >= 2021-03-0220:00 && $date < 2021-03-0303:00' \
>             --min-percentage=2 --category=Activity --output-format=csv \
> | arbtt-chart
Activity                                                                        
════════                                                                        
Proj-arbttⁱ          03:11:40  ███████████▓██████████▓██████████▓██▏········÷···
Chat                 00:30:20  ···········÷··········÷··········÷··█████▊···÷···
(8 entries omitted)  00:15:40  ···········÷··········÷··········÷·······▕██▊÷···
Web-Social           00:08:20  ···········÷··········÷··········÷··········▐▓▏··
Web-otherⁱ           00:06:40  ···········÷··········÷··········÷···········÷█▍·
Web-HN               00:06:20  ···········÷··········÷··········÷···········÷·▐▊
(unmatched time)     00:01:20  ···········÷··········÷··········÷···········÷··▕
                                                                                
(total time)         04:20:20  ███████████▓██████████▓██████████▓███████████▓███
```

### single category, subtags

```
$ arbtt-stats --filter='$date >= 2021-03-0220:00 && $date < 2021-03-0303:00' \
>             --min-percentage=2 --category=Activity --output-format=csv \
> | arbtt-chart --subtags
Activity                                                                        
════════                                                                        
Proj                arbttⁱ  03:11:40  █████████▓█████████▓█████████▓█·······÷···
Chat                        00:30:20  ·········÷·········÷·········÷▕████▊··÷···
Web                 Social  00:08:20  ·········÷·········÷·········÷·····▕█▏÷···
                    otherⁱ  00:06:40  ·········÷·········÷·········÷·······█▏···
                    HN      00:06:20  ·········÷·········÷·········÷········▓▏··
(8 entries omitted)         00:15:40  ·········÷·········÷·········÷········÷██▋
(unmatched time)            00:01:20  ·········÷·········÷·········÷········÷··▕
                                                                                
(total time)                04:20:20  █████████▓█████████▓█████████▓████████▓███
```

### multiple categories

```
$ arbtt-stats --filter='$date >= 2021-03-0220:00 && $date < 2021-03-0303:00' \
>             --min-percentage=2 --each-category --output-format=csv \
> | arbtt-chart
Activity                                                                        
════════                                                                        
Proj-arbttⁱ          03:11:40  ███████████▓██████████▓██████████▓██▏········÷···
Chat                 00:30:20  ···········÷··········÷··········÷··█████▊···÷···
(8 entries omitted)  00:15:40  ···········÷··········÷··········÷·······▕██▊÷···
Web-Social           00:08:20  ···········÷··········÷··········÷··········▐▓▏··
Web-otherⁱ           00:06:40  ···········÷··········÷··········÷···········÷█▍·
Web-HN               00:06:20  ···········÷··········÷··········÷···········÷·▐▊
(unmatched time)     00:01:20  ···········÷··········÷··········÷···········÷··▕
                                                                                
(total time)         04:20:20  ███████████▓██████████▓██████████▓███████████▓███
                                                                                
Desktop                                                                         
═══════                                                                         
4_arbtt              02:21:40  ███████████▓██████████▓███▊······÷···········÷···
6_arbtt_web          00:50:20  ···········÷··········÷···▐██████▓██·········÷···
1_irc                00:34:00  ···········÷··········÷··········÷··██████▌··÷···
2_web                00:34:00  ···········÷··········÷··········÷········▐██▓███
(1 entries omitted)  00:00:20  ···········÷··········÷··········÷···········÷··▕
                                                                                
(total time)         04:20:20  ███████████▓██████████▓██████████▓███████████▓███
                                                                                
Program                                                                         
═══════                                                                         
urxvt                02:38:00  ███████████▓██████████▓██████▊···÷···········÷···
google-chrome        01:21:40  ···········÷··········÷······▐███▓██████████▉÷···
app_element_io       00:14:40  ···········÷··········÷··········÷···········▓█▉·
(3 entries omitted)  00:06:00  ···········÷··········÷··········÷···········÷·▕█
                                                                                
(total time)         04:20:20  ███████████▓██████████▓██████████▓███████████▓███
```

### custom inputs

<!-- include tests/readme/custom.md -->
<!-- common
    $ . "$TESTDIR"/common.sh
-->

    $ arbtt-chart --totals-re='^\(' <<END
    > Tag,Time
    > Act:Work,02:30:00
    > Act:Social,01:20:00
    > Act:Mail,00:20:00
    > Act:Movie,01:30:00
    > (screen),05:40:00
    > 
    > Tag,Time
    > Act:Sport,3600
    > Act:Commute,1800
    > (outside),5400
    > END
    Act                                                                             
    ═══                                                                             
    Work       02:30:00  ████████▓███████▓███▋···÷·······÷········÷·······÷·······÷·
    Movie      01:30:00  ········÷·······÷···▐███▓███████▉········÷·······÷·······÷·
    Social     01:20:00  ········÷·······÷·······÷·······▕████████▓█▊·····÷·······÷·
    Sport      01:00:00  ········÷·······÷·······÷·······÷········÷·▕█████▓██·····÷·
    Commute    00:30:00  ········÷·······÷·······÷·······÷········÷·······÷··████▏÷·
    Mail       00:20:00  ········÷·······÷·······÷·······÷········÷·······÷······█▓▊
                                                                                    
    (screen)   05:40:00  ████████▓███████▓███████▓███████▓████████▓████▊··÷·······÷·
    (outside)  01:30:00  ████████▓███▍···÷·······÷·······÷········÷·······÷·······÷·
<!-- end include tests/readme/custom.md -->

### custom inputs, multiple tables at same scale

<!-- include tests/readme/custom-multitable.md -->
<!-- common
    $ . "$TESTDIR"/common.sh
-->

    $ arbtt-chart <<END
    > Tag,Time
    > Screen:Work,02:30:00
    > Screen:Social,01:20:00
    > Screen:Mail,00:20:00
    > Screen:Movie,01:30:00
    > (total time),05:40:00
    > 
    > Tag,Time
    > Outside:Sport,3600
    > Outside:Commute,1800
    > (total time),5400
    > END
    Screen                                                                          
    ══════                                                                          
    Work          02:30:00  █████████▓█████████▓████▊····÷·········÷·········÷······
    Movie         01:30:00  ·········÷·········÷····▐████▓█████████▍·········÷······
    Social        01:20:00  ·········÷·········÷·········÷·········▐█████████▓██▊···
    Mail          00:20:00  ·········÷·········÷·········÷·········÷·········÷··▐██▉
                                                                                    
    (total time)  05:40:00  █████████▓█████████▓█████████▓█████████▓█████████▓██████
                                                                                    
    Outside                                                                         
    ═══════                                                                         
    Sport         01:00:00  █████████▓·········÷·········÷·········÷·········÷······
    Commute       00:30:00  ·········▕████▊····÷·········÷·········÷·········÷······
                                                                                    
    (total time)  01:30:00  █████████▓████▉····÷·········÷·········÷·········÷······
<!-- end include tests/readme/custom-multitable.md -->

## Contributing

### Code

We welcome bug fixes, (reasonable) new features, documentation improvements,
and more. Submit these as GitHub pull requests. Use GitHub issues to report
bugs and discuss non-trivial code improvements; alternatively, get in touch
via [IRC/Fediverse/email](https://work.lisk.in/contact/).

See [CONTRIBUTING.md](CONTRIBUTING.md) for more details about the code base
(including running tests locally).

Note that this project was born out of a desire to solve a problem I was
facing. While I'm excited to share it with the world, keep in mind that I'll
be prioritizing features and bug fixes that align with my personal use cases.
There may be times when I'm busy with other commitments and replies to
contributions might be delayed, or even occasionally missed. Progress may come
in bursts. Adjust your expectations accordingly.
