Adds the debounce decorator

[lllama]

The debounce decorator can be used to debounce calls to a method. In the below example, the decorator is used to debounce calls to on_text_input_changed in the dictionary example app, which means that unnecessary network calls are not made.

    @debounce(0.250)
    async def on_text_input_changed(self, message: TextInput.Changed) -> None:
        """A coroutine to handle a text changed message."""
        if message.value:
            # Look up the word in the background
            asyncio.create_task(self.lookup_word(message.value))
        else:
            # Clear the results
            self.query_one("#results", Static).update()

    async def lookup_word(self, word: str) -> None:
        """Looks up a word."""
        url = f"https://api.dictionaryapi.dev/api/v2/entries/en/{word}"
        async with httpx.AsyncClient() as client:
            results = (await client.get(url)).json()

        if word == self.query_one(TextInput).value:
            markdown = self.make_word_markdown(results)
            self.query_one("#results", Static).update(Markdown(markdown))

I don't know if this is the right file to put this but it seemed appropriate.

[willmcgugan]

That is a nice solution! Don't think it belongs in events. I'd be tempted to put it in textual/debounce.py

Are you up for the challenge of typing it? There's some recent extensions in typing to type decorators.

@darrenburns @davep

[lllama]

I'll give it a go. There's potentially some similar ideas that might be useful (e.g. buffer to collect events, or window that releases all events that occur within a set time).

If that sounds useful, then is there a more generic place they could live? event_decorators, or event_filters or something?

[lllama]

Update with an attempt at typing. Not sure if you prefer Optional[T] or Union[T, None] but went with Optional.

I also updated the dictionary example to use the decorator - happy to remove if that is a distraction.

[willmcgugan]

@lllama I think this is a great idea. Got some suggestions for improvements, which I will get to eventually!

Could you PR against the main branch, which is where the action is now?