Is there a viable path for improving parameter names/tips?

[villares]

Using Thonny one can get docstring information and some tips about the arguments when calling a function/method.

For size() this is brilliant (width, height; width, height, renderer; width, height, renderer, path)

But for rect() not so much (a, b, c, d...) and I know that rect modes make the positional arguments meanings vary a lot, but, is there something we could do to improve these hints?

[hx2A]

All of the variable names are from information derived from inspection of the Processing Jar file. For rect(), the a, b, c, etc is identical to what Processing has in their documentation:

https://processing.org/reference/rect_.html

I do agree that a, b, c, etc is not that helpful. It might be possible to add a variable name override to the metaprogramming code. Someone would have to dream up new names for variables though. Starting with rect(), what names would you pick?

[villares]

I think I would go for:
x, y, width, height
x, y, width, height, radius
x, y, width, height, tl_radius, tr_radius, bl_radius, br_radius

[villares]

And the doctring, I suppose it is the origin of the other info, where does it come from?
I see there is more info during the autocomplete feature, it disappears after the opening (:
Grabbed as I typed color_mod...

color_mode(mode, /) -> None
color_mode(mode, max, /) -> None
color_mode(mode, max1, max2, max3, /) -> None
color_mode(mode, max1, max2, max3, max_a, /) -> None

Changes the way py5 interprets color data.

Underlying Processing method: PApplet.colorMode

Methods
-------

You can use any of the following signatures:

 * color_mode(mode: int, /) -> None
 * color_mode(mode: int, max1: float, max2: float, max3: float, /) -> None
 * color_mode(mode: int, max1: float, max2: float, max3: float, max_a: float, /) -> None
 * color_mode(mode: int, max: float, /) -> None

Parameters
----------

max1: float
    range for the red or hue depending on the current color mode

max2: float
    range for the green or saturation depending on the current color mode

max3: float
    range for the blue or brightness depending on the current color mode

max: float
    range for all color elements

max_a: float
    range for the alpha

mode: int
    Either RGB or HSB, corresponding to Red/Green/Blue and Hue/Saturation/Brightness

Notes
-----

Changes the way py5 interprets color data. By default, the parameters for
``fill()``, ``stroke()``, ``background()``, and ``color()`` are defined by
values between 0 and 255 using the ``RGB`` color model. The ``color_mode()``
function is used to change the numerical range used for specifying colors and to
switch color systems. For example, calling ``color_mode(RGB, 1.0)`` will specify
that values are specified between 0 and 1. The limits for defining colors are
altered by setting the parameters ``max``, ``max1``, ``max2``, ``max3``, and
``max_a``.

After changing the range of values for colors with code like ``color_mode(HSB,
360, 100, 100)``, those ranges remain in use until they are explicitly changed
again. For example, after running ``color_mode(HSB, 360, 100, 100)`` and then
changing back to ``color_mode(RGB)``, the range for R will be 0 to 360 and the
range for G and B will be 0 to 100. To avoid this, be explicit about the ranges
when changing the color mode. For instance, instead of ``color_mode(RGB)``,
write ``color_mode(RGB, 255, 255, 255)``.

[villares]

And the rect info:

rect(a, b, c, d, r, /) -> None
rect(a, b, c, d, tl, tr, br, bl, /) -> None

Draws a rectangle to the screen.

Underlying Processing method: PApplet.rect

Methods
-------

You can use any of the following signatures:

 * rect(a: float, b: float, c: float, d: float, /) -> None
 * rect(a: float, b: float, c: float, d: float, r: float, /) -> None
 * rect(a: float, b: float, c: float, d: float, tl: float, tr: float, br: float, bl: float, /) -> None

Parameters
----------

a: float
    x-coordinate of the rectangle by default

b: float
    y-coordinate of the rectangle by default

bl: float
    radius for bottom-left corner

br: float
    radius for bottom-right corner

c: float
    width of the rectangle by default

d: float
    height of the rectangle by default

r: float
    radii for all four corners

tl: float
    radius for top-left corner

tr: float
    radius for top-right corner

Notes
-----

Draws a rectangle to the screen. A rectangle is a four-sided shape with every
angle at ninety degrees. By default, the first two parameters set the location
of the upper-left corner, the third sets the width, and the fourth sets the
height. The way these parameters are interpreted, however, may be changed with
the ``rect_mode()`` function.

To draw a rounded rectangle, add a fifth parameter, which is used as the radius
value for all four corners.

To use a different radius value for each corner, include eight parameters. When
using eight parameters, the latter four set the radius of the arc at each corner
separately, starting with the top-left corner and moving clockwise around the
rectangle.

[hx2A]

I see there is more info during the autocomplete feature, it disappears after the opening (: Grabbed as I typed color_mod...

In IPython or a Jupyter notebook you can display a docstring with a question mark at the end, like this:

In [2]: py5.rect?

Signature: py5.rect(*args)
Docstring:
Draws a rectangle to the screen.

Underlying Processing method: PApplet.rect

Methods
-------
...

Two question marks gets you the source code.

In the regular Python REPL you can do this:

>>> help(py5.rect)

That also works in IPython.

And the doctring, I suppose it is the origin of the other info, where does it come from?

All of the info comes from inspection of the jars and these files:

https://github.com/py5coding/py5generator/tree/main/py5_docs/Reference/api_en

The contents of those files are partially maintained by Python. The list of signatures and the list of variables will change automatically as new methods are added to Processing. I get a notification when I run the build if something changed. This was an important feature added early on to make sure py5 and Processing did not drift out of sync.

Everything besides the signatures and the list of variables is human maintained.

I believe it would be possible to add a parameter name override that sits between the data extracted from the Processing jars and the rest of the metaprogramming code. That's how I would implement an override to change a, b, c, etc to something else.

[villares]

No urgency here, I just wanted to comment that it dawned on me that, before being used for type hints, Python's function annotations were just, you know, annotations! There are some, a bit clumsy, ways of doing both at the same time, like: https://peps.python.org/pep-0593/

[hx2A]

Python's current mechanisms for type hints are quite a bit more elegant than what is in that PEP. Glad they keep working on it and iterating on ideas.

[villares]

oh, the point of that PEP is that you can combine type hints with non-type-hint annotations...

[hx2A]

Oh, I see! I took another look. Interesting, this could be used to provide guidance for how a function should be used. For example, a function with int parameter types might want the ints to be in the range 0 to 255. This Python feature provides a way of specifying this.

I've never seen this syntax out in the wild though. This might be a feature that didn't catch on.

[villares]

Yes I think it didn't catch on, but it might be still useful for us. The thing is the type-people took over annotations in a landslide... (sorry for the nasty tone, I know type hints are useful in large projects, but I think it became almost like another language).

[hx2A]

The usefulness of type hints is partly to serve the needs of IDEs like VSCode or type checkers like mypy. I do agree that some criticism is warranted for this aspect of Python.

Right now I am working hard to get the upcoming release out the door. Once that's done, we can think about what features should be prioritized for the next release. I'm thinking matplotlib stuff and addressing how to import code in Thonny that uses py5 imported mode should be most important.