|
| 1 | +# Migration guide from v31 to latest v55+ (STILL UNDER WORKS.. #293) |
| 2 | + |
| 3 | + |
| 4 | +Table of contents: |
| 5 | +* [Distribution packages](#distribution-packages) |
| 6 | +* [Handlers' callbacks and other interfaces](#handlers-callbacks-and-other-interfaces) |
| 7 | + |
| 8 | + |
| 9 | +## Distribution packages |
| 10 | + |
| 11 | +In latest CEF Python there are only two distribution packages |
| 12 | +available. The first one is a wheel package distributed through |
| 13 | +PyPI, which you can install using the pip tool (8.1+ required |
| 14 | +on Linux). The second one is a setup package available for |
| 15 | +download on the GitHub Releases pages, instructions on how to |
| 16 | +install it are provided in README.txt. |
| 17 | + |
| 18 | +On Windows many of the distribution packages such as MSI, EXE, |
| 19 | +ZIP and InnoSetup files, are no more available. It is too much |
| 20 | +hassle to support these. |
| 21 | + |
| 22 | +On Linux the debian package is not supported anymore. Since |
| 23 | +pip 8.1+ added support for manylinux1 wheel packages, you can |
| 24 | +now easily install cefpython on Linux using the pip tool. |
| 25 | +Installing cefpython on Ubuntu using pip should work out of |
| 26 | +the box, all OS dependencies on Ubuntu should be satisfied |
| 27 | +by default. However since upstream CEF has OS dependencies |
| 28 | +that might not be installed by default on other OSes like e.g. |
| 29 | +Fedora, and since debian packages allow to list these and install |
| 30 | +in an automated manner, it might be reconsidered in the future |
| 31 | +to provide debian packages again. |
| 32 | + |
| 33 | + |
| 34 | +## Handlers' callbacks and other interfaces |
| 35 | + |
| 36 | +Since v55.3 all handlers' callbacks and other interfaces such as |
| 37 | +CookieVisitor, StringVisitor and WebRequestClient, are now called |
| 38 | +using keyword arguments (Issue [#291](../../../issues/291)). |
| 39 | +This will cause many of existing code to break. This is how you |
| 40 | +should declare callbacks using the new style: |
| 41 | + |
| 42 | +``` |
| 43 | +def OnLoadStart(self, browser, **_): |
| 44 | + pass |
| 45 | +
|
| 46 | +def OnLoadStart(self, **kwargs): |
| 47 | + browser = kwargs["browser"] |
| 48 | +``` |
| 49 | + |
| 50 | +In the first declaration you see that only one argument is |
| 51 | +declared, the browser, the others unused will be in the "_" |
| 52 | +variable (the name of the variable is so that PyCharm doesn't |
| 53 | +warn about unused variable). |
| 54 | + |
| 55 | +Even if you specify and use all arguments, always add the |
| 56 | +unused kwargs (`**_`) at the end: |
| 57 | + |
| 58 | +``` |
| 59 | +def OnLoadStart(self, browser, frame, **_): |
| 60 | + pass |
| 61 | +``` |
| 62 | + |
| 63 | +This will be handy in the future, in a case when upstream CEF |
| 64 | +adds a new argument to the API, your code won't break. When |
| 65 | +an argument is removed in upstream CEF API, if it's possible |
| 66 | +CEF Python will try to keep backward compatibility by |
| 67 | +emulating behavior of the old argument. |
| 68 | + |
| 69 | +In case of OnLoadStart, when you've used "browser" and "frame" |
| 70 | +names for the arguments, your code won't break. However in |
| 71 | +many other callbacks, where you've used argument names that |
| 72 | +differed from how they were named in API docs, your code will |
| 73 | +break. Also argument names were changed from camelCase |
| 74 | +to underscores. For example the OnLoadEnd callback has renamed |
| 75 | +the `httpStatusCode` argument to `http_code`. So in this case |
| 76 | +your code will definitely break, unless you've also used |
| 77 | +"http_code" for argument name. |
| 78 | + |
| 79 | + |
| 80 | + |
| 81 | + |
0 commit comments