PyEdit  —  Edit Text.  Run Code.  Have Fun.

Summary:	A Python/tkinter text-editor and code-launcher program and component
Version:	3.0, June 2017 (see all version history)
Author:	© M. Lutz, 2000-2017, learning-python.com
License:	Provided freely, but with no warranties of any kind (see also README.txt)
Screenshots:	This program runs on Mac OS X, Windows, Linux
Usage:	Download and start source code, Mac app, and Windows and Linux executables
History:	This is a much-enhanced version of code that originally appeared in the book PP4E

Contents

• Introducing PyEdit
  • PyEdit's Features
• Using the Program
  • Installing and Running PyEdit
  • Configuring PyEdit
  • PyEdit Auto-Saves
• Using the GUI
  • Menus, Toolbars, and Keys
  • The Screenshots Fine Print
  • File Menu
  • Edit Menu
  • Search Menu
  • View Menu
  • Tools Menu
  • Help Menu
• Platform Pointers
  • Supported Platforms
  • Use the Source, Luke or Lucy
  • Additional Tips
• Recent Highlights
  • Version 3.0, June 2017
  • Prior Versions, 2000-2010

Introducing PyEdit

Welcome to PyEdit—a text-editor and code-launcher desktop GUI that runs locally on your computer. PyEdit is coded in the Python programming language using the tkinter/Tk GUI toolkit. It runs on Mac OS X, Windows, and Linux, per the screenshots above; is available in both portable source-code and self-contained executable formats; and can be used as either a standalone program or a library component embedded in other GUIs. With PyEdit, you get two tools in one: a go-to editor for all your text-based files, and a lightweight IDE for running your Python programs and other launchable code.

PyEdit's Features

PyEdit sports the usual text-editing operations that we've all become familiar with—cut and paste, open and save, search and replace, and the like—but also has features that set it apart from some other text-editing tools:

Portability

PyEdit is a cross-platform program, that runs the same on Mac OS X (recently rebranded macOS), Windows, and Linux—as captured, respectively, by the three screenshots above and others that follow. Simply install it per the next section (plus Python, if you've opted for the source-code format) anywhere you want to edit text and run code. There's no need to use a different text editor program on each of these systems. We'll cover more fine-grained details on platforms ahead.

Configurability

PyEdit allows you to customize key parts of the GUI's appearance and behavior, by editing simple but flexible Python assignment statements in a configuration module. Colors, fonts, auto-save parameters, Unicode policies, code-launch choices, and more can be tailored per user goals and preferences. For the available configuration settings and details on how to edit them, see the configurations module, textConfig.py, located in PyEdit's install folder. As explained there, some programs that embed PyEdit (e.g., PyMailGUI) may have local textConfig.py files that replace PyEdit's own.

Unicode Flexibility

PyEdit allows you to select a different Unicode encoding scheme for every file you open, save, and search, and can display a wide range of Unicode characters. For example, it can handle emails and web documents from arbitrary sources encoded in any Unicode format that Python understands—ASCII, Latin-1, UTF-8, UTF-16, UTF-32, and many more. If your text isn't quite so exotic, you can also configure PyEdit to silently fall back on your platform's Unicode default and never ask on opens and saves again. The Unicode default is usually UTF-8, which includes ASCII, and should suffice for most text files; arbitrary Unicode selection is supported for more specialized content.

End-line Consistency

PyEdit neutralizes platform end-line differences when reading and writing files. It loads files that use any end-line sequences, and always saves your text in files using the hosting platform's end-line sequences. It never writes files with mixed end-lines, even if you edit parts of them on different platforms. Though not normally needed, an included Unix/Windows end-line conversion utility offers more control on demand.

Colors and Fonts

PyEdit allows you to configure both colors and fonts in multiple ways. You can specify initial settings for both, change either at any time, and configure your favorite colors and fonts in lists that are cycled through and applied to windows on demand. Color-list cycling can also be applied automatically whenever a new window is opened during a session: each PyEdit window—including Popups and Grep matches clicked—gets the next color from your favorites list. Font size can also be adjusted up or down quickly with Zoom In and Zoom Out in the View menu (and their toolbar and accelerator equivalents), and line-wrapping can be left off or set to character or word breaks.

Multiple-Window Interface

PyEdit makes it easy to view or edit many files at the same time, by providing a true multiple-window interface. To open a new edit window, simply click Popup in the Tools menu (or use its toolbar Pop button or Command/Ctrl-P accelerator). Once a new window is open, you can start a new file, open an existing file in the File menu, and adjust the window's fonts and colors to your liking in View. Popup windows can be created and closed freely. No matter how many you've opened, PyEdit takes care to check all your open windows for changes on quits, and for already-open files on opens.

External Files Search

PyEdit comes with a powerful "Grep" command that searches for a string in all the external files in an entire directory tree. This is in addition to the usual in-window search. Grep allows you to locate text anywhere on your computer, and edit it automatically within a PyEdit session—search results can be opened in PyEdit immediately with a simple click. Though powerful, this has many uses. If you need to modify all appearances of an address in text notes stored anywhere in your content's folders, for example, Grep makes it fast and easy. Grep supports case and Unicode options, runs searches in parallel for speed, and has a dialog that comes with its own Help describing usage. For more on Grep, see the search menu ahead.

Auto-Saves of Changes

PyEdit automatically saves the text of all changed and unsaved windows to a separate folder at fixed intervals, and cleans up auto-saved files after a number of days. This provides emergency backup copies of your work, in the unlikely event of program crash or operator mistake. If you accidentally dismiss a prompt warning you of unsaved changes, for example, your auto-save folder will contain copies of your unsaved text as of the latest auto-save run. Besides helping you avoid losing work when catastrophe strikes, the auto-save feature is both configurable and optional. There's more on using it in the program-usage guide ahead.

Python (and Other) Code Execution

PyEdit is able to run most Python program code you edit in its windows. It can also launch other edited text files (e.g., HTML) as though you had clicked their icons. While not a full-blown IDE, Run Code allows you to use PyEdit to edit, test, and run programs and other content, without ever having to switch to a console window's command line or other tool. For Python code, PyEdit's code-launching option runs a window's code in parallel with PyEdit itself so the GUI isn't blocked or closed; is able to input command-line arguments and pass them to programs you start; and can connect a spawned program's input and output to either a console window, or PyEdit's own GUI display—scrolling its output, and providing its input on demand. In short, this turns PyEdit into an edit+run programming tool, for programming-inclined users. For more on this advanced feature, see Run Code in the Tools menu ahead.

Open Source Code

PyEdit is released with full source code and a very liberal license. Because you can view its code, there is no opportunity for unknown activity to occur in PyEdit while you are editing your files. And because it's open source, it's both readily customizable, and free of charge. For people interested in programming, PyEdit's source code is also intended to serve as learning resource, with ample documentation. For people less interested in programming, PyEdit is also available in app and executable formats that are a natural match for platform interfaces.

Program + Library Modes

PyEdit is dual-purpose code: it can be used both as a standalone program, and as a component widget that can be embedded in other GUIs. The PyMailGUI email client, for example, both embeds PyEdit in its view and compose email windows, and uses it for text-oriented popups, to provide full-featured text display and editing. Besides reducing work, this code reuse means that both features and enhancements in PyEdit are inherited by PyMailGUI automatically.

Privacy

Last—but certainly not least in today's online world—PyEdit comes with full privacy for both your activities and your content. As a standalone desktop GUI that never connects to the Internet, PyEdit lets you edit text and run code without logging-in to a trackable account, without having your files automatically routed to and from inherently-insecure clouds, and without nosy (and arguably-greedy) companies looking over your shoulder. PyEdit may qualify as an "app" on some platforms, but it leaves out the drama.

This next section and the remainder of this document focus on PyEdit standalone use. Because PyEdit works the same in its embedded roles, though, this document also applies to all programs that use PyEdit as a nested component widget.

Using the Program

Installing and Running PyEdit

PyEdit is coded in Python 3.X (it's been verified most recently on 3.5), and works the same on Mac OS X (a.k.a. macOS), Windows, and Linux, with a different but natural look-and-feel on each. It's distributed from this site as both "frozen" Mac app and Windows and Linux executables, and complete source-code. If you're new to such things, here's the short story:

• The frozen formats run on just one platform each, but are easiest to install, integrate best with your computer's GUI paradigms including icons and associations, and are immune to changes in installed Pythons because they bundle the version they use.

• The source-code format requires a separate Python install everywhere you wish to use it, but its code is portable to (i.e., runs on) every PyEdit platform, and it supports both code auditing and code changes that the frozen versions do not.

Though there are no absolute rules on this, the frozen formats are probably your PyEdit of choice if you'd describe yourself as more "user" than "developer." There's more on the tradeoffs of these formats ahead.

Whichever format you choose, PyEdit's GUI works the same, and as described later in this guide. The way you'll install and start PyEdit, however, is format-dependent. The README file hosts the official story on install packages, but here is a review of the highlights:

App and Executable Packages

In its frozen app and executable formats, PyEdit is a self-contained zipfile containing the app or executable, plus all its associated and required files. To use this format, simply:

1. Download the zipfile for your platform—Mac app, Windows 64-bit or 32-bit exe, or Linux executable
2. Unzip to a folder on your computer
3. Click on the folder's app or executable to run—PyEdit.app on Mac, PyEdit.exe on Windows, PyEdit on Linux

No Python install is required, no third-party packages must be installed, and PyEdit isn't affected by any other Pythons that may be installed on your computer. For more convenience, drag PyEdit to an alias or shortcut on your desktop, copy it to your computer's Applications or Programs folder, drag-and-drop text files to PyEdit to open, and associate text files to open in PyEdit automatically when clicked (a Right-click + Open With is the usual first step).

Mac users:

You can also drag the unzipped PyEdit.app to your /Applications folder in Finder to add it Launchpad's screen. Because an app is really a self-contained folder, your textConfig.py configurations file and default auto-save folder are nested inside the app itself—right-click the app, select Show Package Contents, and click to Contents/Resources to access these files (more on these ahead).

Windows and Linux users:

Your textConfig.py configurations file and default auto-save folder are in the unzipped folder too, along with the PyEdit executable. You can create shortcuts to your executable anywhere you wish, and copy or move the unzipped folder as desired.

See PyEdit's README.txt for more on versions and launches, and ahead in this section for more on configuration and auto-saves.

Source-code Package

In its source-code format, PyEdit is a zipfile containing the program's complete source code that you'll run with a local Python. Because source-code is portable, there is just one such package for all platforms. To use this format:

1. Download the source-code zipfile
2. Unzip to a folder on your computer to install PyEdit
3. Also install a Python 3.X to run PyEdit if one isn't already present: get Python here
4. Also install a tkinter/Tk GUI toolkit if required on your platform: see details ahead
5. Use normal Python techniques to launch the program's main script: textEditor.py

The main script can be run by command line, icon click where supported, and so on. Unlike apps and exes, this format works on all platforms, and allows you to run PyEdit with Python versions of your choosing, use PyEdit as a library in other programs, and change it as you wish—an option more for programmers than end-users, of course, but source-code offers ultimate control when you want it.

In all source-code packages, your textConfig.py configurations file and default auto-save folder are in the unzipped folder too, along with the program's main script. You can create shortcuts to the main script anywhere you wish, and copy or move the unzipped folder as desired; your desktop and home folders are likely candidates.

Windows users:

The source-code packages of both PyEdit and PyMailGUI also allow you to register PyEdit to open clicked text-files automatically, by associating the file pyedit.bat shipped with these packages. See that file for more details; its launches work but display a console momentarily, which you can avoid by installing the frozen app or executable PyEdits described above.

PyEdit is also shipped with the PyMailGUI email client as an embedded component, and can be launched standalone in that system's source-code package—run its Launch_PyEdit.pyw to start PyEdit's included source-code version by itself.

See PyEdit's README.txt for more on versions and launches, and ahead in this section for more on configuration and auto-saves.

For more help on install and launch techniques, check out the platform pointers ahead. However you choose to install and start PyEdit, if all goes well it will open a blank main GUI window, where you can begin typing new text or open an existing file for editing or running. What you'll do next involves GUI operation, covered ahead. First, this section takes a quick look at configuring PyEdit for your tastes, and recovering your work in emergencies.

Configuring PyEdit

As introduced earlier, PyEdit allows you to configure assorted aspects of its appearance and behavior to your liking, by coding simple Python assignment statements in its textConfig.py configurations file. This file is located in either the install folder of PyEdit itself when using the program directly, or that of another program that uses PyEdit; PyMailGUI, for example, has its own version that overrides PyEdit's. Edit this file's assignment statements per its instructions to change its settings as you wish.

While some appearance settings can also be changed in the GUI itself (e.g., text window font, color, and size), other settings are made available for user preferences in the configurations file only (e.g., the Run Code's output-window font and optional Python executable). For the full story on file-based configurations, see the configurations file's own in-file documentation.

Also note that you'll probably want to save and restore your textConfig.py file if you upgrade to a new PyEdit version, because it's located in the program's install folder. Simply move this file from your prior install's folder to your desktop (or elsewhere); run the new install; and then move the file back into the new install's folder. Be sure to check for changes in the defaults to see if there's anything new you can tailor (per Recent Highlights).

PyEdit Auto-Saves

As also mentioned earlier, PyEdit automatically saves the full text of all changed and unsaved windows to a separate folder at fixed intervals, and cleans up auto-saved files after a number of days. This provides emergency backup copies of your work, in the unlikely event of program crash or operator mistake. For example, if you accidentally save an old copy of a file in another window, or unintentionally dismiss a prompt warning you of unsaved changes, all is not lost—your auto-save folder will contain copies of your unsaved text as of the latest auto-save run.

To restore your edits, simply:

1. Locate your auto-save folder.
2. Copy the save file there to its original location.
3. Rename the save file to negate naming-pattern additions.

How Auto-Save Works

By default, the auto-save feature:

• Runs every 5 minutes to save the content of all open windows with unsaved changes
• Removes files in the auto-save folder after 7 days of inactivity to minimize clutter and space
• Saves changes to a folder named __pyedit-autosaves__ in the running program's install folder
• Saves text of known-name files as filename--AT--directory, to make same-named files unique
• Saves text of nameless windows as _nameless-seq-pid.txt, to make them unique across sessions
• Saves all windows' text in files using the general UTF-8 Unicode encoding scheme

The first three of these parameters can be changed per your goals—run minutes, retention days, and save-folder name and location are further described and can be tailored in your textConfig.py configurations module. See that file for more details on configuration options and file-naming patterns. For instance, you can tell auto-save to run more or less often, or save files elsewhere. You can also disable auto-saves altogether, but they provide a crucial fallback option when things go wrong, at a very minor cost in space and time.

Of all auto-save parameters, save-folder location may be the most useful to configure. The default auto-save folder is named "__pyedit-autosaves__" and is located in the running program's own install folder. The folder can vary per usage mode:

• When running PyEdit itself, the auto-save folder is nested in the top level of your unzipped distribution package, described above.
• When using PyMailGUI, the auto-save folder for emails edited with the embedded PyEdit is nested in PyMailGUI's top-level folder.

Either way, the auto-save folder default may in some cases be inconvenient to locate. In Mac apps, for instance, it's nested in the app bundle itself, and in some contexts requires a right-click on the app to view. To route auto-save files to a folder of your choosing, see textConfig.py.

Restore Example

As an example of auto-save recovery at work, this document's file was accidentally overwritten by an unfortunate but typical sequence of events: its new version was saved in a window that was then closed, but its former version was later resaved in an older window where the file had been opened redundantly for comparisons. The net effect of the second save was to erase an hour of intense edits (it happens!).

Auto-save to the rescue: to restore all changes since the last auto-save—which occurred just 3 minutes earlier—all that was required was copying and renaming the auto-save file. Because this session was running the frozen app on a Mac OS X machine with no auto-save customizations, auto-saves were stored in the following folder, viewable by right-clicking the app in Finder (or running an "ls" in Terminal):

    /Applications/PyEdit.app/Contents/Resources/__pyedit-autosaves__

    UserGuide.html--AT--_MY-STUFF_Code_pymailgui_PyMailGui-PP4E_PP4E_Gui_TextEditor

    /MY-STUFF/Code/pymailgui/PyMailGui-PP4E/PP4E/Gui/TextEditor/UserGuide.html

Auto-Save versus Save

It's important to note that PyEdit auto-save never automatically overwrites a file you are editing—a strange policy of some other tools that seems presumptuous at best, and rude at worst. Instead, PyEdit auto-saves your work to temporary files in a different folder. That means it's safe to experiment with changes that you might not want to keep. When you do want to save changes permanently, use an explicit File-menu Save or Save As to update your file in-place, per the GUI operations this guide turns to next.

Using the GUI

Many of the GUI's actions are standard among text editors, and straightforward enough that a test drive probably suffices for some users. Moreover, PyEdit's advanced tools (including Grep and Run Code) come with their own in-program documentation that we won't rehash here. As a more formal reference, though, this section—the largest in this guide—provides a rundown of the GUI's functionality, and gives usage notes and tips along the way. If you don't care to read it now, file it away for future downtime.

Because PyEdit's menus are its main interface device, the overview in this section is organized by their content:

• File Menu
• Edit Menu
• Search Menu
• View Menu
• Tools Menu
• Help Menu

Before we jump into the coverage, here is a brief tour of action-invocation options, as well as a few details about the screenshots you'll see along the way.

Menus, Toolbars, and Keys

All of PyEdit's main actions are accessed through its menus—panels of selectable operations, which appear either:

• At the top of the screen on Mac OS X
• At the top of each PyEdit window on Windows
• At the top of each PyEdit window on Linux (usually)
• In nested frames when PyEdit is embedded in another GUI
• In tear-off windows on Windows and Linux (via dash-line clicks)

Regardless of where they show up on your display, actions in the menus can be invoked both in the menus themselves, and also by their corresponding:

• Accelerator shortcuts—platform-specific key sequences shown in the menus' labels
• Alt-underline shortcuts—sequences using underlined menu characters on Windows and Linux
• Toolbar buttons—commonly-used menu actions at the bottom of the window

For example, the Run Code option can be invoked by its named entry in the Tools menu; by its Ctrl+X (command+X on Macs) accelerator-key combination; or its button in the toolbar—the word Run plus a gear symbol to make it stand out. On Windows and Linux, the Alt+T+R key combination is Run Code too. These all invoke the same tool; they're just alternative access points.

The bottom-of-window toolbar is mostly a convenience. Its buttons vary in appearance per platform to optimize their usability (try them to see what they do), and reflect commonly-used options. You can configure the toolbar's font to your liking, though not its content; use menus and/or their accelerators for other menu actions the toolbar omits.

Accelerator key combinations—and their labels captured in the shots below—vary per normal platform conventions:

• On Macs, the "^" means the "control" key, the splat-ish ⌘ symbol is "command", and function keys may require a "fn" press unless you've changed this in your keyboard preferences. For example, command+o is Open, control+q is Quit, and fn+F3 (or just F3) is Color List. A circle with an arrow emanating from it means Escape (esc), though this seems more hieroglyphic than intuitive.
  
  
• On Windows and Linux, accelerator labels are arguably more straightforward. For instance, "Ctrl+O" means press "Ctrl" and "o" together to trigger an Open, "Alt+q" is Quit, and F3 is Color List. Escape is "Escape"—boring perhaps, but deterministic.

This is one of the many differences which tend to make cross-platform work more exciting than it should be, but computer vendors naturally have a vested interest in the proprietary. The good news is that seasoned platform hoppers adjust to accelerator differences (eventually!).

Related tips:

• Other keys: the Tk Text widget used by PyEdit for display and edits may support additional keyboard bindings beyond those explicitly added or supported by PyEdit itself and listed in its menus ahead. Most seem obscure, but for details try this reference. Most of these can be used in Run Code's output window too (see Tools).

• Scrollbars: PyEdit's text display comes with both vertical and horizontal scrollbars that are useful when line-wrapping is off (see View). They generally work as you'd expect, but Mac users should note that right-click (or two-finger click) in most parts of the scrollbar jumps to that location immediately, and control-click jumps to top and bottom of file alternately. For example, a right-click near the bottom, or control-click once or twice, goes to end of file quickly. Scrolls work as usual, by drags, swipes (two-fingered on Macs), and mouse wheels.

The Screenshots Fine Print

Finally, three quick footnotes regarding this section's upcoming screenshots:

The images

First, the three opening images in each section were captured on Mac OS X, Window, and Linux, respectively; click to view full-sized. Additional images are from Mac only, mostly for space; to see their equivalents on Windows and Linux, plus additional captures not embedded here, see the full screenshots collection (and click on its "index.html" files for thumbnails where needed).

The context

Second, for Mac users: the shots here capture the frozen app in action. If you instead run source code via the Mac Python Launcher, your application menu's title is "Python" (not "PyEdit"), though the menu is otherwise the same. The Launcher also uses a generic rocket icon in most contexts (not the PyEdit icon shown here), but this is just cosmetic. Windows and Linux don't vary as much.

The content

Third, the content of some of the text files shown in the captures changes over time, and may differ slightly by the time you view these images (e.g., some URLs in README.txt were recently updated, and the release date slipped). Given that there are 70 shots taken on 3 different platforms (with indexes), keeping these fully up to date would be a daunting task (if not cruel and unusual punishment!).

In other words, these are just representative examples. You can also turn the images off in most webbrowsers if they're too distracting for your tastes. GUIs are inherently visual and the shots provide context (plus 30% more fun), but some readers may prefer a text-only guide.

File Menu

This menu is about the files in which your text is saved, and is one provider of program and window closures. Because PyEdit is a multiple-window interface, operations here also work hard to avoid erasing unsaved changes.

Open Open a file for editing in this window. You'll be prompted to save the window's current text if it's changed and unsaved, and a standard file-selection dialog for your platform will be popped-up (or slid-down on Macs) for you to choose your file. If all goes well, the newly-opened file's text appears in this window—the window active when you selected Open. If you'd rather edit your file in a new window, use the Popup command in the Tools menu described ahead, and then Open in that window. On most PyEdit platforms, you can also open an existing file in a new window by a click on a file associated with PyEdit, a drag-and-drop of a file onto PyEdit's icon, or a right-click file-open menu; these all run an implicit Open in the new window. By default, Open prompts for the name of a Unicode scheme with which to decode the file's text as it is read from your file. As described above, this is a feature which allows you to open nearly any kind of text file, but you can disable the popup with a simple edit in your configurations file if all your text will use your platform's default encoding (and if you don't know what Unicode is, your files probably qualify). See your textConfig.py file for more on its Unicode policy settings. One subtle point here: PyEdit may open your file successfully even if the encoding type you input at its Unicode prompt fails, because multiple encoding schemes are tried before giving up (including your platform's default). To see which encoding was used for the file, open the Info dialog in the Tools menu; to see all the encoding steps PyEdit follows, see the last portion of the configurations file. Open also tries to warn you if you're asking to open a file that's already open in another window—a potentially-dangerous move, because you might make conflicting changes in either copy (no, really). If you decline the open, the window or windows where the file is already open are automatically raised on screen for quick access (even if currently minimized). If you approve the open, you'll get a new copy of the file's text in a new window; you may want to do this, after all, to compare parts or inspect changes made. One caveat here: the already-open check is limited to files open in a single PyEdit process. It always works if you start PyEdit once and open files within its GUI; always applies to files opened by Greps (see ahead); and fits perfectly with Mac OS X, where a single PyEdit app process runs perpetually and handles open-document messages on file clicks, Open Withs, and drag-and-drops. Still, if you start PyEdit itself more than once, or open files by clicks and drops on some other platforms, be careful about duplicate opens; PyEdit may not be able to warn you. New Start a new file in this window. You'll be prompted to save the window's current text if it's changed and unsaved, and the window will be cleared of any existing text. Your new unnamed file's name will display as "None" (i.e., nameless) in the black filename bar at the top, until you've saved it under a filename. You can also open a new PyEdit window to start a new file, by using the Popup option in the Tools menu discussed ahead. Save Save this window's text to a file. If you've already saved the file at least once (and it has a real name in the black filename bar at the top), this option saves it at its known location. Otherwise, you'll receive a platform-specific file dialog popup allowing you to specify where you want the file to be saved. Like Open, the initial save of a file prompts you for the name of the Unicode scheme with which to encode the text as it's written to your file. This allows you to save in any encoding known to Python; also like Open, though, you can disable the popup and use your platform's default by editing your textConfig.py configurations file. As mentioned earlier, PyEdit also features an auto-save feature that saves backup copies of your changed and unsaved windows' text at regular intervals to a separate folder. These copies are meant only for emergency recovery, and are automatically deleted later. For normal work, use the GUI's Save or Save As to explicitly save your files and retain your changes. Tip: be sure to include an extension at the end of your filename when saving, if you want one. PyEdit doesn't add one automatically, because it cannot guess your content's type, and doesn't impose choices silently as a rule. New files might be general text (.txt), Python code (.py), web pages (.html), comma-separated data (.csv), or any other type of text. In fact, you might want them to have no extension at all. Appending a ".txt" automatically might be not only wrong but rude—especially where extensions are hidden by default. About emojis: PyEdit does not fully support emojis (like 😊), because the current version of the Tk GUI library it uses does not either. You cannot insert new emojis into text you're editing; and although you can open and view existing files containing emojis, their emojis are replaced with the Unicode replacement character (often shown as �) for display, and will not be retained if the content is saved again to a file. That is: ☞ saves discard emojis; they will be replaced with � in your file too, and you'll get a warning anytime this is a potential. The reasons for this are too complex to get into here, but if you're interested in gory details, see this folder and its README, and try this page for general background on the BMP—the set of Unicode characters that Tk, and hence PyEdit, do support (emojis are really just part of Unicode's "astral" planes, but this is not a science-fiction novel). The good news is that PyEdit's workaround allows you to view emoji-laden files; without the replacements, such files wouldn't open at all. Better still, this limitation does not apply to the very many other Unicode symbols and language characters in the BMP's U+0000..U+FFFF codepoint range. Though not supported by some other widely-used editors, all such text can be displayed, edited, and saved correctly in PyEdit's GUI—including these: ✓ ☓ ☑ ☒ ☀ ☼ ☉ ★ ☆ ☞ ☜ ☯ ⚐ ♡ ☮ 重 出 ж म ä ☺. Save As Save this window's text to a file. This option always asks for the file to which text should be saved, whether it has already been saved or not. Among other things, this allows you to make another copy of the text. See Save above for notes on the Unicode popup in Save As. Quit Close this window or exit the program. This has the same effect as the window close action for your platform (e.g., the upper-left red circle button on Mac and Ubuntu Linux, and the upper-right "X" on Windows on Fedora Linux). Quit closes windows and always warns you about any unsaved changes before closes, though its scope depends on the type of window on which it is invoked: For a popup window, Quit prompts you about unsaved changed in that window only. If approved, the Quit closes that window only and PyEdit continues. If cancelled, Quit does nothing. Popup windows are identified by both the word "Popup" and a ☝︎ symbol in their title bars (for legibility and consistency; Windows and Linux can use unique title-bar icons, but they are tiny on Windows, and absent on Mac). For a main window, Quit asks about changes in all open windows. If approved, Quit closes all windows and ends the program. If cancelled, Quit automatically raises all windows having unsaved changes on screen (even if they are minimized), to help you decide how to proceed. Main windows are distinguished by the word "Main" plus a ✍ symbol in their title bars on all platforms In both cases, Quit closes windows—and for main windows ends the program—immediately and without prompts if there are no unsaved changes. In other words, if a window closes silently on Quit, you can assume that nothing had changed in the window's text since the window's latest Open, Save, or Save As. If the entire program exits silently on a main-window Quit, the same was true of all open windows. This model makes it easy to end a session—closing a main window ends the program immediately if there are no unsaved changes—but you should keep this in mind when you're closing individual windows. Because their behavior differs (and matters!), PyEdit goes out of its way to help you differentiate the two window types per the title-bar makings described above. Also remember: if you accidentally dismiss a changes-verification prompt on Quit, a recent copy of your work is still available in your auto-save folder, described earlier. Popup windows are created by Popup in the Tools menu (and its equivalent "Pop" toolbar button and Ctrl/Command-P accelerator key); by clicking on Grep matches (also in Tools); and by other programs. The Clone option in Tools makes a window of the same type as the subject; running it on a main window is the only way to make another main window. You can also open more PyEdit windows by running the program again (e.g., clicking its shortcut or alias on your desktop). For the Mac app, this simply creates a new popup window if PyEdit is already running. For others, this makes independent windows that are never closed by another run's windows, though separately-started sessions don't know about unsaved changes or open files in other sessions. Note to Mac users: You also have a Quit in the application's (leftmost) menu and in your Dock item for PyEdit. Both are always the same as the main window's red-circle quit button and File-menu Quit—they close the entire app and all its windows, either immediately if there are no unsaved changes, or after you verify the quit. That is: File-menu Quit is specific to the window being closed, and is the same as the window's quit button (described above). Application-menu and Dock Quit apply to the whole program, and are the same as a main window's quit. Note that the program closed by the application-menu and Dock Quit may be another app, when PyEdit is embedded in another program (e.g., for PyEdit popup windows created in PyMailGUI). Be sure to check the app's name in the application-menu bar and Dock before selecting their Quit actions.

Edit Menu

This menu deals with changes—including a few common but useful operations above and beyond typing text on your keyboard. Undo and Redo, for example, allow you to back out and reinstate any number of changes so far.

Undo Undo the most recent change made to your text. This works for changes made by both keyboard and GUI interactions. PyEdit has unlimited undo/redo: clicking Undo repeatedly backs out successively-older changes, until there are no more to undo (or you stop clicking). This allows you to experiment with changes to your text that you might not want to keep. Subtle point: Undo deals with all the changes that you've made during your entire PyEdit session, not just those that happened since you last saved your file. This allows you to back out changes even after you've saved them to a file: just Undo and Save again. If you want to check if your session has unsaved changes, use Info in the Tools menu. Redo Redo the most recent change to your text that you backed out with Undo. This is essentially the inverse of Undo, and works in tandem with it: you can restore the changes you've undone by clicking Redo repeatedly. Each Redo reapplies successively-newer undone changes, until there is nothing left to redo. Cut Delete the selected and highlighted text, after saving it to the cross-program clipboard. Text transferred to the clipboard this way can be inserted later with Paste, and is available to other programs. Copy Save the selected and highlight text to the cross-program clipboard, but don't delete it. Text copied to the clipboard this way can be inserted later with Paste, and is available to other programs. Paste Insert the text currently on the cross-platform clipboard, if any, at the current insertion point in this window (where the cursor is blinking). If any text is currently selected and highlighted, it will be replaced by the pasted text. Text on the clipboard may come from a prior Cut or Copy in PyEdit, or from similar actions in another program. Subtle point: pasted text is not highlighted, because a subsequent Paste would immediately erase it. Instead, the cursor is simply moved just past the newly-inserted text. Use Undo to back out unwanted Pastes. Delete Delete the currently selected and highlight text in this window without saving it to the clipboard. This can also be done with a backspace or delete key, so it has no accelerator shortcut. Select All Select and highlight all the text in this window. This is commonly used to erase and start anew, or copy your entire document elsewhere by following up with a Copy.

Search Menu

This menu's job is finding things—both text and line numbers, in both windows and external files. Its Change is search+edit but can also just be search, and its Grep scans entire folders.

Goto Line jump: scroll the display to show the line whose relative number you enter in a popup. This can be useful if you've been given a line number by another program. You can also jump to top of file without a scroll by going to line number 1 (or using the "Top" button in the Change dialog covered ahead). Find Simple search: locate, select, highlight, and scroll to the next occurrence in this window of a string that you enter in a popup. The search always begins at the current insert cursor's position (scroll or Goto the top to search the entire file), and is either case-insensitive ("a" = "A") or not, depending on your textConfig.py configurations-file settings. It's worth noting at there are three search tools in PyEdit. Find (this) is meant for simple search needs, and is designed to be used in conjunction with Refind. To instead search a window's text with case-sensitivity selected in the GUI, use the Change option ahead in this menu. To instead search external files, use Grep. Refind Search again: locate, select, highlight, and scroll to the next occurrence of a string in this window that was used for the latest Find, or one you'll enter in a popup if there was no previous Find. Refind is used as a quick continuation of a prior Find: on each Refind, you'll locate and scroll to the next matching string without having to reenter it. Change Advanced search: open the Find/Change dialog to locate a string and/or replace it with another in the current window, any number of times. This is a non-modal (stay-up) dialog that not only does the same work as Find and Refind, but can also replace successive appearances of the search string with another. This dialog's searches are case-insensitive by default ("a" matches "A"); set its "Case?" toggle to make searches case-sensitive instead. Like Find, this dialog also searches from current cursor position to end of file; Change, however, also provides a "Top" button that you can use to jump the top of file quickly to search again. For more details on this dialog's usage, click its Help button to view its dialog-specific help. Note: the toolbar's "Find" is really Change, because the Find/Change dialog is more useful than the simple Find and Refind menu options, and similarly locates successive matches on Find clicks. Tip: a Refind (e.g., control+G or Alt+g) repeats this dialog's prior Find too. Grep External files search: find all appearances of a string among all the external files contained in an entire directory tree whose names match a filename pattern. Unlike Find and Change, the Grep dialog searches files on your computer, not already-open PyEdit windows. It opens a non-modal (stay-up) dialog, whose Search button kicks off a process that searches your files in parallel with PyEdit, and reports its results in a listbox popup. When clicked, the listbox popup's entries in turn automatically open matching files in new PyEdit windows, which scroll to and highlight their matching lines. Matching-file opens work the same as a manual Open, and run its already-open test (especially useful when editing many matches). Like Change, Grep's search is case-insensitive by default to locate more matches ("pyedit" will match "PyEdit"); set its "Case?" toggle to make searches case-sensitive instead for more-specific needs ("pyedit" will not match "PyEdit"). Apart from case, the search string itself is a simple string always matched verbatim, not a potentially-complicated pattern. Unlike Change, Grep also uses an input Unicode encoding name to use when reading the files it searches; while most users can accept its default, this allows searching many types of text. One usage note here: because a very large number of matches might take a long time to display (if not hang the GUI altogether), Grep will warn you when the number of matches is fairly large, and allow you to skip the display. The warning cutoff is somewhat arbitrary and the dialog does not necessarily mean you cannot proceed to view the results; it's just a heads-up that you may be taking a risk for pathologically-large result lists (200K may qualify!). This is an advanced but powerful tool—and roughly like a Unix find+grep, but portable to Windows. For example, you might use Grep to locate and edit all appearances of a variable name in your entire source-code folder tree all at once. You could also use this to locate a misplaced note by searching all the text files on your entire drive for an identifying term (e.g., the name of a person or month). For more details on this dialog's usage, click its dialog-specific Help button.

View Menu

This menu is all about appearances—it provides multiple ways to tailor your text's font and color for a more visually-pleasing edit session. It also toggles line wrapping if you prefer splitting over scrolling.

Zoom In Increase the font size of this window's text to make it appear larger. You can achieve similar effects in this menu with Pick Font selections and Font List settings (below), but Zoom In is a quick way to make the text bigger. Pick Font's initial value fill will display the new size. Zoom Out Decrease the font size of this window's text to make it appear smaller. You can achieve similar effects in this menu with Pick Font selections and Font List settings, but Zoom Out is a quick way to decrease the text's size. Like Zoom In, Pick Font and Info display the new size. Font List Apply the next font setting in the font list to the current window. The font list has a program preset, but can be customized in your textConfig.py configurations file. Each time you select Font List, the window's font advances to the next setting in this list. Use this menu option to cycle through your textConfig.py's favorite-fonts list. Pick Font Popup a non-modal (stay-up) dialog to select a font to be applied to this window's text. This dialog displays the currently-used font initially, and accepts a new font family, size, and style. Its setting applies only to the current window in the current PyEdit session, but it can be used to experiment with fonts you might opt to make permanent in textConfig.py's font list or initial-font setting. For more details on this dialog's usage and the values it accepts, click its Help button to view its dialog-specific help. Color List Apply the next foreground/background color in the color list to the current window. The color list has a program preset, but can be customized in your textConfig.py configurations file. Each time you select Color List, the window's colors advance to the next combination in this list. This also happens automatically if you enable color cycling in textConfig.py: each new window (main, popup, or component) is set to the next color combination, including the Tools menu's Popups and Clones, and the search menu's Grep matches. Use Color List to manually cycle through your textConfig.py's favorite-colors list in the current window. Pick Bg Popup a non-modal (stay-up) and platform-specific dialog to select a background color to be applied to this window's surface. This dialog's setting applies only to the current window in the current PyEdit session, but it can be used to experiment with colors you might opt to make permanent in textConfig.py's color list or initial-color setting. Pick Fg Popup a non-modal (stay-up) and platform-specific dialog to select a foreground color to be applied to this window's text. This dialog's setting applies only to the current window in the current PyEdit session, but it can be used to experiment with colors you might opt to make permanent in textConfig.py's color list or initial-color setting. Foreground color is also automatically applied to the insertion cursor, so that a dark background doesn't hide the cursor's black default. Line Wrap Toggle line-wrapping modes in the window's text. By default, PyEdit does not wrap lines, and provides both window resizes and a horizontal scrollbar to pan left and right as desired. Line Wrap (and its Escape key and toolbar carriage-return button equivalents) allows you to instead wrap your text's lines to fit your window, at either character or word boundaries. Each time you select Line Wrap, the line-wrapping mode cycles from none, to character wrapping, to word wrapping, and back to none again. For example, to view a window's text with lines broken visually ("wrapped") at the last character that can fit in the window, click Line Wrap once. To view with word wrapping, where lines are split on rightmost whitespace, click Line Wrap again. A third click turns line wrapping off again, and restarts the cycle. Note that this modifies the text's display only, not its content; no end-line characters are ever added when wrapping is enabled, and line content when saved to a file is always as it appears in unwrapped view. Be careful not to rely on wrapping too much, because what you see may not be what you get—if you always work in wrapped mode and never press your Enter/Return key, your text may be saved as a single very-long line! If in doubt, leave wrapping off and use the scroll bar, especially for structured text like program code.

Tools Menu

This menu is a grab-bag of tools you may find useful while editing: new windows, text information, and a simple IDE for coders. The latter of these allows you to edit and run code—both Python programs and clickable content like HTML—without ever leaving PyEdit.

Info Post a dialog giving information about the window's text and display. This includes the current insert cursor's position (line and column numbers, both starting at 1), and the text in the window (its number of characters, lines, and roughly words). You can use these to check your position in the file without having to manually count characters and lines (handy to align text at a fixed column or get a line-count metric). This dialog also reports the current font and color (useful if you want to save one you like in your textConfig.py file to make it permanent) plus the state of unsaved changes (an alternative to pressing Quit to check). Popup Open a new, independent, and empty PyEdit edit window, in which you can type new text or open an existing file to edit. Popup windows' chief distinction is that they can be closed individually and verify just their own changes on Quit, as described earlier. They are closed automatically along with a main window on program exit, but only if their unsaved changes are first verified. Popup windows can be identified by the word "popup" and a ☝︎ symbol in their title bars; they are an easy-to-use alternative to using New to open a different file in the same window, or launching a new PyEdit program run. Popup windows are also opened by the "Pop☝︎" toolbar button, their accelerator keys, and automatically for Grep match results. Note to Mac users: In the frozen app distribution of PyEdit, you can also quickly create a new empty Popup window by double-clicking the PyEdit app or single-clicking its Dock entry, when it is already running. This also works when clicking the Python Launcher's Dock entry when running the source-code version of PyEdit. Clone Open a new, independent, and empty PyEdit edit window. Clone creates a new window of the same type—popup or main—as the window from which it was invoked. The Popup option should normally be preferred to Clone because Popup windows can be closed individually, but Clone is available for use as an alternative window scheme in embedded (non-standalone) PyEdit roles. When a main window is Cloned, the new window will not have "popup" in its title, and will verify all window's changes and exit the program on Quit. Run Code Assume the text in this window is Python program code or other launchable content, and run it. Non-Python code is run as though you had clicked its file's icon. Python code can be run in a spawned program running in parallel so it doesn't impact PyEdit; with or without command-line arguments input in the GUI; and with the code's IO (input/output) streams mapped to a console window or PyEdit's own GUI display. In the latter case, the code's output is scrolled as it appears, and its input is entered and sent on user request; this allows you to run interactive code even if PyEdit itself is started without a console window (e.g., by clicks). In effect, this turns PyEdit into a simple IDE—a way to easily test and run the code you are editing within PyEdit itself. It works for both non-Python code like HTML, as well as most types of Python programs, including tkinter GUIs, interactive scripts, and any other code that uses arguments, prints output, or reads input. Although Run Code lacks more-advanced IDE tools, this option can serve as a program launching technique that makes it unnecessary to leave PyEdit or open a command-line console window or file-explorer GUI. As examples, the command-line based mergeall and diffall data archiving programs and ziptools package scripts can be run from PyEdit's Run Code Capture mode by opening their main-script files and providing arguments. The GUI-based frigcal calendar program can similarly be run in PyEdit, in Click, Console, or Capture modes. You can also view edited HTML files in your default browser, and may even run PyEdit's own main script from a PyEdit window (both proof of concept and potential head-exploder!). The Run Code dialog's in-program Help has full details on the launching process and its available run modes, so we'll skip most of them here for space. Instead, here's an assortment of Run Code tips: Run Code Windows Like Change and Fonts, the Run Code window is a stay-up dialog: you need open just one per edit window having code you wish to run. Capture mode's code-IO windows (labeled "Streams") are per-run instead, so you can refer back to prior runs' results. Enter command-line arguments (if any) at the top of the Run Code window; enter console input (if any) in either the console or the top of the per-run window, depending on your chosen mode. On all platforms, closing the per-run streams window kills your program if it's still running—especially handy if it's stuck in a loop. Any-Code Modes Run Code's Click modes run any text file (including but not limited to Python code) via your system's file name or type associations—as though you clicked the file's icon. For example, you can quickly open a browser to view the result of an HTML file you are editing by running it this way, and can launch Python-coded GUIs that have no console IO with a locally-installed Python. On some platforms, this mode also supports sending command-line arguments to the launched code (though not on Macs), as well as popped-up consoles for IO (on Windows, whose Click+Keep mode also saves the console after the program closes). Python Modes Run Code's Click modes run your Python code using the Python you've associated with it on your computer, per the prior tip. Capture and Console modes run Python code only, but specially—the former routing console IO (if any) to PyEdit's own GUI, and the latter to PyEdit's own console (if any). Capture mode is recommended for most Python code, because it works in all cases on all platforms (even if PyEdit is run with no console), and offers more control via configurations. Unlike Console mode, Capture also can't get out of synch with input requests. Its only downsides are that it may scroll output more slowly than a console on some platforms, and creates a console IO window that may be unused for some GUIs. In exchange, Capture mode does not require a separate Python install to run your code with frozen executable PyEdits; Console mode requires a Python executable. Pythons and Paths Run Code's Capture and Console modes run your Python code with the same version of Python that is running PyEdit by default, but both modes also allow you to select an alternative, locally-installed, and preferred Python (including a Python 2.X) in your configurations file. Capture mode additionally allows you to easily and portably specify import-path extensions so your code can use local folders outside the Python standard library. These configurations are not required to use the Python's standard library or import files from your main script's folder. They're also unnecessary if you're running the source-code package, and the version of Python you use to run PyEdit suffices for running the Python code files you open in PyEdit. These settings come in handy, however, when you want to: Pick a specific version of Python to run your code, regardless of which version is running PyEdit Portably import modules or libraries located in folders other than one in which you save your main script Enable other locally-installed packages for use in code run by frozen app and executable PyEdits These configurations are especially useful in the latter role; if unset, frozen PyEdits by default run your code with a Python 3.X that has all standard libraries "baked in" but no access to local folders or installs on your computer. Naturally, these settings are used for Python code only, and do not apply to Click modes which run your Python files with the version you've associated on your system. Miscellaneous Tips Finally, the compulsory handful of odds-and-ends: In Capture mode's output window, Ctrl-C (Command-C on Macs) copies selected text, Shift-click selects regions, and Escape toggles line wrapping on and off at character boundaries. See the key bindings note above for more ideas. You can also check modules without main actions for syntax errors by running them—no output means no syntax errors. For example, you can use this to verify your edits to PyEdit's user configuration file. And for precoded examples to try out in Run Code, see the scripts in PyEdit's install folder docetc/examples/RunCode-examples. Open and run in PyEdit. Again for more Run Code usage details, be sure to also see its dialog's own in-program Help display.

Help Menu

There is just one item here, but a program's documentation is just as important as its code. PyEdit's docs come in multiple flavors—popups, dialog displays, text files, and the HTML file you're reading right now.

PyEdit Help Last but not least, the Help menu—a full menu on Mac and Linux, and a simple button on Windows—opens PyEdit's help dialog. From this dialog, you can view About—a brief overview, and Versions—short version histories, both opened as popups in the GUI itself; Readme—a text-file opened in a new PyEdit window that gives package-usage details; as well as the full User Guide—an HTML help document (this file) opened in an automatically-started web browser. Help is a non-modal (stay-up) dialog; click its Close button when you're finished browsing the documentation. Besides these, you'll also find in-program documentation for all of PyEdit's custom dialogs, in the form of a scrollable text display opened (and closed) by pressing the dialogs' Help buttons. This works for Pick Font, Change, Grep, and Run Code, and provides additional usage details we've skipped here for space. The Run Code screenshot at the Tools menu's section captures dialog help in action. Note to Mac users: You can reach the same help dialog from the About entry in your standard application (leftmost) menu introduced earlier. You also have a standard Window menu which is similarly unique to your platform; entries in Window, the application menu, and your bottom-of-screen Dock allow you to control PyEdit windows as usual for your platform, and quit the entire application immediately. As noted earlier, a Dock single click also opens a new popup edit window ready for your ideas.

Platform Pointers

This section provides install and usage details for users new to any of PyEdit's supported platforms. It's primarily intended for users of the source-code package described above, which may require extra steps. Users of the frozen app and executable packages do not need to install a Python separately and can run with a simple app or program click, but may still find some of this material useful when using a locally-installed Python for the Run Code feature.

Supported Platforms

PyEdit works and is regularly used on all reasonably-recent versions of Mac OS X (a.k.a. macOS), Windows, and Linux. Specifically, it has been verified to run on Mac OS X El Capitan and Sierra; Windows 7, 8, and 10; and Ubuntu Linux. Other flavors of these systems are expected to work as well, especially when using the source-code package. PyEdit is a true cross-platform program, that runs portably on all three of today's major desktop operating systems.

That said, some program formats are more portable than others. For example:

• The source-code package is widely portable across all flavors of Mac, Windows, and Linux, but only because it assumes and requires that a platform-specific Python is installed on the underlying computer.

• The app and executable packages are true first-class citizens on your computer, but run only on the platforms for which they are built (e.g., the Mac app won't normally run on Windows), and may have additional platform-version constraints (e.g. the Windows 64-bit executable won't run on 32-bit systems, and systems older than that on which these packages were built may not be supported).

These constraints are normal and minor, but be sure to see the README file for the full story on package portability. Although each of PyEdit's supported platforms has usage idiosyncrasies that are beyond this guide's scope, the next section goes over the basics required to use programs like PyEdit, especially when it is installed as source code.

Use the Source, Luke or Leia

As mentioned, PyEdit is shipped as both source code that you run with a locally-installed Python, and frozen programs that are self-contained. Source code is ideal for both transparency and portability, but it's also possible to build stand-alone packages. For example, PyEdit is provided as a Mac app built with py2app, and Windows and Linux executables built with PyInstaller. Apps and executables install with a simple unzip and run with a single click, so we won't say much more about them here (see their earlier coverage).

The source-code package, however, often requires additional steps. PyEdit's source-code is shipped for all platforms as a zipfile—installing the PyEdit program itself is as simple as unzipping into a folder on your machine. In addition to unzipping the package itself, though, you'll also need a Python to run it, and standard launching techniques to start it. On Mac and Linux, you may also need to install a copy of the tkinter/Tk GUI toolkit.

First off, an installed Python 3.X is required, and its most-recent version is generally recommended. More specifically, Python 3.1 through 3.5 have all been verified to run PyEdit correctly, though later 3.X are expected to work too. Except when they don't—unlike frozen apps and executables which bundle the version of Python they use, source code is prone to be affected by Python's evolution, which has a habit of breaking existing code over time. If in doubt, install a Python no newer than the latest verified here; today, that means 3.5.

Because the rest of the Python-install and program-launch story varies per platform, the following groups additional pointers by the platforms that PyEdit supports:

On Windows:

The Python self-installers for Windows from python.org ship with everything you need, including the tkinter GUI library and the Tcl/Tk libraries it uses. Get the appropriate 3.X if it's not present in your machine's Start menu or screen, and click to install.

After Python is installed, you can run a program from a Command Prompt command line (e.g., "py -3 <program> ..."); from IDLE's Run menu after opening the program's source file; and by clicking or tapping on the program's file icon in Explorer. You can also create a shortcut to the GUI's main script on your desktop for quick access (e.g., Copy + right-click). See the top-level "icons" folder for ".ico" desktop icon files to use with shortcuts.

Clicks (and taps) launch scripts without setup on Windows, because Python associates itself when installed to open script files—an automatic scheme that makes usage simple for running programs written in scripting languages and shipped as source code. Python also comes with the "py" launcher on Windows, which makes it easy to specify a version to run; see this page for an introduction. Windows also allows you to associate the pyedit.bat file at the top of your package to open all your text files in PyEdit automatically, albeit with a momentary flash; see that file for details.

On Mac OS X:

Your computer has a Python preinstalled by Apple, but at this writing it's not very recent, and its tkinter GUI library is buggy. Per the instructions here, download and click to run the latest Python 3.X self-installer for Mac from python.org, and do the same to get the recommended Tcl/Tk—which at this writing is 8.5 from ActiveState. This story is prone to change (e.g., Python might someday include the newer Tcl/Tk 8.6 for Mac as it does today for Windows), so watch python.org for details. Some Mac users might also be interested in installing both Python and Tk using the Homebrew package manager, which may offer more recent versions; see its Python page.

After the installs, you can run a program from a Terminal command line (e.g., "python3 <program> ..."); from IDLE's Run menu after opening the program's source file; by dragging the program's file icon to the Python Launcher you get with the install; or by clicking the program's file icon in Finder after associating it or its filetype with the Python Launcher using a right- (or control-) click. The Mac Python Launcher can be set to open scripts without a console; you may not want one for GUIs with no useful text output (like PyEdit). Once associated, you can also create an Alias for a script and drag it to the desktop for quick access.

On Linux:

Your machine almost certainly already has a usable Python, its tkinter GUI library, and Tcl/Tk, because they are core tools on this platform. If not, or if your versions are out of date, an "apt-get" on Ubuntu or a "yum install" on Fedora should allow you to install required packages. For instance, "sudo apt-get install python3-tk" fetches tkinter for Python 3.X on Ubuntu today. It's also straightforward to build Python from its source code on Linux, if you've ever dabbled with "configure" and "make" commands.

Once Python is verified or installed, you can run a program from a terminal command line (e.g., "python3 <program> ..."); from IDLE's Run menu after opening the program's source file; or by clicking on the program's file icon in the system's file explorer after you've configured to run in this mode.

Running by icon clicks may require giving the file executable permission with a "chmod +x <filename>" or file icon right-click; setting the file explorer's Properties to run scripts on clicks instead of opening them in a text editor; ensuring that the script's top "#!" line references your Python (see "which python3"); and converting end-lines in the file to Unix form (some may ship in Windows/DOS form—see the fixeoln.py script in the tools/ folder if you have no other converter, or simply open and save on Linux in PyEdit to force Unix end-lines).

Naturally, you may find additional install and launch schemes on each platform, but we'll cut this story short here. For more platform pointers, see your local help resources or try a web search.

Additional Tips

Run Code works too

Also keep in mind that you can run Python programs in PyEdit's own Run Code tool on all platforms, once you get PyEdit running. Simply open the file you wish to run in PyEdit and invoke Run Code's menu item, accelerator keys, or toolbar entry to start your program. This can serve as a portable alternative to the other program launch techniques described above in many or most use cases.

Consider an app or exe

For better support of file/program associations, desktop icons, and more, be sure to also consider the Mac app and the Windows and Linux executable formats of PyEdit. While they don't support program changes and run only on a single platform each, they may also be closer to what you've come to know as a "program." See the README for more details.

Handling zipfiles

Most platforms today will unzip a zipfile if you simply click it; try a right-click and extract-all, extract-to-here, or your platform's equivalent (a double-click suffices on a Mac). If your computer doesn't do unzips, check out the "zip-extract.py" script in the ziptools package—a free, portable, and Python-coded zipfile suite from PyEdit's creators that is run with simple command lines. Also on this topic: some web browsers may warn you about downloading zipfiles; zips can be a legitimate security threat, but those at PyEdit's site are not.

Windows 10 blurry text

If you use Windows 10, your system may have blurry text fonts in Tk-based programs like PyEdit—and many others—unless you install a patch to revert to Windows 8's font-scaling scheme. Though not all computers are affected, it seems universal on higher-resolution devices. You can find the fix and read about the issue in numerous place on the web. In short, Windows seems to have broken text fonts for the sake of landscape orientation in its tablet computers.

This blurring is so bad that it impacts many of Windows' own programs (Device Manager is a good test case), and some PC vendors have taken to preinstalling the suggested workaround. Until this is fixed in either Windows 10, or the legions of programs and libraries like Tk impacted by it, the widely-used workaround is a recommended antidote to Windows 10's bizarre and rude font story.

Mac OS X blurry text?

The prior note being said, it's also worth noting that Macs don't generally have this problem, though they did when retina displays were first introduced, and still may if you scale your text to be too large in your Display Preferences. If you notice blurry fonts in this program, try using a higher-resolution setting, or the default for your display.

Don't Grep in IDLE!

Source-code package users: if you launch PyEdit by opening and running its main script in Python's IDLE GUI, your options may be a bit limited. As of 3.0, PyEdit's Grep command no longer seems to work in IDLE, most likely due to Grep's shift to multiprocessing instead of threads. This isn't a problem for app and executable PyEdits, but negates a major PyEdit feature in source-code mode.

Luckily, the workaround is simple: to use its Grep, launch PyEdit instead using any other technique—by app, executable, or source-file click; from a command line; or via PyEdit's own Run Code tool. And yes, in this case PyEdit works where IDLE does not, but any broader generalizations will have to remain suggested exercise.

Recent Highlights

This section briefly summarizes recent enhancements made to PyEdit. PyEdit has evolved over multiple years (and book editions), so for space this summary is focused on changes after the latest book appearance. If you're a programmer interested in more technical details, search the program's source code for the pattern "[N.M]" where N.M is a given release's version number (e.g., "[3.0]").

Version 3.0, June 2017

This was so large an update that it probably qualifies as a new program. Its changes were too numerous to list exhaustively here, but among its highlights:

1. Ported to run with full functionality on Mac OS X, in addition to Windows and Linux
2. Now available as source, a Mac app, and Windows and Linux frozen executables
3. Run Code has become a mini-IDE, with rich and robust support for launching code
4. An auto-save feature now periodically saves your unsaved changes for recovery
5. Menus have grown accelerator key shortcuts, and support for Mac menu paradigms
6. Toolbars now have expandable spacers, and use Unicode symbols where legible
7. Fonts and colors now support configurable pick lists and automatic color cycling
8. Custom dialogs now have their own in-program help, opened by a simple button click
9. Opens now check whether a file is already open in another window and alert the user
10. Closes sharpen the check for changes anywhere, and provide an API for clients
11. The new View menu adds line-wrapping toggles and font-based zoom in/out
12. Grep searches now report statistics and use processes instead of threads for speed
13. Grep and Find/Change searches now have a case-sensitivity toggle in the GUI
14. Non-BMP Unicode characters unsupported by Tk are replaced instead of causing errors
15. The textConfig.py file allows additional appearance and behavior to be customized
16. Mac OpenDoc and ReopenApp events are handled to open files and new edit windows
17. This document was written as a new user guide, aimed at PyEdit's end-users

For more change details, search for "[3.0]" in PyEdit's source-code files.

Prior Versions, 2000-2010

Earlier versions of PyEdit appeared in the 2nd through 4th editions of the book Programming Python:

• Version 2.1 was published in 2010's 4th Edition
• Version 2.0 was published in 2006's 3rd Edition
• Version 1.0 was published in 2000's 2nd Edition

Although these early versions laid the groundwork on which 3.0 is based, they were scaled for use in a book, and their changes are too dated to cover here. For more earlier-version details, see the "Version" button in PyEdit's Help dialog, the main docstring in PyEdit's source file "textEditor.py", and older book copies on your older coworkers' shelves.

Before You Go...

If you like this program, you may also be interested in these other productivity tools brought to you by the makers of PyEdit:

frigcal	—	Personal Calendar GUI; No Login Required
mergeall	—	Backup and Mirror Your Stuff Your Way
PyMailGUI	—	Email Without the Evil

You can find these and other free software packages at the programs site.

Books

Programs

Posts

Email

© M. Lutz