Improve type hints when using colour.Color

[ccprince]

When I try to use colour.Color I'm getting errors in VSCode:

OK, it's not really an error, but rather Pylance trying to save me from mistakes. The code works just fine, it's the type hinting that doesn't know about Color.

I first tried turning off that reportCallIssue check, but then it complained about the type of the parameter. Turning that check off really defeats the purpose of the type hints, all together.

So, as a proof of concept, I bashed this into py5/__init__.py:

try:
    import colour
    @overload
    def stroke(color: colour.Color, /) -> None:
        pass
except ImportError:
    colour = None

And that gets rid of the error cleanly.

Obviously, this is just a quality-of-life improvement, so I can't imagine it would be high on the list of development priorities. Should I make up a PR? My plan would be to add that new @overload definition, along with a copy of the relevant doc string, on all the methods that rely on @_convert_hex_color().

[hx2A]

Hi @ccprince ! Thank you for starting this discussion.

You bring up a good point. The type hints in py5 could include classes from the optional dependencies such as the library colour. I'll open an issue to track this.

This is also related to something @villares and I have previously discussed, in that methods like stroke() and fill() also accept color names when matplotlib is installed. For example, fill("red") or stroke("blue"). Those are not in the type hints either.

Getting this to work would be tricky. One complexity is that most of the py5 code is not written directly. It is generated by py5generator using metadata about the methods and variables. Getting these type hints added would have to be done in a way that fits in that workflow.

Your proof of concept above is part of a solution but I would need to figure out how to get py5generator to create the overloads like that for it to work for all methods. And I don't have time for that right now, as I have a show opening in a few weeks. Let's open an issue for now so I don't forget and I will revisit it later when I have more flexibility.

[hx2A]

I just opened #619 to track this. I need some time to think about this to come up with a good way to approach this problem.

[ccprince]

Yeah, I wasn't sure where where the auto-generated code picked up. Maybe I'll poke around the generator code and see if I can wrap my head around it. But, getting your show opened is obviously the correct priority. Back in my community theater days, we had a saying: "Open is Done, and Done is Art." :-)

[ccprince]

OK, I poked around a little bit in the generator, and I'll clearly need to put in more time before I can even think about adding any code to it.

So, instead, I've got a kludge. In some ways, it's kludgier than just manually hacking on the generated code, but I won't have to re-hack it after each release, or in each venv.

hack.py:

# type: ignore

import colour
import py5


def colour_stroke(c: colour.Color) -> None:
    py5.stroke(c)

That # type: ignore tells Pylance to not analyze the file. I think I could also add the file to the appropriate settings entry in VsCode.

# Before:
c = Color(hue=255, brightness=50)
py5.stroke(c)

# After:
from hack import colour_stroke

c = Color(hue=255, brightness=50)
colour_stroke(c)

This makes the sketch code a little less consistent, but it gets rid of the ugly and incorrect errors. It's a reasonable trade-off, for now.

[hx2A]

But, getting your show opened is obviously the correct priority. Back in my community theater days, we had a saying: "Open is Done, and Done is Art." :-)

I'll have to remember that. :)

OK, I poked around a little bit in the generator, and I'll clearly need to put in more time before I can even think about adding any code to it.

@ccprince , the generator stuff is much like a custom template engine, except instead of producing html pages in a website, it can produce python files. I do need to document how it works. Not documenting it makes it harder for others to figure out how it works, which makes it harder to get contributions to the library. Nevertheless, I do admire your diving in to the code and giving it it try.

That documentation is an obstacle that I need to address. There's a lot of important things that need doing though.

[hx2A]

(It made me think how cool it would be if we had some CMYK color tools we could integrate with py5, but that's another can of worms)

Perhaps this would require a custom renderer? Internally Processing uses RGB color space. A custom renderer could use something else instead.

[ccprince]

Cheers, @ccprince, so nice that you are investigating these things!

Well, don't get your hopes too high -- it's all too likely I'll see something shiny and never actually accomplish anything. :-)

[villares]

Even without a custom renderer for CMYK (which would be crazy cool) something that could constrain RGB colors into a space that maps better to CMYK would be very useful. I'm not sure something like this would be easy but some color pickers can check if a color is "out of gamut in your CMYK profile"...

[hx2A]

Hmmm, it shouldn't be that hard to do. I think you'd just need to convert a RGB color to XYZ coordinates and then CMYK. If you have negative CMYK values, then you know it is outside the CMYK color gamut.