5. Top Level API

This document describes the lower level NPRStuff API, upon which all the command line and GUI tools are based. It lives in nprstuff.

This module implements the lower-level functionality that does or has the following:

access and retrieve configuration and other data from an SQLite3 database using SQLAlchemy object relational mapping (ORM) classes. The SQLite3 database is stored in ~/.config/nprstuff/app.db.
NPRStuffConfig is an ORM class that stores configuration information.
create_all instantiates necessary SQLite3 tables in the configuration table if they don’t already exist.
low level PyQt5 derived widgets used for the other GUIs in NPRStuff: ProgressDialog, QDialogWithPrinting, and QLabelWithSave.

class nprstuff.NPRStuffConfig(**kwargs)

This SQLAlchemy ORM class contains the configuration data used for running all the NPRStuff tools. Stored into the nprconfig table in the SQLite3 configuration database.

Variables:

service – the name of the configuration service we store. Index on this unique key. This is a Column containing a String of size 65536.
data –
the JSON formatted information on the data stored here. For instance, username and password can be stored in the following way
```
{ 'username' : USERNAME,
  'password' : PASSWORD }
```
This is a Column containing a JSON object.

class nprstuff.ProgressDialog(parent, windowTitle='', doQuit=True)

A convenient PyQt5 widget, inheriting from QDialogWithPrinting, that acts as a GUI blocking progress window for longer lasting operations. Like its parent class, this dialog widget is also resizable. This shows the passage of the underlying slow process in 5 second increments.

This progress dialog exposes three methods – addText, stopDialog, and startDialog – to which a custom QThread object can connect.

startDialog is triggered on long operation start, sometimes with an initial message.
addText is triggered when some intermediate progress text must be returned.
stopDialog is triggered on process end.

Parameters:

parent (QWidget) – the parent QWidget on which this dialog widget blocks.
windowTitle (str) – the label to put on this progress dialog in an internal QLabel.
doQuit (bool) – if True, then using the quit shortcuts (Esc or Ctrl+Shift+Q) will cause the underlying program to exit. Otherwise, hide the progress dialog.

Variables:

mainDialog (QTextEdit) – the main dialog widget in this GUI.
parsedHTML (BeautifulSoup) – the BeautifulSoup structure that contains the indexable tree of progress dialogs.
elapsedTime (QLabel) – the bottom QLabel widget that displays how much time (in seconds) has passed.
timer (QTimer) – the QTimer sub-thread that listens every 5 seconds before emitting a signal.
t0 (float) – the UNIX time, in seconds with resolution of microseconds.

addText(text)

adds some text to this progress dialog window.

Parameters:: text (str) – the text to add.

showTime(): method connected to the internal timer that prints out how many seconds have passed, on the underlying elapsedTime QLabel.

startDialog(initString='')

starts running the progress dialog, with an optional labeling string, and starts the timer.

Parameters:: initString (str) – optional internal labeling string.

stopDialog(): stops running, and hides, this progress dialog.

class nprstuff.ProgressDialogThread(parent, title)

This subclassing of QThread provides a convenient scaffolding to run, in a non-blocking fashion, some long-running processes with an asssociated ProgressDialog widget.

Subclasses of this object need to have a particular structure for their __init__ method. The first three arguments MUST be self, parent, self is a reference to this object. parent is the parent QWidget to which the ProgressDialog attribute, named progress_dialog, is the child. title is the title of progress_dialog. Here is an example, where an example class named ProgressDialogThreadChildClass inherits from ProgressDialogThread.

def __init__( self, parent, *args, **kwargs ):
    super( ProgressDialogThreadChildClass, self ).__init__( parent, title )

    # own code to initialize based on *args and **kwargs

This thing has an associated run method that is expected to be partially implemented in the following manner for subclasses of ProgressDialogThread.

It must start with self.progress_dialog.show( ) to show the progress dialog widget.
It must end with this command, self.stopDialog.emit( ) to hide the progress dialog widget.

Here is an example.

def run( self ):
    self.progress_dialog.show( )
    # run its own way
    self.stopDialog.emit( )

In the run method, if one wants to print out something into progess_dialog, then there should be these types of commands in run: self.emitString.emit( mystr ), where mystr is a str message to show in progress_dialog, and emitString is a pyqtsignal connected to the progress_dialog object’s addText( ).

Parameters:

parent (QWidget) – the parent widget for which this long-lasting process will pop up a progress dialog.
title (str) – the title for the progress_dialog widget.

Variables:

emitString – the signal, with str signature, that is triggered to send progress messages into progress_dialog.
stopDialog – the signal that is triggered to stop the progress_dialog, calling stopDialog.
startDialog – the signal, with str signature, that is triggered to restart the progress_dialog widget, calling startDialog.
progress_dialog – the GUI that shows, in a non-blocking fashion, the progress on some longer-running method.
time0 (int) – a convenience attribute, the UTC time at which the progress_dialog object was first instantiated. Can be used to determine the time each submethod takes (for example, time.time( ) - self.time0).