Add sparkline widget.

[rodrigogiraoserrao]

Implementation of the sparkline widget.

I'd like to validate the API before writing tests and docs.

I used $success and $error for the two default colours but their interpolation doesn't look great, IMO.
The example below is pretty much the example from the sparkline renderable file.

[willmcgugan]

Agree re color. How about $accent as the peak color, and $accent 30% as the base?

Might need a little experimenting to find something that works.

[rodrigogiraoserrao]

@willmcgugan some colour experiments here:

App with experiments

from textual.app import App
from textual.widgets._sparkline import Sparkline

import statistics


class MyApp(App):
    CSS = """
    Sparkline {
        width: 100%;
        margin: 2 0;
    }
    #fst > .sparkline--max-color {
        color: $success;
    }
    #fst > .sparkline--min-color {
        color: $warning;
    }
    #snd > .sparkline--max-color {
        color: $warning;
    }
    #snd > .sparkline--min-color {
        color: $success;
    }
    #trd > .sparkline--max-color {
        color: $error;
    }
    #trd > .sparkline--min-color {
        color: $warning;
    }
    #frt > .sparkline--max-color {
        color: $warning;
    }
    #frt > .sparkline--min-color {
        color: $error;
    }
    #fft > .sparkline--max-color {
        color: $accent;
    }
    #fft > .sparkline--min-color {
        color: $accent 30%;
    }
    #sxt > .sparkline--max-color {
        color: $accent 30%;
    }
    #sxt > .sparkline--min-color {
        color: $accent;
    }
    #svt > .sparkline--max-color {
        color: $error;
    }
    #svt > .sparkline--min-color {
        color: $error 30%;
    }
    #egt > .sparkline--max-color {
        color: $error 30%;
    }
    #egt > .sparkline--min-color {
        color: $error;
    }
    #nnt > .sparkline--max-color {
        color: $success;
    }
    #nnt > .sparkline--min-color {
        color: $success 30%;
    }
    #tnt > .sparkline--max-color {
        color: $success 30%;
    }
    #tnt > .sparkline--min-color {
        color: $success;
    }
    """

    def compose(self):
        nums = [10, 2, 30, 60, 45, 20, 7, 8, 9, 10, 50, 13, 10, 6, 5, 4, 3, 7, 20]
        yield Sparkline(nums, summary_function=max, id="fst")
        yield Sparkline(nums, summary_function=max, id="snd")
        yield Sparkline(nums, summary_function=max, id="trd")
        yield Sparkline(nums, summary_function=max, id="frt")
        yield Sparkline(nums, summary_function=max, id="fft")
        yield Sparkline(nums, summary_function=max, id="sxt")
        yield Sparkline(nums, summary_function=max, id="svt")
        yield Sparkline(nums, summary_function=max, id="egt")
        yield Sparkline(nums, summary_function=max, id="nnt")
        yield Sparkline(nums, summary_function=max, id="tnt")


app = MyApp()
if __name__ == "__main__":
    app.run()

[davep]

Looks like roadmap should get a tweak in this PR too.

[davep]

Looking over this, I wonder if the documentation for the widget needs fleshing out a little? I've never personally used a sparkline for anything, ever, so perhaps my ignorance of what they are and why I'd use them comes into play here. But the examples don't really give me a sense of why I'd use this, and to some degree I'm a little confused about the how too.

I can see that I feed it data, which will be numeric, but then it's not clear to me what the summary function actually does and why I'd want to use it. Also, there's talk of "buckets" but no explanation of what a bucket it is and how it comes into play here.

I feel that perhaps this widget deserves a good, simple, "real world" example that walks someone though the how and why of using the widget. Why would I use it? What sort of data is it good for? What is a bucket? What choices make sense for the summary function and how do I evaluate those choices?

[rodrigogiraoserrao]

@willmcgugan @davep I've improved the docs but I still wasn't very verbose.
Let me know where you stand.

[davep]

@rodrigogiraoserrao The expansion to the docs makes a lot more sense to be; I feel it's a lot more clear how it works and the role the functions play. I think the only thing I'd mention from these changes is that, rather than mention a "bucket" then go on to explain what it is in a tip, I think I'd start out in the main text talking about how the data gets portioned up to fit in the widget's width.

Maybe? Perhaps?

[willmcgugan]

I don't think the term "bucket" is relevant as far as the textual dev is concerned.

All they need to know is that they can assign some data, and it will be stretched to fit the space allocated to it.

[rodrigogiraoserrao]

@willmcgugan @davep I got rid of the word "bucket".

[davep]

That last comment about the sparkline_basic.py example aside... looking good to me.