Qutebrowser Made Extensible
Total Page:16
File Type:pdf, Size:1020Kb
qutebrowser made extensible Term Project (Studienarbeit) Autumn Term 2018/2019 Department of Computer Science University of Applied Sciences Rapperswil (HSR) www.hsr.ch Author: Florian Bruhin Advisor: Prof. Stefan Keller, HSR Date: December 21, 2018 Abstract The qutebrowser project is a web browser, comparable to Google Chrome or Mozilla Firefox, which is focused on keyboard usage and having a minimal user interface. It is aimed at power- users who value customizability and efficiency, but are willing to accept a rather steep learning curve compared to “traditional” web browsers. In contrast to Chrome and Firefox, qutebrowser did not support extending its functionality via extensions. Over its lifetime, various features have been added to its core by its maintainer and contributors. However, this caused the core to grow substantially, becoming increasingly complex over time. Many users of qutebrowser have specific feature requests and workflows. It should be possible for them to extend qutebrowser in an easy way in order to keep the core small and simple. The goal of this project was to make qutebrowser extensible by introducing a clearly defined API which can be used to develop extensions. Before attempting to expose such an API from qutebrowser, various problematic areas in its codebase had to be cleaned up due to "technical debt" accumulating in the past. Subsequently, functionality suitable for moving out of the core into extensions was identified. Based on the selected areas of code, a concept for an extension API was developed. After implementing said API, large parts of qutebrowser’s functionality could be moved into extensions. The resulting changes increased code maintainability and simplicity. More information about qutebrowser can be found on its project website: https://www.qutebrowser.org/. 2 Management Summary Introduction The qutebrowser project is a web browser, comparable to Google Chrome or Mozilla Firefox, which is focused on keyboard usage and having a minimal user interface. It is aimed at power- users who value customizability and efficiency, but are willing to accept a rather steep learning curve compared to “traditional” web browsers. Since qutebrowser uses the Python programming language in conjunction with the Qt library for graphical user interfaces, it is standing on the shoulders of giants: It does not implement complex tasks such as downloading and executing HTML/CSS/JavaScript code itself. Instead, it relies on the QtWebEngine project to do so, which is largely based on the same code as Google Chrome. Work on qutebrowser started in December 2013. Since then, it has gained a big community of thousands of users and dozens of contributors. Figure 1.: Technologies used Objective In contrast to Chrome and Firefox, qutebrowser did not support extending its functionality via extensions. Over its lifetime, various features have been added to its core by its maintainer (who is the author of this report) and contributors. However, this caused the core to grow substantially, becoming more and more complex over time. 3 Many users of qutebrowser are power-users and thus have specific (and sometimes unique) feature requests and workflows. It should be possible for those users to extend qutebrowser with custom extensions in an easy way in order to keep the core small and simple. The goal of this project was to make qutebrowser extensible by introducing a clearly defined application programming interface (API) which can be used to develop extensions. Since qutebrowser already has a thriving community, this change also intends to decentralize future development efforts, as it enables users and developers to maintain their extensions independently from qutebrowser’s core. Figure 2.: qutebrowser displaying its history completion Procedure / Results In order to follow best practices in the software development world, tools for checking data types were evaluated. The mypy tool is now run regularly over the code which resulted in various lingering defects being found in qutebrowser itself and in related projects. Important parts of qutebrowser were annotated with type information in order to prevent such issues in the future, also serving as additional developer documentation. Before attempting to expose an interface for extensions from qutebrowser, various problematic areas in qutebrowser’s codebase had to be cleaned up due to “technical debt” accumulating in the past. Subsequently, functionality suitable for moving out of the core into extensions was identified. Based on the selected areas of code, a concept for an extension API was developed. After implementing said API, large parts of qutebrowser’s functionality (such as the adblocker, blocking advertisements on websites) could be moved into extensions. The resulting changes increased code maintainability and simplicity. 4 Future Work This research project was focused on increasing qutebrowser’s software quality and moving parts of its core into extensions. As a next step, additional functionality should be exposed to extensions, allowing more code to be moved out of the core. When the exposed interfaces are expected to be reasonably stable, they should then be gradually opened to interested external developers so that third-party extensions can be written. After third-party extensions gain enough traction, an “extension manager” should be developed so that users can easily install and update available extensions via a graphical user interface. 5 Contents 1. Introduction 9 1.1. Background . 9 1.2. Vision . 10 1.3. Objectives . 10 1.3.1. Merging contributions . 10 1.3.2. Refactorings . 10 1.3.3. Extension API . 11 1.3.4. Documentation . 11 1.4. Context . 12 1.4.1. Notable language features . 12 1.5. Methods and Structure . 14 1.5.1. Structure of this document . 14 1.5.2. Design decisions . 14 1.5.3. Tools used . 14 2. Project Management 15 2.1. Releases and Milestones . 15 2.2. Team and Roles . 15 2.3. Process Model . 16 2.4. Project Schedule . 16 2.5. Risks . 17 3. Requirements Specification 19 3.1. Use Cases . 19 3.2. Non-functional Requirements . 19 4. Existing APIs 20 4.1. Firefox XUL extension API . 20 4.2. WebExtensions API . 21 4.2.1. Anatomy of a WebExtension . 22 4.2.2. Analysis of the WebExtension API . 23 4.3. qutebrowser tab API . 30 4.4. Other inspirations . 32 4.4.1. pytest . 32 4.4.2. odoo . 32 5. Evaluation 33 5.1. Criteria . 33 5.2. Conclusion . 34 6. Concept 35 6.1. Summary . 35 6 6.2. Exposing existing APIs . 35 6.3. Security . 37 7. Implementation and Test 39 7.1. Type checking . 39 7.1.1. Background . 39 7.1.2. Introducing type checking . 41 7.1.3. Increasing strictness . 43 7.1.4. Adding annotations . 44 7.2. Important packages, modules and classes . 45 7.2.1. The qutebrowser.api package . 45 7.2.2. The qutebrowser.extensions package . 46 7.2.3. The qutebrowser.components package . 46 7.3. Automated Testing . 48 7.4. Manual Testing . 48 8. Results 50 8.1. Achievement of Objectives . 50 8.1.1. Merging contributions . 50 8.1.2. Refactorings . 50 8.1.3. Extension API . 51 8.1.4. Documentation . 51 8.2. Releases . 51 8.3. Risk review . 52 8.4. Time evaluation . 52 8.5. Code Statistics . 54 8.6. Demo extension . 55 8.7. Future Work . 58 8.8. Personal Review . 58 8.9. Acknowledgements . 59 A. Glossary and Abbreviations 62 B. API documentation 63 C. Task description / Aufgabenstellung 63 D. Urheber- und Nutzungsrechte 80 E. Test log 81 F. Literature and Sources 82 7 List of Figures 1. Technologies used . 3 2. qutebrowser displaying its history completion . 4 3. Project schedule . 16 4. Risk matrix . 17 5. A button added via the browserAction WebExtension API . 24 6. Class diagram for existing tab API . 30 7. Inheritance tree of tab API classes . 30 8. Sequence diagram for the extension API with adapter object . 36 9. Class diagram for refactored tab API . 37 10. Time spent per week . 52 11. Time tracking categories per week . 53 12. Command completion showing the :has-leaflet command . 55 13. Running the :has-leaflet command on OSMyBiz . 56 14. Running the :has-leaflet command on Google Maps . 56 List of Tables 2.1. Risk mitigations . 17 7.1. Modules in the qutebrowser.api package . 45 7.4. Modules in the qutebrowser.components package. 46 7.2. Important classes and functions in the qutebrowser.extensions.interceptors package 47 7.3. Important classes and functions in the qutebrowser.extensions.loader package . 47 7.5. Test coverage for added/changed modules . 49 8.1. Time tracking categories . 53 8.2. Line count for added/changed modules . 54 List of Listings 1. Existing main tab API . 31 2. Demo extension . 57 8 1. Introduction 1.1. Background The.