search

ticoneva / pystata-kernel

Jupyter kernel for Stata based on pystata
GNU General Public License v3.0
13 stars 6 forks source link

Single- vs. multi-line code cells #23

Open hugetim opened 1 year ago

hugetim commented 1 year ago

Continuing the discussion from #16:

Preface

Using nbstata for my normal work a few times has turned up a few further quirks of pystata.stata.run.

By the way, nbstata's getting pretty complicated due to my stubborn insistence on the "noecho" mode, so it's really nice that pystata_kernel also exists, as a simpler kernel that passes each code cell pretty directly to pystata.stata.run. (Actually, if I were you, I would remove the echo=None config option to better keep things simple.) That way, if something unexpected happens, the user can at least trace the issue directly back to the behavior of pystata.stata.run.

Single- vs. multi-line code cells

Single-line input (to pystata.stata.run, and thus to pystata_kernel) is processed like Stata's interactive mode, whereas multi-line code is processed via running a do-file. This has a number of implications (beyond echo) that may be surprising to the unsuspecting user of pystata_kernel unless they read the fine print in the pystata docs linked above:

  1. Inline comments (// or /* ... */) work in multi-line code but trigger an error in single-line code.
  2. #delimit ; works in a multi-line code cell (only for that one cell--and I'd now suggest keeping it that way for pystata_kernel) but placing `#delimit ;' in a single-line cell will cause an error.
  3. More than one graph command in a cell will only result in one graph being displayed unless you give the additional graphs unique names. (This is only noted in the pystata docs for the %stata magic.)

edit: Contrary to my original assertions, there are no single- vs. multi-line issues with locals or the version command (and maybe no issues not already flagged somewhere in the pystata docs). The issues I was having with those turned out to only apply to the "noecho" mode which runs multi-line code as a program. (If you maintain that mode in pystata-kernel (contrary to my recommendation above), you may want to address those issues, though, perhaps just by acknowledging them in the README, for starters.)

ticoneva commented 1 year ago

The 'noecho' mode is off by default, and stripping it out completely seems a bit excessive. Perhaps I can just add a note saying that this feature is incomplete?

hugetim commented 1 year ago

Right, definitely. Maybe "experimental" is what I should have called it all along.

Sorry, rereading my post, it sounds more demanding than I was intending. My intention is just to be helpful in an informative way. It's no big deal either way. :)