On Monday, August 5, 2019 at 1:27:12 PM UTC-5, Edward K. Ream wrote: > This time around everything things much easier.
*Status* Recent revs in the pyzo branch put the code that used to be in pyzo_file_browser.py into the pyzo_in_leo.py plugin. The pyzo_file_browser.py now contains a *copy* of *all *the classes and functions needed to put pyzo's file browser in Leo. Except for icons, it is as functional as the code in pyzo_in_leo.py. That is, *the code must still be connected to Leo*. That will be straightforward because I can change the source code at will. It will also be straightforward to add icons. I have now fully explored both ends of the *usage spectrum*: pyzo_in_leo.py *imports* everything, while pyzo_file_browser.py *copies* everything. Both ends of the spectrum are revealing. Neither, by itself, is a total answer. *Remarks* Imo, the acceleration of progress is a reflection of my increasing expertise with pyzo's code base. Like most expertise, it's a bit difficult to describe. Suffice it to say that experience has shown me what to do, what to avoid, and why. Previously I said that copying classes pyzo_file_browser.py "got old in a hurry". That was a novice talking :-) This time around I could see the value in doing so. Let me explain... 1. *Imports**:* In some sense imports are a necessary evil. They allow code to be broken into files, and that's pretty much it. Yeah, these files define python modules, but in this case that's not important. Please, don't bother reminding me of the virtues of python modules. The plugin is an *experimental prototype*, and there are virtues to having everything in one file: *all the pyzo-centric imports disappear. *This eliminates a lot of blah, blah, blah. That leads to insight. 2. *Startup**:* In the "real" pyzo, startup and imports are intimately linked. The plugin shows that this need not be so. In fact, the onCreate function now just creates a new dock widget using Leo's *existing* code, instantiates the PyzoFileBrowser class (defined in the plugin), and calls dock.setWidget to complete the process. That's *all.* 3. *Configuration**:* The plugin defines a FileBrowserConfig class. I don't think of it as a shim, it's just a necessary part of the code. The config class makes everything explicit, and extending this class will be straightforward. That's big progress. 4. *Relationships:* This is the big one. The plugin makes absolutely clear which code is (and is not!) needed by the file browser alone. This is a crucial insight, worth far more than the the few hours it took to get it. It leads to... *Refactoring pyzo code* Earlier in this post I said, "Both ends of the usage spectrum are revealing. Neither, by itself, is a total answer." Now, a way of getting the benefits of each is starting to appear. Here's how: 1. *Remove side effects from pyzo imports:* Most (all?) pyzo modules start by importing the pyzo module itself. This has numerous side effects besides defining classes and functions. In other words, "import pyzo" does stuff, not all of which are compatible with Leo. I'll be investigating replacing these side effects with explicit *do-something* calls. *This would allow this plugin to gain access to the pyzo code without copying!* 2. Refactor various utilities into *new* modules in leo/external/pyzo. This is a companion to removing side effects, but it has other virtues. In particular, accessing pyzo's icons could be made simpler. Similarly for other utilities, such as the translate function and its helpers. *Important*: I am now giving myself expanded permission to change leo/external/pyzo. Imo, there is no other way to reconcile pyzo code with Leo. Yes, one could imagine monkey-patching pyzo's files, but the side effects of pyzo imports would make that difficult or even impossible. Instead, I'll clearly mark all changed code. *A grand strategy* This plugin suggests a relatively straightforward way towards including all and *only* the desired pyzo docks into Leo. 1. I'll refactor the code in leo/external/pyzo as discussed above. 2. There will be a separate Leo plugin for each pyzo dock. Each plugin will import pyzo code from leo/external/pyzo as needed, without worrying about side effects. The startup code (in the top-level onCreate function of each plugin) will then "make things happen" using the new do-something calls. And that's just about it. *Summary* The present pyzo_file_browser plugin contains copies of all code needed to embed pyzo's file browser in Leo. It works except for icons, which happen to be vital for clarity. It also must be connected to Leo, which will also be straightforward. This plugin has revealed *a grand strategy*, namely a refactoring of leo/external/pyzo into* side-effect free imports* and *do-something calls*. Imo, this refactoring should be relatively straightforward. This grand strategy should provide the benefits of both use-by-copy and use-by-import. If this grand strategy succeeds, it will allow each pyzo dock to be defined in a separate Leo plugin. Each such plugin will contain nothing but imports, calls to do-something functions, and a few lines of code in each plugin's onCreate top-level function. As always, nothing is assured. All aspects of this project remain experimental. However, I now have my "marching orders". Edward -- You received this message because you are subscribed to the Google Groups "leo-editor" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/leo-editor/d1ee49b0-98d9-41f1-8e27-d95e09a49f65%40googlegroups.com.
