beeware / beeware/toga

Constructor argument cleanups

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

Description

Widget constructor arguments follow a fairly consistent order:

* A single required or effectivey-required argument, if any, such as `Label(text)` and `ImageView(image)`
* `id`
* `style`
* Everything else

Currently all arguments can be passed either with positional or keyword syntax. However, using positional syntax for anything except the required argument is not very clear. So I'd like to propose that we deprecate passing all other arguments positionally.

To detect how an argument was passed, all constructors would need to have a signature of the form:
```py
(required_arg_if_any, *args, **kwargs)
```

They could then parse the `args` and `kwargs` by passing them to a helper function along with a tuple specifying the deprecated positional order. After a reasonable deprecation period, the `args` part of the signature would be removed.

The docstring of `kwargs` would change from "initial style properties" to "initial properties", thus making explicit the practice that we've long followed, that every writable property has a constructor argument.

This means the constructor signatures would no longer list all their arguments individually. But I actually think that would be an improvement, as the constructor documentation mostly duplicates the property documentation anyway. The only additional information it contains is the default values, and they can be moved to the documentation of the individual properties.

So far I've only mentioned widgets, but this pattern could apply to other classes as well.

Contributor guide

Open the contributing guide

Research direction

Start by inventorying widget and other class constructors that accept positional arguments, then review the proposed helper-based parsing and deprecation approach. Done means deprecated positional arguments are consistently handled, constructor documentation reflects initial properties, and the scope beyond widgets is resolved.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
desktop
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.