8.4. Howdy Email API 

change_album_name(new_album_name)

Changes the main album name to a new name, only if the new name is different from the old name.

Parameters:: new_album_name (str) – the new name to change the main Imgur album.

See also

change_name(imgMD5, new_name)

Changes the name of an image in the main Imgur library.

Parameters:

imgMD5 (str) – this is the MD5 hash of the image in the main Imgur library.
new_name (str) – the new name to give this image.

Returns:

True if image could be found and its name changed. Otherwise returns False.

Return type:

bool

See also

upload_image.
delete_image.

delete_candidate_album(candidate_album_name)

This deletes the candidate album from the Imgur account. This album with that name must exist in the Imgur account.

Parameters:: candidate_album_name (str) – the name of the album to remove, with its underlying images.

See also

delete_image(b64img, imgMD5=None)

Removes an image from the main Imgur library.

Parameters:

b64img (str) – the Base64 representation of the image.
imgMD5 (str) – optional argument. This is the MD5 hash of the image. If not provided, this is calculated for that image represented by b64img.

Returns:

True if image can be found and returned. Otherwise returns False.

Return type:

bool

See also

upload_image.
change_name.

get_candidate_album_names()

Returns:: a list of album names in the Imgur account. set_main_album can use this method to determine the valid album name to choose.

See also

get_candidate_albums.

get_candidate_albums()

Returns:: a dict of album information, organized by album name. Each key in the top-level dictionary is the album name. Each value is a lower level dictionary: the id key is the album ID, and the images key is a list of low-level Imgur image information.

classmethod get_image_md5(image)

Returns:: the MD5 hash of the image.
Parameters:: image (PngImageFile) – the native Pillow PNG image object.

get_main_album_name()

Returns:: the name of the main Imgur album, if albums exist on this account. Otherwise returns None.
Return type:: str

refreshImages()

Refreshes the collection of images in the main Imgur album, by filling out self.imghashes. The pictures in an album in our Imgur account are expected to be filled through methods in this object.

The key is the MD5 hash of the image in that library.
The value is a four element tuple: image name, image ID, the URL link to this image, and the datetime at which the image was uploaded.

set_main_album(new_album_name)

Sets or changes the main Imgur album used for storing and displaying images to a new album name. If new_album_name exists in the Imgur account, then sets that name. If new_album_name does not exist, then creates this new Imgur album.

Once this album is set or created,

sets the new Imgur credentials using store_imgur_credentials.
populates self.imghashes with all the images found in this library. Of course, if the album does not exist, then self.imghashes is an empty dict.

Parameters:: new_album_name (str) – the new name of the Imgur album to use for images.
Raises:: ValueError – if images in the new album cannot be accessed.

See also

get_all_email_contacts_dict.

upload_image(b64img, name, imgMD5=None)

Uploads a Base64 encoded file into the main Imgur album. If the image exists, then returns information (from self.imghashes) about the file. If not, create it, put it into self.imghashes, and then return its information.

Parameters:

b64img (str) – the Base64 representation of the image.
name (str) – name of the image.
imgMD5 (str) – optional argument. This is the MD5 hash of the image. If not provided, this is calculated for that image represented by b64img.

Returns:

a 4-element tuple: image name, image ID, the URL link to this image, and the datetime at which the image was uploaded.

Return type:

tuple

See also

refreshImages.
delete_image.
change_name.

class howdy.email.PNGPicObject(initdata, pImgClient)

This provides a GUI widget to the Imgur interface implemented in PlexIMGClient. Initializaton of the image can either upload this image to the Imgur account, or retrieve the image from the main Imgur album. This object can also launch a GUI dialog window through getInfoGUI.

Parameters:

initdata (dict) –
the low-level dictionary that contains important information on the image, located in a file, that will either be uploaded into the main Imgur album or merely kept in memory. The main key that determines operation is initialization. It can be one of "FILE" or "SERVER".

If initialization is "FILE", then upload the the image to the main album in the Imgur account. Here are the required keys in initdata.
- filename is the location of the image file on disk.
- actName is the PNG filename to be used. It must end in png.
If initialization is "SERVER", then retrieve this image from the main album in the Imgur account. Here are the required keys in initdata.
- imgurlink is the URL link to the image.
- imgName is the name of the image.
- imgMD5 is the MD5 hash of the image.
- imgDateTime is the datetime at which the image was initially uploaded into the main Imgur album.
pImgClient (PlexIMGClient) – the PlexIMGClient used to access and manipulate (add, delete, rename) images in the main Imgur album.

Variables:

actName (str) – the file name without full path, which must end in png.
img (QImage) – the QImage representation of this image.
originalImage (Image) – the Image representation of this image.
originalWidth (float) – the inferred width in cm.
currentWidth (float) – the current image width in cm. It starts off as equal to originalWidth
b64string (str) – the Base64 encoded representation of this image as a PNG file.
imgurlLink (str) – the URL link to the image.
imgDateTime (datetime) – the datetime at which this image was first uploaded to the main album in the Imgur account.

Raises:

ValueError – if initdata['initialization'] is neither "FILE" nor "SERVER".

b64String()

Returns:: a 3-element tuple on the image incorporated into this object: its Base64 string, its width in pixels, and the Imgur link.
Return type:: tuple

changeName(new_name, hImgClient)

changes the filename into a new name.

Parameters:

new_name (str) – the new name of the image file to be changed in the main album on the Imgur account. This must end in png.
hImgClient (HowdyIMGClient) – the HowdyIMGClient used to access and manipulate (add, delete, rename) images in the main Imgur album.

classmethod createPNGPicObjects(pImgClient)

Parameters:: pImgClient (PlexIMGClient) – the PlexIMGClient used to access and manipulate (add, delete, rename) images in the main Imgur album.
Returns:: a list of PNGPicObject representing the images in the main Imgur album.
Return type:: list

getInfoGUI(parent)

Launches a QDialog that contains the underlying image and some other labels: ACTNAME is the actual PNG file name, URL is the image’s Imgur link, and UPLOADED AT is the date and time at which the file was uploaded. An example image is shown below,

../_images/email_pngpicobject_infogui.png — Fig. 8.36 An example PNG image that can be stored in the main Imgur library. Note the three rows above the image: the *name* of the PNG image; its URL; and the date and time it was uploaded.

Parameters:: parent (QWidget) – the parent QWidget that acts as the QDialog window’s parent. Can be None.

howdy.email.get_all_email_contacts_dict(verify=True, pagesize=4000)

Returns all the Google contacts using the Google Contacts API.

Parameters:

verify (bool) – optional argument, whether to verify SSL connections. Default is True.
pagesize (int) – optional argument, the maximum number of candidate contacts to search through. Must be \(\ge 1\).

Returns:

a dict of contacts. The key is the contact name, and the value is the set of email addresses for that contact.

Return type:

dict

howdy.email.get_email_contacts_dict(emailList, verify=True)

Returns the Google contacts given a set of emails, all using the Google Contacts API.

Parameters:

emailList (list) – the list of emails, used to determine to whom it belongs.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

Returns:

a list of two-element tuple. The first element is the Google conatct name. The second element is a primary email associated with that contact.

Return type:

list

See also

howdy.email.get_email_service(verify=True)

This returns a working Resource representing the Google email service used to send and receive emails.

Parameters:: verify (bool) – optional argument, whether to verify SSL connections. Default is True.
Returns:: the Resource representing the Google email service used to send and receive emails. If None, then generated here.
Return type:: Resource

howdy.email.send_email_lowlevel(msg, email_service=None, verify=True)

Sends out an email using the Google Contacts API. If process is unsuccessfull, prints out an error message, "problem with <TO-EMAIL>", where <TO-EMAIL> is the recipient’s email address.

Parameters:

msg (MIMEMultipart) – the email message object to send. At a high level, this is an email with body, sender, recipients, and optional attachments.
email_service – optional argument, the Resource representing the Google email service used to send and receive emails. If None, then generated here.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

See also

get_email_service.

8.4.2. howdy.email.email module

This implements the following functionality: sending emails of torrent files and magnet links; sending MIMEMultiPart newsletter or more general style emails to friends of the Plex server; and sending general emails with attachments.

howdy.email.email.get_summary_body(token, nameSection=False, fullURL='http://localhost:32400', verify=True)

Returns the summary body of the Plex newsletter email as a reStructuredText string document, for the Plex server.

Parameters:

token (str) – the Plex access token.
nameSection (bool) – if True, then include this summary in its own section called "Summary". If not, then return as a stand-alone reStructuredText document.
fullURL (str) – the Plex server URL.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

Returns:

the reStructuredText document representing the summary of the media on the Plex server.

Return type:

See also

get_summary_data_music_remote.
get_summary_data_movies_remote.
get_summary_data_television_remote.

howdy.email.email.get_summary_data_movies_remote(token, fullURL='http://localhost:32400', sinceDate=datetime.date(2020, 1, 1))

This returns summary information on movie media from all movie libraries on the Plex server, for use as part of the Plex newsletter sent out to one’s Plex server friends. The email first summarizes ALL the movie data, and then summarizes the movie data uploaded and processed since the last newsletter’s date. Unlike get_summary_data_music_remote and get_summary_data_television_remote, this returns a list of strings rather than a string.

Parameters:

token (str) – the Plex access token.
fullURL (str) – the Plex server URL.

Returns:

a string description of TV media in all TV libraries on the Plex server. If there is no Plex server or TV library, returns None.

Return type:

list

See also

howdy.email.email.get_summary_data_music_remote(token, fullURL='http://localhost:32400', sinceDate=datetime.date(2020, 1, 1))

This returns summary information on songs from all music libraries on the Plex server, for use as part of the Plex newsletter sent out to one’s Plex server friends. The email first summarizes ALL the music data, and then summarizes the music data uploaded and processed since a previous date. For example,

As of December 29, 2020, there are 17,853 songs made by 889 artists in 1,764 albums. The total size of music media is 306.979 GB. The total duration of music media is 7 months, 18 days, 15 hours, 8 minutes, and 15.785 seconds.

Since January 01, 2020, I have added 7,117 songs made by 700 artists in 1,180 albums. The total size of music media that I have added is 48.167 GB. The total duration of music media that I have added is 28 days, 15 hours, 25 minutes, and 37.580 seconds.

Parameters:

token (str) – the Plex access token.
fullURL (str) – the Plex server URL.
sinceDate (date) – the datetime from which we have added songs. Default is date corresponding to January 1, 2020.

Returns:

a string description of music media in all music libraries on the Plex server. If there is no Plex server or music library, returns None.

Return type:

See also

howdy.email.email.get_summary_data_television_remote(token, fullURL='http://localhost:32400', sinceDate=datetime.date(2020, 1, 1))

This returns summary information on TV media from all television libraries on the Plex server, for use as part of the Plex newsletter sent out to one’s Plex server friends. The email first summarizes ALL the TV data, and then summarizes the TV data uploaded and processed since a previous date. For example,

As of December 29, 2020, there are 25,195 TV episodes in 298 TV shows. The total size of TV media is 6.690 TB. The total duration of TV media is 1 year, 5 months, 19 days, 9 hours, 29 minutes, and 13.919 seconds.

Since January 01, 2020, I have added 5,005 TV epsisodes in 298 TV shows. The total size of TV media that I have added is 1.571 TB. The total duration of TV media that I have added is 3 months, 16 days, 4 hours, 52 minutes, and 15.406 seconds.

Parameters:

token (str) – the Plex access token.
fullURL (str) – the Plex server URL.
sinceDate (date) – the datetime from which we have added songs. Default is date corresponding to January 1, 2020.

Returns:

a string description of TV media in all TV libraries on the Plex server. If there is no Plex server or TV library, returns None.

Return type:

See also

howdy.email.email.get_summary_html(token, fullURL='http://localhost:32400', preambleText='', postambleText='', name=None)

Creates a Plex newsletter summary HTML email of the media on the Plex server. Used by the email GUI to send out summary emails.

Parameters:

token (str) – the Plex access token.
fullURL (str) – the Plex server URL.
preambleText (str) – optional argument. The reStructuredText formatted preamble text (text section before summary), if non-empty. Default is "".
postambleText (str) – optional argument. The reStructuredText formatted text, in a section after the summary. if non-empty. Default is "".
name (str) – optional argument. If given, the recipient’s name.

Returns:

a two-element tuple. The first element is an HTML string document of the Plex newletter email. The second element is the full reStructuredText string.

Return type:

See also

howdy.email.email.send_collective_email_full(mainHTML, subject, fromEmail, to_emails, cc_emails, bcc_emails, verify=True, email_service=None)

Sends the HTML email to the following TO recipients, CC recipients, and BCC recipients altogether. It uses the GMail API.

Parameters:

mainHTML (str) – the email body as an HTML string document.
subject (str) – the email subject.
fromEmail (str) – the RFC 2047 sender’s email with name.
to_emails (set) – the RFC 2047 set of TO recipients.
cc_emails (set) – the RFC 2047 set of CC recipients.
bcc_emails (set) – the RFC 2047 set of BCC recipients.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.
email_service – optional argument, the Resource representing the Google email service used to send and receive emails. If None, then generated here.

howdy.email.email.send_email_movie_none(movieName, verify=True)

Request an individual movie from the Plex server’s administrator, using the GMail API.

Parameters:

movieName (str) – the name of the movie.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

Returns:

the string "SUCCESS" if nothing goes wrong.

Return type:

Raises:

AssertionError – if the current Plex account user’s email address does not exist.

howdy.email.email.send_email_movie_torrent(movieName, data, isJackett=False, verify=True)

Sends an individual torrent file or magnet link to the Plex user’s email, using the GMail API.

Parameters:

movieName (str) – the name of the movie.
data (str) – the Base64 encoded file, if torrent file. Otherwise the magnet URI link if magnet link.
isJackett (bool) – boolean flag used to determine whether data is a torrent file or magnet link. If False, then expects a torrent file. If True, then expects a magnet link. Default is False.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

Returns:

the string "SUCCESS" if nothing goes wrong.

Return type: