File: pymailgui-products/unzipped/README.txt

PyMailGUI — Email Without the Evil

Version:
    4.1, June 2022

    New: the source-code and macos-app packages (only) were updated
    and rereleased in June 2022, to add a "Message-ID" header to all 
    sent mails, use "Reply-To" if present, throttle down event checks, 
    and more; see the "News" section at the top of UserGuide.html for 
    full details.  Windows and Linux users may use the new source code.

Author:
    © M. Lutz (http://learning-python.com), 2000-2022

License:
    Provided freely, but with no warranties of any kind.  This program is
    open source and is yours to use and copy as you like for personal use.
    For quality and attribution purposes, any bulk redistributions must 
    include in full and unaltered form this file, and file "UserGuide.html"
    and folder "docetc" from the top level of this package.

    Also note that the original version of this program's code appears in 
    the book "Programming Python, 4th edition," and is copyrighted in the 
    author's name.  While it is intended to be used freely, see the book for
    more on its terms of reuse.  The book's license requires attribution, 
    which is satisfied by following the prior paragraph's terms.

Fetch: 
    From "http://learning-python.com/pymailgui.html" download and unzip:

      - PyMailGUI.app.zip (macos app)
      - PyMailGUI-64bit.zip or PyMailGUI-32bit.zip (Windows executable)
      - PyMailGUI.zip (Linux executable)
      - PyMailGUI-source.zip (source code)

    See Package Usage Basics below for more install details.

Start:
    To launch the program, run the unzipped folder or its file:

      - PyMailGUI.app (macos app) 
      - Launch_PyMailGUI.exe (Windows executable)
      - Launch_PyMailGUI (Linux executable)  
      - Launch_PyMailGUI.py (source code)

    See Package Usage Basics below for more run details.

Docs:
    Open UserGuide.html in a web browser for the main user guide.
    Select the Help bar in the GUI to view that document in any distribution. 

Configs:
    Edit MailConfigs/* files to customize PyMailGUI's appearance and behavior.

Backups:
    PyMailGUI saves sent emails in your file PyMailGui-PP4E/sentmail.txt.
    This is a mail-save file; Open in the GUI to view.  See UserGuide.html.

Tools:
    PyMailGUI is coded in Python 3.X, and uses tkinter/Tk for its GUI.  
    macos frozen apps are built with py2app; others use PyInstaller. 

Upgrades:
    To install a future version of PyMailGUI, save and restore your 
    MailConfigs folder; PyMailGui-PP4E/textConfig.py if changed;
    and any sent-mail and saved-mail files located in the install 
    folder (see UserGuide.html's "Recent Updates" for more details).

Updates:
    Watch http://learning-python.com/post-release-updates.html
    for new-release announcements and additional usage pointers.

Other:
    See "Recent Highlights" in UserGuide.html for version changes.
    See UserGuide.html or folder docetc/docimgs for GUI samples.

------------------------------------------------------------------------------

Package Usage Basics

PyMailGUI is available as full source code, a macos app, and executables
for Windows and Linux.  Source code is the ultimate in portability,
but apps and executables integrate better with your computer's GUI,
do not require any additional install steps, and are immune to 
future changes in the Python programming language they use.

The following sections give the fundamentals of each format's usage:

    - macos App Package
    - Windows Executable Package
    - Linux Executable Package
    - Source-Code Package

------------------------------------------------------------------------------

macos App Package

    The macos (f.k.a. Mac OS X) app runs only on Macintosh systems, but 
    requires no Python install and better supports the macos user experience.

    To Install:
        Fetch file "PyMailGUI.app.zip", unzip it by a double-click (or other), 
        and drag the resulting PyMailGUI.app to your /Applications folder in 
        Finder to access it from Launchpad.  You can also move PyMailGUI.app 
        and create aliases to it anywhere else on your computer.
    
    To Run:
        Click "PyMailGUI.app" to start the program (or run the app any other way).
        Running PyMailGUI.app automatically starts PyMailGUI's account launcher,
        the same as running the source-code package's script Launch_PyMailGUI.py.
        From the launcher, open individual account windows to fetch, send, and 
        view email in independently running programs.

        The launcher's window is just withdrawn to the Dock when it is closed, 
        and clicking either the launcher's Dock icon or PyMailGUI's app icon 
        opens and lifts the launcher's window to allow you to open new accounts. 
        Closing an account's window closes it in full, and clicking a Dock icon
        for any withdrawn account opens and lifts the window for that account.  
        Double-click the app and single-click Dock items.  To quit the launcher
        in full, right-click (double-press) its Dock item and select Quit.

    Files:
        Your MailConfigs folder and PyEdit textConfig.py files are located
        inside the unzipped app's folder, at path:
        
            PyMailGUI.app/Contents/Resources

        Navigate to this nested folder in Finder by a right-click on 
        PyMailGUI.app and Show Package Contents (or use "ls" in Terminal).

        See the MailConfigs/README.txt at this location for information 
        on setting up your own email accounts.  The base textConfig.py
        is nested in the PyMailGui-PP4E folder in Resources, as usual.
 
        Your UserGuide.html is in the Resources folder too, but can also 
        be accessed by the GUI's Help bar on the server list window.

    Scripts:
        There are no additional frozen scripts in PyMailGUI, but a script
        is provided for running the embedded PyEdit program in standalone 
        mode as source code (a separately installed Python is required):
       
            PyMailGUI.app/Contents/Resources/Launch_PyEdit.pyw

        For frozen PyEdits that better integrate with your platform's user
        interfaces, see http://learning-python.com/pyedit.

    Versions: 
        The macos app was built on OS X version 10.15 Catalina,
        as a macos universal binary.  It is expected to work on later 
        macos versions.  Support for earlier versions of macos remains 
        to be verified.  The previous app release was built on macos
        10.11 El Capitan, and worked on later macos versions.

    Known issues:
        Due to limitations in the underlying Tk toolkit, emojis are 
        replaced for display only; see the user guide for details.

        Due to a flaw in the underlying Tk toolkit, closed windows may 
        leave zombie items in Dock menus; these can be safely ignored.

        The Run-Code Capture mode of the embedded PyEdit program is 
        intentionally disabled in this package.  To use Capture mode, 
        get the standalone PyEdit program at learning-python.com/pyedit. 

------------------------------------------------------------------------------

Windows Executable Package

    The Windows executables run only on Windows systems, but require
    no Python install and better support the Windows user interface.

    To install:
        Fetch file "PyMailGUI-64bit.zip" or "PyMailGUI-32bit.zip" and  
        unzip it on your computer (see Versions below for the difference).
        Copy the unzipped folder to C:\Program Files or elsewhere to
        save it.  Make Desktop shortcuts to the unzipped folder's
        executable (per the next section) for quick access as desired.

    To Run:
        Click on the unzipped folder's "Launch_PyMailGUI.exe" file to run.  
        Running this program automatically starts PyMailGUI's account launcher,
        the same as running the source-code package's script Launch_PyMailGUI.py.
        From the launcher, open account windows to fetch, send, and view email
        in independently running programs.

    Files:
        Your UserGuide.html and textConfig.py files and MailConfigs folder are 
        located at the top level of the same folder as the ".exe" executable 
        (the folder created by unzipping the download).   The PyEdit component's 
        user guide and base textConfig.py (as documentation only) are in the
        unzipped folder's PyMailGUI-PP4E\__pyedit-component-data__.
        
    Versions: 
        The Windows executable comes in both 64- and 32-bit forms, as denoted
        by its zipfile names.  The former works only on 64-bit systems; the 
        latter works more broadly but may run slower on 64-bit systems.  The
        64-bit executable was built on Windows 7, and the 32-bit version on 
        Windows 8, but both have been verified to run on Windows 7, 8, and 10.

    Known issues: 
        Startups may be briefly delayed due to PyInstaller folder extracts.  
        Use the source-code package if this is problematic on slower machines.

        Due to limitations in the underlying Tk toolkit, emojis are replaced 
        for display only; see the user guide for details.

        The Run-Code Capture mode of the embedded PyEdit program is also
        intentionally disabled in this package.  To use Capture mode, get 
        the standalone PyEdit program at learning-python.com/pyedit. 

------------------------------------------------------------------------------

Linux Executable Package

    The Linux executable runs only on Linux systems, but requires no
    Python install and may better support the Linux user interface.

    To install:
        Fetch file "PyMailGUI.zip" and unzip it on your computer.  Copy
        the unzipped folder to your home, desktop, or other folder to make
        it easy to access, and make desktop shortcuts to the executable as
        desired.

    To Run:
        Click on the unzipped folder's "Launch_PyMailGUI" file to run.  
        Running this program automatically starts PyMailGUI's account launcher,
        the same as running the source-code package's script Launch_PyMailGUI.py.
        From the launcher, open account windows to fetch, send, and view email
        in independently running programs.

    Files:
        Your UserGuide.html and textConfig.py files and MailConfigs folder are 
        located at the top level of the same folder as the ".exe" executable 
        (the folder created by unzipping the download).   The PyEdit component's 
        user guide and base textConfig.py (as documentation only) are in the
        unzipped folder's PyMailGUI-PP4E\__pyedit-component-data__.

    Versions: 
        The sole Linux executable was built on Ubuntu Linux 16.04, on a 
        64-bit system.  It is known to work on this and other versions of 
        Ubuntu and is expected to work on some other distributions of Linux,
        but this is to be verified.  If it fails on your system, use the 
        source-code PyMailGUI package.

    Known issues: 
        Startups may be briefly delayed due to PyInstaller folder extracts.  
        Use the source-code package if this is problematic on slower machines.

        Due to limitations in the underlying Tk toolkit, emojis are replaced 
        for display only; see the user guide for details.

        The Run-Code Capture mode of the embedded PyEdit program is also
        intentionally disabled in this package.  To use Capture mode, get 
        the standalone PyEdit program at learning-python.com/pyedit. 

------------------------------------------------------------------------------

Source-Code Package 

    The source-code version of PyMailGUI runs on all flavors of macos, 
    Windows, and Linux, but requires a separately installed Python.

    To Install:
        Fetch file "PyMailGUI-source.zip" and unzip it on your computer.
        Also fetch and install a usable Python 3.X if one is not already
        present.  On macos and Linux, also install the tkinter/Tk toolkit 
        if needed.  See the user guide's "Install and Launch" for details.

    To Run:
        Run "Launch_PyMailGUI.py" in the unzipped folder to launch 
        the program, using any Python program-launching technique on your 
        platform: Windows icon clicks, IDLE, command lines, macos Python 
        Launcher, etc.  You can also run the file from within PyEdit
        (see learning-python.com/pyedit).

    Files:
        Your UserGuide.html and textConfig.py files and MailConfigs 
        folder are located in the same folder as the main scripts' file 
        (the folder created by unzipping the download).

    Versions:
        Source code is platform-neutral and is not dependent on the 
        version of your operating system.  This package runs on all
        versions of macos, Windows, and Linux in common use today.
        
        The source-code package does, however, require and assume a
        separately installed Python on your computer: download one 
        for your platform from www.python.org/downloads if Python is 
        not already installed.  
 
        PyMailGUI's source code has been verified to run on all Python 
        3.X through 3.8, and has no third-party install requirements.
        Later Python versions are expected to work too, but 3.8 is 
        the latest version verified in depth.

    Known issues:
        Due to limitations in the underlying Tk toolkit, emojis are replaced 
        for display only; see the user guide for details.

        On macos, closed windows may leave zombie items in Dock menus due 
        to a flaw in the underlying Tk toolkit; use Tk 8.6+ if possible.

        The Run-Code Capture mode of the embedded PyEdit program is also
        intentionally disabled in this package.  To use Capture mode, get 
        the standalone PyEdit program at learning-python.com/pyedit. 

------------------------------------------------------------------------------
[end]



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