beeware / beeware/toga

Clarify API surface for Source/ListSource/TreeSource/Row/Node

Open
#3,760 10 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Python
Stars
5.4k
Forks
827
Avg merge
15h 39m
Merged PRs (30d)
40

Description

### Discussed in https://github.com/beeware/toga/discussions/3759

We have a protocol definition for `Source`, API documentation for `ListSource` and `TreeSource`, and a topic guide that discusses custom data sources.

However, in all this documentation, the exact API surface for a custom `ListSource` and `TreeSource` (any, by extension, `Row` and `Node`) isn't clear.

If a user were to try and write a custom `ListSource` or `TreeSource`, it would be very difficult to do so, as the API contract for these classes isn't explicitly documented.

We should provide much clearer documentation of:
1. The API contract for `ListSource` and `TreeSource`
2. The list of notifications that a custom ListSource and TreeSource should generate to satisfy Table, Tree and DetailedList widgets.

Contributor guide

Open the contributing guide

Research direction

Start with the existing Source protocol definition, ListSource and TreeSource API documentation, and the topic guide on custom data sources. Compare these with the Table, Tree, and DetailedList widget notification requirements, then document the custom ListSource and TreeSource contracts and the notifications they must generate.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.