[Python] expand the APIs

[UDXS]

Currently, NumWorks Python only has a few non-mathematical APIs. Those being kandinsky and some of the built in python ones. I suggest adding a few things. A good baseline minimum for where the API should be is what TI-BASIC offers. The glaring item that is missing is the inability to take keyboard input from the user. This is limiting especially if one wants to make a game or some form of interface. Speaking of interfaces and games, I think kandinsky's feature set should be expanded to allow easy shape drawing as well as text of different sizes (and maybe colors). On top of this, a double buffering interface for smoother drawing would helo. As for interfaces, I think some form of simple interface module using escher that features simple buttons, check/radio buttons, input fields, and kandinsky drawing canvases would work well. Another helpful API would be Poincare. Being able to put an expression string and have it solved or simplified would be great for computation. Finally, a way to store data would be helpful (Like a key-value store).

I don't believe that all of these features are required, or need to be done 100%. Either way, I think one can agree that the current Python APIs are a little sparse.

Thanks!

[boricj]

There's also the Casio 90+E and its upcoming MicroPython port to consider. In a perfect world we'd share a common base API and we could have truly cross-platform calculator programs at last.

While I would not expect Casio to cooperate and coordinate with NumWorks on that subject, at least we'll be able to independently reimplement their base API once its out.

[UDXS]

That's one way to do it. We can expand on it when it's done and (hopefully) end up with a better product. I'm currently working on Lua for microcontrollers and will port it to Epsilon. I hope to provide extensive APIs.

[Ecco]

Hi @UDXS ! Thanks for the good suggestion and the extensive writeup. Here are some comments on parts of what you suggested.

Currently, NumWorks Python only has a few non-mathematical APIs. Those being kandinsky and some of the built in python ones.

That's a deliberate choice. Epsilon is a (quickly) moving target, and maintaining a stable API on top of this would be a significant burden on the development team.

double buffering interface for smoother drawing would help

It would, and that is not restricted to just Python. The problem is that the screen has quite a high resolution, so a single non-compressed frame is 320x240x2 = 153 KB.

There's also the Casio 90+E and its upcoming MicroPython port to consider. In a perfect world we'd share a common base API and we could have truly cross-platform calculator programs at last.

On our side, we're completely open to starting a working group with other graphing calculators manufacturers to come up with a shared API.

All this being said, one of the nice aspects of using Python (vs a non-standard language) is that it is actually standard and that code can be shared among platforms (not restricted to graphing calculators). Adding a custom (even if standardized) API on top of Python directly breaks cross-platform compatibility.

[boricj]

All this being said, one of the nice aspects of using Python (vs a non-standard language) is that it is actually standard and that code can be shared among platforms (not restricted to graphing calculators). Adding a custom (even if standardized) API on top of Python directly breaks cross-platform compatibility.

Purely functional code that only relies on what the bare Python language provides is effectively portable, but the kandinsky module is not standard and scripts using it (including the mandelbrot.py sample) will not work on a regular computer without some glue code. Any graphical or sufficiently advanced program is going to require modules anyway.

We don't have to reinvent the wheel from scratch either. There's plenty of nuggets of the standard Python API we could take, like time.sleep(), time.clock(), os.get_terminal_size(), statistics, turtle, tkinter.messagebox... Beyond that, the graphics.py module seems like a reasonably decent starting point for a graphics API on calculators, or we could use a dumbed-down tkinter. If we want packaged Python applications, there's zipapp and so on...

It's not what we would settle on that's very important so much as everyone settles on the same basic things. Not every calculator will have the hardware to support everything, so it's okay if a model doesn't implement everything or has proprietary APIs for specific/advanced things. But for once we have a cross-platform language in the calculator world, it would be very dumb if we can't get everyone to agree on the very basic stuff.

[boricj]

By the way, it's not just NumWorks and the Casio 90+E, there's also a Python syntax compatibility mode in giac now and Bernard Parisse expressed interest too (https://tiplanet.org/forum/viewtopic.php?t=21373&p=230363#p230354). So we're looking at least at Xcas, possibly the HP Prime too if we're optimistic.

And now for the $1.000.000 question: how do we pull this off? Aligning both NumWorks and Xcas on the same page should be easy enough given that one is on GitHub and the second is open-source. Getting Casio (and TI, on the off-chance they are working or thinking about Python) on board is another story and they (especially TI) sure are unlikely to discuss that over public channels...

[UDXS]

I think that open source is quite attractive. The idea that a company can say "We not only support the standards. We support them very well." is one that is also attractive. Now, this would apply to many tech companies but the graphing calc companies are historically terrible at catering to consumers. Now, from my somewhat intermediate french, I can see that the Casio 90+E does look good spec-wise and, from what I could find, it's targeted to the french market, somewhat like the NumWorks calculator. So, there might be some interest from Casio. I think some form of working group would work very well.

Now, I want to get something made clear. I've used MicroPython before. It's not Python. We are not going to have every module. I believe an API standard needs to be defined. This standard covers both built in python APIs and standardized graphing calculator APIs. Not each API is required to be implemented (though there will be a base minimum). Each calc API then defines capabilities. For example, we can have a drawing API. This API may not be required but it will have various capabilities. For example, it would have a colorDepth capability. There will be a single minimum module that provides info about available modules and capabilities. Code would look like this:

import gcalc
if modules.drawing:
    if modules.drawing.capabilities.colorDepth == 24
        import drawing
        drawing.start()
        drawing.circle(50,50,30,drawing.type.outline,drawing.color.red)
        drawing.end()

Something like this, but a bit less verbose would be good. Also, I would refrain implementing other Python APIs because they are generally large. Some standard modules like time (specifically time.sleep) or parts of os would be good but larger APIs like tkinter or graphics.py don't make sense. It's better to make a standardized API just for graphing calculators and maybe backport it to PC if needed. Also, I don't believe APIs should be too expansive. We need to define APIs that offer plenty of features but aren't too large or specialized for a specific calculator. It's ok if the manufacturer wants to define a more expansive and more specialized API for their calculators. We just want to provide a good cross-platform, generic version. For example, for UI, a simple system like the one I described above would be fine. If people need more complex capabilities, they can check for and use the manufacturer's own APIs.

[boricj]

Obviously we don't want to mandate nor port every last standard module for obvious reasons. I'm not advocating for a full-blown tkinter and a straight port of graphics.py, that would be ridiculous.

If we go down the "try to reuse standard APIs if possible" road, then a simplified graphics.py module for graphics (that does NOT mandate tkinter) makes sense in my opinion. If we gut everything to the bare bones then just a GraphWin placeholder object that redirects to the framebuffer with getKey(), checkKey() and plotPixel() (with plot() as an alias) would map more-or-less to what kandinsky offers yet would run on a computer. We can work our way up from this (and should, because that would be a super lame API for calculators).

Heck, we don't even need to care if it's a built-in module. The manufacturer can just as well make their own proprietary modules and preload a plaintext Python graphics.py glue script, or if the manufacturer doesn't we can supply it.

If we choose to make our own modules then the sky's the limit. I'm not fundamentally opposed to that idea, but I'd rather give the first approach a try before we break out the NIH syndrome.

[UDXS]

That sounds good but I want to make sure that there is a way to check for calculator capabilities. I also want to make sure that our APIs are clean and don't have artifacts from the regular versions. For example, I don't want to have a file access class that features directories if we don't support them. I don't think that this is reinventing the wheel. These graphing calculators are fundamentally different from full computers after all.

Another question is whether it's worth it using (or reusing) standard python APIs for things like drawing. I think we should give both approaches a good try and see whatever works best.

[adriweb]

@UDXS Hmm, don't forget that so far, the numworks only has a total memory of 4KB available for storing python scripts, so having "complex" APIs to check capabilities and all that is probably not a good ideaas it adds quite some code for something that's never going to change on a given platform.

I don't think we should really focus on having some perfectly compatible APIs (as in, expect one script to just work everywhere) - the most compatible the better of couse, but at least not having to rely on capabilities checking would be better: a script behaves well and correctly on one platform, and if needed, it has to be modified a bit (screen resolution and things like that) for another one.

Maybe some intermediary layer (at "build-time") could just enable/disable some platfom-specific code, that'd solve the issues, but then it's not really standard python anymore...

Anyway, maybe a more urgent matter would be to actually try to make a "working group" between manufacturers/developers in the first place... Looks like between Numworks (@Ecco) and HP (@parisseb) this could be done easily enough. Casio, no idea who would have to be contacted but it's worth a try, and I suppose I could ask around regarding TI if they ever plan to do something (they might as well get in the "working group" rather than just be faced with it once an API comes out). It would be quite a (good) surprise if this gets done, though :D

[UDXS]

Yeah, Ok... maybe not capabilities. My grand vision for this is that all the programming stuff is done with python standard APIs (e.g. time or random) and that everything else(e.g. drawing,UI,input...) should be done with new APIs. A calculator manufacturer only has to implement what they can and can add more if they wish. Instead of achieving 100% standardization, we can have similar APIs. This guarantees some incompatibility for more advanced APIs and ensures that scripts using more basic APIs (e.g. time, random. print, input, math) will be fully compatible.

[UDXS]

I'd like to propose adding some functions and features before something this big happens. First, I'd like to be able to configure text drawing with kandinsky with both color and size options. I'd also like to be able to take keyboard input.

[boricj]

Something like this?

• kandinsky.draw_line(x1,y1,x2,y2,color=black)
• kandinsky.draw_string(text,x,y,textColor=black,backgroundColor=white,font="large")
• kandinsky.fonts a dictionary of available fonts and their characteristics ({"large": {"width":10, "height":18}...), mostly for on-calc reference
• kandinsky.fill_rect(x1,y1,w,h,color=black)
• ion.scan_keys() returning a tuple of strings of currently pressed keys (ex: ("UP", "OK", "C"))
• time.monotonic()
• time.sleep(seconds)

The only thing that would require improvements to the firmware is time.monotonic(), because we don't currently have a timebase.

EDIT: read too much C++ lately, use correct naming convention.

[parisseb]

The current API is using _ and no uppercase, therefore it should be draw_line and could draw a polygonal line with more than 4/5 arguments (last one=color if odd number of args). No need to have drawText, just add optional args to draw_string, I already added color inside Xcas https://www-fourier.ujf-grenoble.fr/%7eparisse/xcasfr.html#exec&filename=%40session&python=1&+draw_string(%22abcd%22%2C10%2C10%2Cred)&

Le 07/05/2018 à 20:26, Jean-Baptiste Boric a écrit :

Something like this?

• |kandinsky.drawLine(x1,y1,x2,y2,color=black)|
• |kandinsky.drawText(text,x,y,textColor=black,backgroundColor=white,font="large")|
• |kandinsky.fonts| a dictionary of available fonts and their characteristics (|{"large": {"width":10, "height":18}...|), mostly for on-calc reference
• |kandinsky.fillRect(x1,y1,w,h,color=black)|
• |ion.scanKeys()| returning a tuple of strings of currently pressed keys (ex: |("UP", "OK", "C")|)
• |time.monotonic()|
• |time.sleep(seconds)|

The only thing that would require improvements to the firmware is |time.monotonic()|, because we don't currently have a timebase.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/numworks/epsilon/issues/416#issuecomment-387158097, or mute the thread https://github.com/notifications/unsubscribe-auth/ALzjfNoP-4SlxRmPOUDtMabCI-dnL4_6ks5twJHtgaJpZM4Truug.

[UDXS]

@borcj yes, that would be good. That would make "real" apps and games possible.