qcrash Documentation Release Author

Transcription

1 qcrash Documentation Release Author October 31, 2016

2

3 Contents 1 Introduction 3 2 Changelog 5 3 Examples 7 4 API reference 13 5 Contributing 17 6 Indices and tables 19 Python Module Index 21 i

4 ii

5 A PyQt/PySide framework for reporting application crash (unhandled exception) and/or let the user report an issue/feature request. Contents: Contents 1

6 2 Contents

7 CHAPTER 1 Introduction 1.1 About A PyQt/PySide framework for reporting application crash (unhandled exception) and/or let the user report an issue/feature request. 1.2 Features multiple builtin backends for reporting bugs: github_backend: let you create issues on github _backend: let you send an with the crash report. highly configurable, you can create your own backend, set your own formatter,... a thread safe exception hook mechanism with a way to setup your own function 1.3 Screenshots Screenshots taken on KDE Plasma 5 Report dialog Review report before submitting Github integration 1.4 LICENSE QCrash is licensed under the MIT license. 1.5 Installation pip install qcrash 3

8 1.6 Usage Basic usage: import qcrash.api as qcrash # setup our own function to collect system info and application log qcrash.get_application_log = my_app.get_application_log qcrash.get_system_information = my_app.get_system_info # configure backends github = qcrash.backends.githubbackend('colinduquesnoy', 'QCrash') = qcrash.backends. backend('colin.duquesnoy@gmail.com') qcrash.install_backend([github, ]) # install exception hook qcrash.install_except_hook() # or show the report dialog manually qcrash.show_report_dialog() Some more detailed examples are available. Also have a look at the API documentation. 1.7 Dependencies keyring githubpy (embedded into the package) 1.8 Testing To run the tests, just run the following command: python setup.py test 4 Chapter 1. Introduction

9 CHAPTER 2 Changelog Improvements [All] don t limit size of application log, github backend will upload it as an anonymous gist [All] split review dialog into two tabs: General and Log [GitHub] add option to save user name only [GUI] allow to use TAB to change focus of input text area (do not insert a t anymore) [GUI] allow the user to press Ctrl+Return to accept a dialog Fixed bugs fix segfault with PyQt 5.6 on Plasma fix a few minor GUI issues (unaligned labels in gh login dialog, fix missing dialog icons, remove unused help buttons from dialogs) First public release. 5

10 6 Chapter 2. Changelog

11 CHAPTER 3 Examples 3.1 PyQt5 1 import logging 2 import sys 3 4 from PyQt5 import QtCore, QtWidgets 5 6 import qcrash.api as qcrash logging.basicconfig() 11 GITHUB_OWNER = 'ColinDuquesnoy' 12 GITHUB_REPO = 'QCrash-Test' 13 = 'your. @provider.com' def get_system_info(): 17 return 'OS: %s\npython: %r' % (sys.platform, sys.version_info) def get_application_log(): 21 return "Blabla" app = QtWidgets.QApplication(sys.argv) 25 my_settings = QtCore.QSettings() # use own qsettings to remember username,... (password stored via keyring) 29 qcrash.set_qsettings(my_settings) # configure backends 33 qcrash.install_backend(qcrash.backends.githubbackend( 34 GITHUB_OWNER, GITHUB_REPO)) 35 qcrash.install_backend(qcrash.backends. backend( , 'TestApp')) # setup our own function to collect system info and application log 39 qcrash.get_application_log = get_application_log 7

12 40 qcrash.get_system_information = get_system_info # show report dialog manually 44 qcrash.show_report_dialog() # create a window 48 win = QtWidgets.QMainWindow() 49 label = QtWidgets.QLabel() 50 label.settext('wait a few seconds for an unhandled exception to occur...') 51 label.setalignment(qtcore.qt.alignhcenter QtCore.Qt.AlignVCenter) 52 win.setcentralwidget(label) 53 win.showmaximized() # install our own except hook. 57 def except_hook(exc, tb): 58 res = QtWidgets.QMessageBox.question( 59 win, "Unhandled exception", "An unhandled exception has occured. Do " 60 "you want to report") 61 if res == QtWidgets.QMessageBox.Yes: 62 qcrash.show_report_dialog( 63 window_title='report unhandled exception', 64 issue_title=str(exc), traceback=tb) qcrash.install_except_hook(except_hook=except_hook) # raise an unhandled exception in a few seconds 70 def raise_unhandled_exception(): 71 raise Exception('this is an unhandled exception') 72 QtCore.QTimer.singleShot(2000, raise_unhandled_exception) # run qt app 75 app.exec_() 3.2 PyQt4 1 import logging 2 import sys 3 from PyQt4 import QtCore, QtGui 4 import qcrash.api as qcrash 5 6 logging.basicconfig(level=logging.debug) 7 8 GITHUB_OWNER = 'ColinDuquesnoy' 9 GITHUB_REPO = 'QCrash-Test' 10 = 'your. @provider.com' def get_system_info(): 14 return 'OS: %s\npython: %r' % (sys.platform, sys.version_info) def get_application_log(): 8 Chapter 3. Examples

13 18 return "Blabla" app = QtGui.QApplication(sys.argv) 22 my_settings = QtCore.QSettings() # use own qsettings to remember username,... (password stored via keyring) 26 qcrash.set_qsettings(my_settings) # configure backends 30 qcrash.install_backend(qcrash.backends.githubbackend( 31 GITHUB_OWNER, GITHUB_REPO)) 32 qcrash.install_backend(qcrash.backends. backend( , 'TestApp')) # setup our own function to collect system info and application log 36 qcrash.get_application_log = get_application_log 37 qcrash.get_system_information = get_system_info # show report dialog manually 41 qcrash.show_report_dialog() # create a window 45 win = QtGui.QMainWindow() 46 label = QtGui.QLabel() 47 label.settext('wait a few seconds for an unhandled exception to occur...') 48 label.setalignment(qtcore.qt.alignhcenter QtCore.Qt.AlignVCenter) 49 win.setcentralwidget(label) 50 win.showmaximized() # install our own except hook. 54 def except_hook(exc, tb): 55 res = QtGui.QMessageBox.question( 56 win, "Unhandled exception", "An unhandled exception has occured. Do " 57 "you want to report") 58 if res == QtGui.QMessageBox.Ok: 59 qcrash.show_report_dialog( 60 window_title='report unhandled exception', 61 issue_title=str(exc), traceback=tb) qcrash.install_except_hook(except_hook=except_hook) # raise an unhandled exception in a few seconds 67 def raise_unhandled_exception(): 68 raise Exception('this is an unhandled exception') 69 QtCore.QTimer.singleShot(2000, raise_unhandled_exception) # run qt app 72 app.exec_() 3.2. PyQt4 9

14 3.3 PySide 1 import logging 2 import sys 3 4 from PySide import QtCore, QtGui 5 6 import qcrash.api as qcrash logging.basicconfig() 11 GITHUB_OWNER = 'ColinDuquesnoy' 12 GITHUB_REPO = 'QCrash-Test' 13 = 'your. @provider.com' def get_system_info(): 17 return 'OS: %s\npython: %r' % (sys.platform, sys.version_info) def get_application_log(): 21 return "Blabla" app = QtGui.QApplication(sys.argv) 25 my_settings = QtCore.QSettings() # use own qsettings to remember username,... (password stored via keyring) 29 qcrash.set_qsettings(my_settings) # configure backends 33 qcrash.install_backend(qcrash.backends.githubbackend( 34 GITHUB_OWNER, GITHUB_REPO)) 35 qcrash.install_backend(qcrash.backends. backend( , 'TestApp')) # setup our own function to collect system info and application log 39 qcrash.get_application_log = get_application_log 40 qcrash.get_system_information = get_system_info # show report dialog manually 44 qcrash.show_report_dialog() # create a window 48 win = QtGui.QMainWindow() 49 label = QtGui.QLabel() 50 label.settext('wait a few seconds for an unhandled exception to occur...') 51 label.setalignment(qtcore.qt.alignhcenter QtCore.Qt.AlignVCenter) 52 win.setcentralwidget(label) 53 win.showmaximized() # install our own except hook. 10 Chapter 3. Examples

15 57 def except_hook(exc, tb): 58 res = QtGui.QMessageBox.question( 59 win, "Unhandled exception", "An unhandled exception has occured. Do " 60 "you want to report") 61 if res == QtGui.QMessageBox.Ok: 62 qcrash.show_report_dialog( 63 window_title='report unhandled exception', 64 issue_title=str(exc), traceback=tb) qcrash.install_except_hook(except_hook=except_hook) # raise an unhandled exception in a few seconds 70 def raise_unhandled_exception(): 71 raise Exception('this is an unhandled exception') 72 QtCore.QTimer.singleShot(2000, raise_unhandled_exception) # run qt app 75 app.exec_() 3.3. PySide 11

16 12 Chapter 3. Examples

17 CHAPTER 4 API reference 4.1 qcrash.api This module contains the top level API functions. qcrash.api.install_backend(*args) Install one or more backends. Usage: qcrash.install_backend(backend1) qcrash.install_backend(backend2, backend3) Parameters args the backends to install. Each backend must be a subclass of qcrash.backends.basebackend (e.g.:: qcrash.backends. backend or qcrash.backends.githubbackend) qcrash.api.get_backends() Gets the list of installed backends. qcrash.api.install_except_hook(except_hook=<function except_hook>) Install an except hook that will show the crash report dialog when an unhandled exception has occured. Parameters except_hook except_hook function that will be called on the main thread whenever an unhandled exception occured. The function takes two parameters: the exception object and the traceback string. qcrash.api.set_qsettings(qsettings) Sets the qsettings used by the backends to cache some information such as the user credentials. If no custom qsettings is defined, qcrash will use its own settings (QSettings( QCrash )) Parameters qsettings QtCore.QSettings instance qcrash.api.show_report_dialog(window_title= Report an issue..., window_icon=none, traceback=none, issue_title=, issue_description=, parent=none, modal=none, include_log=true, include_sys_info=true) Show the issue report dialog manually. Parameters window_title Title of dialog window window_icon the icon to use for the dialog window traceback optional traceback string to include in the report. 13

18 issue_title optional issue title issue_description optional issue description parent parent widget include_log Initial state of the include log check box include_sys_info Initial state of the include system info check box qcrash.api.get_application_log() Reference to the function to use to collect the application s log. Client code should redefine it. qcrash.api.get_system_information() Reference to the function to use to collect system information. Client code should redefine it. 4.2 qcrash.backends BaseBackend class qcrash.backends.basebackend(formatter, button_text, button_tooltip, button_icon=none, need_review=true) Bases: object Base class for implementing a backend. Subclass must define button_text, button_tooltip and button_icon and implement send_report(title, description). The report s title and body will be formatted automatically by the associated formatter. qsettings() Gets the qsettings instance that you can use to store various settings such as the user credentials (you should use the keyring module if you want to store user s password). send_report(title, body, application_log=none) Sends the actual bug report. Parameters title title of the report, already formatted. body body of the reporit, already formtatted. application_log Content of the application log. Default is None. Returns Whether the dialog should be closed. set_formatter(formatter) Sets the formatter associated with the backend. The formatter will automatically get called to format the report title and body before send_report is being called Backend class qcrash.backends. backend( , app_name, formatter=<qcrash.formatters. . formatter object>) Bases: qcrash.backends.base.basebackend This backend sends the crash report via (using mailto). 14 Chapter 4. API reference

19 Usage: _backend = qcrash.backends. backend( 'your_ @provider.com', 'YourAppName') qcrash.install_backend( _backend) send_report(title, body, application_log=none) GithubBackend class qcrash.backends.githubbackend(gh_owner, gh_repo, formatter=<qcrash.formatters.markdown.mardownformatter object>) Bases: qcrash.backends.base.basebackend This backend sends the crash report on a github issue tracker: Usage: github_backend = qcrash.backends.githubbackend( 'ColinDuquesnoy', 'QCrash') qcrash.install_backend(github_backend) get_user_credentials() send_report(title, body, application_log=none) upload_log_file(log_content) 4.3 qcrash.formatters BaseFormatter class qcrash.formatters.base.baseformatter Bases: object Base class for implementing a custom formatter. Just implement format_body() and format_title() functions and set your formatter on the backends you created. format_body(description, sys_info=none, traceback=none) Not implemented. Parameters description Description of the issue, written by the user. sys_info Optional system information string traceback Optional traceback. format_title(title) Formats the issue title. By default this method does nothing. An formatter might want to append the application to name to the object field qcrash.formatters 15

20 Formatter class qcrash.formatters. . formatter(app_name=none) Bases: qcrash.formatters.base.baseformatter Formats the crash report for use in an (text/plain) format_body(description, sys_info=none, traceback=none) Formats the body in plain text. (add a series of - under each section title). Parameters description Description of the issue, written by the user. sys_info Optional system information string log Optional application log traceback Optional traceback. format_title(title) Formats title (add [app_name] if app_name is not None) MardownFormatter class qcrash.formatters.markdown.mardownformatter Bases: qcrash.formatters.base.baseformatter Formats the issue report using Markdown. format_body(description, sys_info=none, traceback=none) Formats the body using markdown. Parameters description Description of the issue, written by the user. sys_info Optional system information string log Optional application log traceback Optional traceback. 16 Chapter 4. API reference

21 CHAPTER 5 Contributing 5.1 Report bugs or ask a question You can report bugs or ask question on our issue tracker. 5.2 Submitting pull requests: Pull Requests are great! 1. Fork the Repo on github. 2. Create a feature/bug fix branch based on the master branch. 3. If you are adding functionality or fixing a bug, please add a test! 4. Push to your fork and submit a pull request to the master branch. Please use PEP8 to style your code: python setup.py test -a "--flake8 -m flake8" 17

22 18 Chapter 5. Contributing

23 CHAPTER 6 Indices and tables genindex modindex search 19

24 20 Chapter 6. Indices and tables

25 Python Module Index q qcrash.api, 13 21

26 22 Python Module Index

27 Index B BaseBackend (class in qcrash.backends), 14 BaseFormatter (class in qcrash.formatters.base), 15 E Backend (class in qcrash.backends), 14 Formatter (class in qcrash.formatters. ), 16 F format_body() (qcrash.formatters.base.baseformatter method), 15 format_body() (qcrash.formatters. . formatter method), 16 U format_body() (qcrash.formatters.markdown.mardownformatter upload_log_file() method), 16 method), 15 format_title() (qcrash.formatters.base.baseformatter method), 15 format_title() (qcrash.formatters. . formatter method), 16 G get_application_log() (in module qcrash.api), 14 get_backends() (in module qcrash.api), 13 get_system_information() (in module qcrash.api), 14 get_user_credentials() (qcrash.backends.githubbackend method), 15 GithubBackend (class in qcrash.backends), 15 I install_backend() (in module qcrash.api), 13 install_except_hook() (in module qcrash.api), 13 M MardownFormatter (class in qcrash.formatters.markdown), 16 Q qcrash.api (module), 13 qsettings() (qcrash.backends.basebackend method), 14 S send_report() (qcrash.backends.basebackend method), 14 send_report() (qcrash.backends. backend method), 15 send_report() (qcrash.backends.githubbackend method), 15 set_formatter() (qcrash.backends.basebackend method), 14 set_qsettings() (in module qcrash.api), 13 show_report_dialog() (in module qcrash.api), 13 (qcrash.backends.githubbackend 23