File: pymailgui-products/unzipped/MailConfigs/README.txt

PyMailGUI per-account server and GUI customization settings files.

The short story:

    Assignments in files here override and customize defaults in the PyMailGUI
    "base" file, which defines and describes all available settings, and may be
    viewed at this path in the install folder (".." is one level up from here):

        ../PyMailGui-PP4E/mailconfig.py

    Change or emulate the examples here to send and receive email on your 
    accounts, and use the "<account>" in filename "mailconfig_<account>.py"
    to choose an account's file in the GUI launcher.  

    For example, if you save a file here named "mailconfig_mymail.py" in which
    your email-server parameters and GUI customizations are assigned, you'll 
    be able to open this account in PyMailGUI's launcher using name "mymail",
    and send and receive email on the servers specified in the file.

    The example files shipped in this folder may be edited or emulated, and any
    of them may be used for experimenting and offline-processing of saved-mail 
    files, but you must setup your own email-provider account parameters to 
    fetch or send email live in the GUI.  See also textConfig.py in folder 
    ../PyMailGui-PP4E for additional PyEdit settings used for mail display.

More details:

    PyMailGUI supports a wide range of customizations via its config files. 
    Both email account parameters and GUI behavior and appearance may be 
    tailored by changing their variable settings in the mailconfig module, 
    using simple Python code - normally, just assignment statements.

    To use PyMailGUI, edit or create one or more "mailconfig_*.py" files of 
    your own to access your email accounts for sends and receives.  The "*"
    part stands for a unique name you'll create for each account, and each 
    file may contain completely different configuration settings. 

    Each file here matching this name pattern shows up as a selectable account
    in the GUI launcher, sorted by name.  In the GUI launcher's selection list,
    choose the "*" characters in the "mailconfig_*.py" filename of the desired 
    account to select it for use in a new PyMailGUI session.

    Account config files may contain any Python code.  Their assignments replace
    (override) the default settings in PyMailGUI's base file, described above.
    You need only assign names that will vary from their base-file defaults, 
    but your files here may reassign any name assigned in PyMailGUI's base file.  

Using example accounts:

    You must configure your own account's parameters to send and receive your 
    email, but can use any of the example account files shipped to process
    saved-mail files offline.  No server connection is attempted until a send
    or receive request is made, and a password is required for all the example
    files' accounts.

    See "SavedMail/" and "sentmail.txt" in the "../PyMailGui-PP4E" folder for 
    example save files to Open, and the "imapfetch" utility program at site
    learning-python.com for a tool that creates save files from server folders.

Passwords:

    As coded and shipped, the MailConfigs files assume POP and SMTP passwords 
    are stored in a one-line file located in the user's home directory.  For
    example, file ~/pmg-pw1.txt (where ~ means /Users/you) looks like this:

    yourpasswordhere

    These files are not located in the program's install folder, and not shipped
    with it.  To use your own accounts, create account password files of your 
    own in your home folder, and/or configure the locations of the password 
    files as desired.  See the config-files' password settings for more info;
    the program will also prompt for passwords if the settings are empty.
    
Extending other files:

    Account config files can also extend another account config file located
    in this folder, by either importing or exec()'ing the other file's code 
    and overriding its assignments, using either of the following forms:

        from mailconfig_OtherFileHere import *
        -or-
        exec(open('mailconfig_OtherFileHere.py').read())  

        ...plus custom settings here...

    See the shipped files here for examples.  When named with a "mailconfig_" 
    prefix, the other file will be selectable in the GUI launcher too.  If 
    the other file's name has no such prefix, it won't itself be selectable.

    In this version, config files here do not import the PyMailGUI base file 
    explicitly - it is loaded automatically and exec()s the selected files 
    here on startup.  All files here extend the PyMailGUI base file implicitly.

Run mode: 

    As of version 3.1, files here are exec()'d, not imported.  They may either
    exec() or import other base files in this folder to run their assignments,
    because both the current working directory and import search path are reset
    temporarily to point to this folder during the top-level exec().  Errors
    in files here trigger a GUI pop-up, with exception details.  

    Caution: all PyMailGUI instances spawned for accounts share the same single
    console window for their messages, along with the GUI launcher.  Closing 
    the shared console window silently closes the launcher and all PyMailGUIs,
    which may be either feature or pitfall, depending on your usage.  Minimize
    the console window to avoid closing all others unintentionally.

File naming: 

    Because these files are not imported as Python modules, their names may 
    now contain any valid filename character.  However, files here imported 
    by other files here must still follow module name rules, and sticking with
    letters, digits, and underscores is generally a good idea for portability.

Example files shipped:

    "mailconfig_<name>.py"
        are user-defined overrides and extensions to the PyMailGUI base file. 
        These files may use exec() or imports to load other base files in this 
        folder.  Top-level files here do not import PyMailGUI's base file, 
        but extend its default settings implicitly.

    "mailconfig_<name>_ssl.py"
        are extensions to base files here having no "_ssl" suffix, coded to
        add SSL server support for transmission privacy when available at ISPs.  
        SSL support was factored off to separate files to allow testing of both
        SSL and non-SSL server ports, but should always be used if available.

    "mailconfig_<name>_ssl_<more>.py"
        are further extensions to SSL bases.  These files demo multiple-level
        config customizations: they extend an SSL file; which extend a non-SSL
        file; which implicitly extends the PyMailGUI base file.  For example,
        the mailconfig.py base file is extended by Lutzmv, Lutzmv_ssl, and 
        Lutzmv_ssl_spam, in that order.  Your account setups may not require 
        such deep nesting (if any), but it works naturally where useful.

    "mailconfig_Gmail.py"
        is a largely self-contained example using SSL, with instructions and 
        code for using PyMailGUI to access Gmail account mail (if you must;
        free email at this provider comes at a huge cost in lost privacy).

    "mailconfig_defaultbase.py"
        is a config file which does _not_ customize the PyMailGUI base file.
        It's here to serve as the equivalent of the default settings shipped 
        with the book from which this program came (PP4E).  If you have just 
        one email account you could change the base file directly and launch 
        via this account name, but extension files are generally recommended.  
        This account's file can be freely removed to declutter the launcher.

    "mailconfig_testerrors.py"
        is a test for handling of errors in config files (remove as desired).
    
    You may freely modify or replace any files shipped for accounts of your own.
    Whatever files remain are listed in the launcher, in name-sorted order.

More settings:

    See file textConfig.py in ../PyMailGui-PP4E for PyEdit popup settings.
    Its font, color, and size settings apply to independent PyEdit windows 
    created for raw text and text parts, not to the text in PyMailGUI's own
    View/Write windows which is configured by files here.

See also:

    -The ../PyMailGui-PP4E/mailconfig.py base file for available settings
    -The GUI launcher's docstring in ../Launch_PyMailGUI.py for more details
    -mailconfig_Gmail.py if you want to run PyMailGUI on a Gmail account
    -The script ../docetc/pickcolor.py for a simple color-string chooser
    -saved-shipped-mailconfigs.zip for original versions of example files here



[Home page] Books Code Blog Python Author Train Find ©M.Lutz