search

cosmograph-org / py_cosmograph

Binder to the cosmograph visual analytics for big graphs
Other
10 stars 0 forks source link

Call js functions from python, with a pythonic interface. #10

Open thorwhalen opened 1 year ago

thorwhalen commented 1 year ago

We're looking specifically at a call to JS that would take the raw form, in python, as:

def _raw_cosmos_call(canvas, config):
    "Raw python wrapper to JS"

The problem is that config is supposed to be a json of the configs when speaking JS, which translates, in a raw form, as expressing config as JSON string, or as a dict. We could do a bit better by doing this:

def _raw_cosmos_call(canvas, **config):
    "A bit less raw"

Here, what's nice is that the user can call this function like this:

_raw_cosmos_call(canvas, spaceSize=1234, nodeColor="#b3b3b3")

That's okay. Many packages abuse the user in such a way. And maybe we should. It would make our lives easier. But we can do better UX-wise. We can (1) actually let the user see what the valid arguments are (2) show the user what the defaults are (this doubles up as documentation too, since they can see the type of the default values (3) validate the arguments in python before we send to JS and cause errors that the pythonist won't understand (4) Provide some description of the arguments in the docs (5) add some type annotations (?)

One problem to get right here is: Where do we source the information of what these arguments, descriptions, and defaults are? Right now, they're described in the README.md, but better would be to define them in a JSON file that would source, the JS code, the README, the python etc. One source of truth. Less misalignment potential.

thorwhalen commented 1 year ago
image
Stukova commented 1 year ago

Thanks @thorwhalen !

I like the idea of parsing configuration parameters and related descriptions from the README.md table! But in the future we will move part of the README.md documentation to the documentation site. So, it would be cool to learn how to parse config parameters, description and type directly from TS code. We already have a JSDoc description for each variable there.

But this is not a primal task, let's develop this parser after we have a working python version of Cosmos with config. To do this, I manually created a JSON with all the actual config parameters. It looks like the one you generated from the table. I added types there as well.

Check my last commit https://github.com/cosmograph-org/py_cosmograph/commit/d798f1723b9cb8786d9e1b26db91d80f17c07f12. I've added some changes based on yours and make a notebook with some testing and demonstration. Also added all type of config parameters with related info and examples.

Let me know your thoughts and if you have a question on the JS side.