New API

[r0x0r]

NOTE: the original description below no longer reflects current design. Refer to the docs instead.

This is going to be the first ever breaking change, so let's make this 3.0 once it is done. This matter was discussed earlier. As this is quite a big change, I would like to get it implemented before other features to keep conflicts low.

The API would introduce a new function webview.start(callback=None, parameters=(), multiprocessing=False) that would start the UI loop and block program execution. The bare minimum hello world example would be then

import webview
window = webview.create_window("Test", "http://example.org")
webview.start()

Multiple window example would be

import webview
window1 = webview.create_window("Test 1", "http://example.org")
window2 = webview.create_window("Test 2", "http://example.org")
webview.start()

All the webview functions related to the created window will be move to the Window object returned by create_window. For example Loading HTML would be

import webview

def load_html(window):
  window.load_html("Hello world!")

window1 = webview.create_window("Test 1")
webview.start(load_html, window)

Moreover, I propose a new function signature of create_window, so that all window options would be in a separate object and localization moved out of create_window. So that

webview.create_window(title, url=None, js_api=None, options={})

webview.localization = { ... } # default localization object

Specifying window option would be like this

webview.create_window("Test", options={'resizable': False, 'fullscreen': True})

I am not sure what to do with the confirm_quit switch. Semantically it should be a global, not a window specific parameter, but I am not comfortable to moving it to webview.config.

It would not hurt to introduce webview.windows property that would contain all the opened windows.

@shivaprsdv Would you be able to give this a hand at some point?

[mikaelho]

I like it!

Would this also enable calling start() from a subthread? I would really need to reserve the main thread for other stuff.

[r0x0r]

GUI stuff must be run on the main thread. This is a requirement by every underlying GUI framework. There is no way around it.

[shivaprsd]

@shivaprsdv Would you be able to give this a hand at some point?

Certainly. We can start working on it. All your proposals are well formed. And let's keep the discussions of #181 in mind. Let us see what we can turn up with.

[r0x0r]

Glad to hear that! The roadmap would be #210 and #169 first and then I would like to start working on the new API. Maybe remove QT4 in process too.

[HeavenVolkoff]

Are you considering dropping Python 2 support with this 3.0 release? Just asking because we are nearing its EOL (https://legacy.python.org/dev/peps/pep-0373/#id2), and a lot of projects have already dropped or pledged to drop support for python 2. So, I was curious if you guys were considering the same.

[r0x0r]

I haven't given this much a thought, but supporting both Python 2 and 3 is not a big deal at the moment.

However I have been thinking whether it would be possible to change the thread model to asyncio. If this turns to be feasible, then dropping Python 2 may be worth it.

[r0x0r]

Now after spending a couple of days trying to fix Python 2 tests on Appveyor, I change my mind. Not a full deprecation, but rather stopping supporting it gradually.

[shivaprsd]

All set for pywebview-3.

Edit:

• [ ] Finsih #306.

[r0x0r]

I have second thoughts about the create_window signature. While having loads of parameters in the function signature looks ugly in the documentation, it works better in code. Introducing an options dictionary only makes things more complicated.

create_window could have an additional html=None parameter that would load HTML code instead of url. That would save from an additional load_html call. When both url and html are present, url would be ignored.

debug should be a parameter to webview.start and thus global to all the windows I think.

@HeavenVolkoff let's get your Edge PR as part of v3

[HeavenVolkoff]

@HeavenVolkoff let's get your Edge PR as part of v3

Sure. There are still a lot of polishing to be done and some features that I am having a hard time implementing (load_html). I agree that putting it off till v3 is the best decision.

[r0x0r]

I have made some progress on this, namely

• init has the new API
• Introduced Window and webview.windows property
• Cocoa implementation is done apart from bugs here and there
• Examples and tests are largely refactored to conform to the new API
• Steps are made for a new event systems. I have introduced two events: shown (window is created) and loaded (DOM is ready).
• webview.config is gone. GUI selection is done via the gui parameter of webview.start
• win32 implementation is gone
• localization and debug are now parameters to webview.start. The function has the following signature start(func=None, args=None, localization={}, multiprocessing=False, gui=None, debug=False)

This has been pushed to the pywebview-3 branch

TODO

• [x] CEF and Winforms implementations.
• [x] QT implementation
• [x] GTK implementation
• [x] On Cocoa shown event should launch on window load and not application load. I did a cursory research and it seems it should be implemented via a NSViewController. @shivaprsdv Could you take a look at this?
• [x] Observers for news events
• [x] Documentation update
• [x] _api_call should be split into two different methods for shown and loaded events

As always help and comments are welcomed

[shivaprsd]

On Cocoa shown event should launch on window load and not application load. I did a cursory research and it seems it should be implemented via a NSViewController. @shivaprsdv Could you take a look at this?

@r0x0r At the moment I am very much occupied, that is the reason I am not able to contribute anything recently. I will certainly look into it once I get some time.

[r0x0r]

I have implemented loadedand shown events, as well as the observer pattern. Also refactored the project by splitting __init__ into separate files and by moving platform specific implementations to platforms. Not sure if this is any better structure, but the time will tell.

Noticed also that webView_didFinishNavigation_ fires multiple times for URLs loaded for a second time. A quick googling did not produce a solution.

[r0x0r]

CEF and Windows are brought up to date as well. The only issue left with the API is Cocoa events I think.

[r0x0r]

Events in Cocoa are fixed as well. Tests in Travis are failing as usual, but I get no errors locally. I left multiprocessing support out of this release, as it turned out to be more complex than I thought. Other than that, refactoring is complete. I am closing this issue.