Download and
start source code, macOS app, and Windows executable
History:
A radically enhanced version of code that originally appeared in
PP4E
This is an online-only document to better support updates, and has been
styled for viewing on both desktop and mobile devices. Recent news:
PyEdit 4.0—This release
enhances this program in numerous ways, some of which
are noted ahead as updates. For more
about 4.0 specifically, see its release
notes and
screenshots.
PyEdit on Android—See the separate
how-to for using
PyEdit on Android
and the tips below.
In short, the PyEdit 4.0 source-code package today works unchanged on Android
in the Pydroid 3 app.
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 macOS, Windows, and Linux, per the screenshots above;
runs on Android in the Pydroid 3
app;
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 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 macOS (f.k.a. Mac OS X),
Windows, and Linux—as captured, respectively, by the three screenshots above and others
that follow. It also runs on
Android
with limited functionality.
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.
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.
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 its platform-neutral Unicode default and never ask on opens
and saves again.
The Unicode default is generally UTF-8, which includes ASCII, and should
suffice for most text files; arbitrary Unicode selection is supported for more specialized content.
There's more on PyEdit's Unicode support at the File-menu coverage
ahead.
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.
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.
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.
This section provides some practical details about the PyEdit program,
apart from the GUI itself. It covers package formats and installs,
configuration options, and auto-save files.
If you're looking for details on the GUI, see the next section.
For pointers on portability and using PyEdit on various platforms, see the
platforms section later in this document.
PyEdit is coded in Python 3.X (it's been verified most recently on Python 3.13 and
Tk 8.6.15 in PyEdit release 4.0), and works the same on
macOS (f.k.a. OS X),
Windows,
Linux, and Android,
with a different but
natural look-and-feel on each. It's distributed from
this site
as both "frozen" macOS app and Windows and Linux executables,
and complete source-code (the latter is also used on
Android).
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:
Click on the folder's app or executable to run—PyEdit.app on macOS, 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).
macOS 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 used on all platforms. To use this format:
Unzip to a folder on your computer to install PyEdit
Also install a Python 3.X to run PyEdit if one isn't already present: get Python
here
Also install a tkinter/Tk GUI toolkit if required on your platform: see details
ahead
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 the source-code package, 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.
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).
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:
Locate your auto-save folder.
Copy the save file there to its original location.
Rename the save file to negate naming-pattern additions.
To follow the above steps, you need to understand the basics of auto-save's operation,
the topic of the next section.
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 auto-save name for known files now includes both a ".txt" extension and
the process ID of the PyEdit instance:
filename--AT--directory--BY--processid.txt.
This makes saves unique when the same file is edited in multiple PyEdit instances.
The auto-save filename format for nameless windows was also modified slightly
to match: _nameless-seq--BY--processid.txt, where seq
is still a counter incremented or each edit window and New action in a PyEdit session.
The preset time to saves was also changed from 5 to 3 minutes to backup more
recent mods at a trivial cost in processing time.
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 macOS 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 ig.py.
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 macOS 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):
Your mileage will vary, but will be similar. When using source-code PyEdit,
the auto-save folder is nested in PyEdit's source folder by default; for Windows
and Linux executables, it resides in the same folder as the unzipped executable
unless you've configured your auto-save parameters. Your filenames will vary too,
but will follow the same pattern for named files, and the nameless pattern described
above for text not yet saved.
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.
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:
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.
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 macOS
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 macOS) 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 macOS, 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!).
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 macOS 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 macOS), and mouse wheels.
Finally, three quick footnotes regarding this section's upcoming screenshots:
The images
First, the three opening images in each section were captured on macOS, Window,
and Linux, respectively; click to view full-sized. Additional images are from macOS 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 macOS users: the shots here capture the frozen app in action. If you instead
run source code via the macOS 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.
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 asked if you wish to save the
window's current text if it is changed and unsaved, and a standard file-selection
dialog
for your platform will be popped up (or slid down on macOS) 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 encoding 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
PyEdit'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.
Two Unicode details here, for detail-minded users:
First of all, PyEdit's Unicode default technically comes from Python 3.X's
sys.getdefaultencoding(), not locale.getpreferredencoding().
That means the default is generally UTF-8, which supports all types
of text, and will not vary per platform. This is an intentional
feature, which makes your text files more portable: if a
platform-specific default was used instead, you'd have to remember
where a file was created in order to correctly provide its encoding on
opens elsewhere. Hence, your platform's default in PyEdit is
UTF-8—as it is on every platform. More details
here.
Secondly, 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 PyEdit'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.
Though mostly outside this guide's scope, you can also find a recent note
on handling Unicode BOMs properly in PyEdit
at this note.
BOM issues can generally be ignored by users who open and close text in PyEdit alone,
but may crop up in files saved elsewhere (and prefixed with BOMs covertly).
Beyond its Unicode support,
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 (a.k.a. instance).
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 macOS, 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.
4.0 Update
PyEdit 4.0 adds a cross-process test
for already-open files. Run on opens on every platform, this new test first verifies
with the user if any other process has the target file open.
This is most useful on Windows which lacks a usable single-instance mode,
but can also be useful on macOS where multiple PyEdit processes can be started
from command lines outside the system's UI. The former in-process
already-open test is still run, too, because it allows windows with open files to be
auto-raised and applies to all platforms when Popup or other supplemental windows are
opened. In addition, 4.0 now also runs both already-open tests when text is first
saved to a file, not just on opens.
New
Start a new file in this window. You'll be asked if you wish to save the
window's current text if it is 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 (above), the initial save of a file
prompts
you for the name of the
Unicode encoding 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 PyEdit's Unicode 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.
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;
check out the Frigcal calendar app's lower-level
coverage;
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: ✓ ☓ ☑ ☒ ☀ ☼ ☉ ★ ☆ ☞ ☜ ☯ ⚐ ♡ ☮ 重 出 ж म ä ☺.
4.0 update: PyEdit 4.0
now supports display, copy, and paste of
emojis and other non-BMP Unicode text, to the extent that they are
supported by the underlying Tk library used by tkinter. In late 2024,
emojis are fully supported on macOS, but are not yet colored on Windows and
Linux and not yet available on Android.
On macOS, pick emojis in PyEdit's Edit menu.
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 macOS
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 macOS).
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 macOS 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 macOS 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.
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.
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.
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.
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 macOS 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.
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 macOS), 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 Python's standard library modules
or import files located in your main script's folder. They're also unnecessary
if you're running the source-code PyEdit package and the version of Python you're
using 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.
To speed code startup times in standalone PyEdit apps and executable,
PyEdit 4.0's Run Code no longer "bakes in" a full
Python standard library. To gain access to more standard library modules,
as well as third-party extensions of your choosing, install a local
Python and reference it from the Run Code Python settings provided
and documented in textConfig.py.
Doing so has the added advantage of speeding code startup even further in
standalones because your code is run with a source-code script instead of
an executable that must be unpacked. When using PyEdit's source-code
package, the Python you use to launch PyEdit is used in Run Code by
default, but textConfig.py settings are still applied if set.
Miscellaneous Tips
Finally, the compulsory handful of odds-and-ends:
In Capture mode's output window,
Ctrl-C (Command-C on macOS) 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 the PyEdit install folder's path 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.
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 macOS 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 macOS 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 Windowmenu
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.
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.
PyEdit works and is regularly used on all reasonably recent versions of
macOS (a.k.a. OS X),
Windows, and
Linux. Specifically,
it has been verified to run on macOS El Capitan and later;
Windows 7, 8, 10, and 11; 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 macOS, 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 macOS 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.
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 macOS 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 macOS 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.5 through 3.13 have all been
verified to run PyEdit correctly (support for Python 3.1 through 3.4 was dropped in
PyEdit 4.0), though later Python 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.13.
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 macOS:
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 macOS 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 macOS as it does today for Windows), so watch python.org for details.
Some macOS 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 macOS
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.
Finally, here's a collection of additional hints and reminders from the
customer-support department:
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 macOS 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 macOS). 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 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 places
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.
Update: tkinter GUIs can now be deblurred with a DPI setting in programs'
properties, as covered in this
usage update.
4.0 Update
PyEdit 4.0
now automatically deblurs its GUI on Windows,
using Windows proprietary tools. User action is no longer required for this,
and deblurring is applied for both standalone executables and source-code usage.
macOS blurry text?
The prior note being said, it's also worth noting that macOS doesn'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.
This section briefly summarizes 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., "[4.0]").
A cross-process test for already-open files,
along with already-open tests for Saves
Support for both emojis and dark mode
where supported by the underlying Tk library
Automatic deblurring of the GUI on Windows for higher-resolution displays
A splash screen in the Windows executable during initial-start-up
and Run-Code pauses
In more detail, Windows deblurring replaces a former
manual step
and is applied for both source-code and executable usage,
and the new cross-process already-open test uses hidden lockfiles (with
timestamps to detect and cull zombies) and is especially useful on Windows where
Explorer clicks open new PyEdit processes (a.k.a. instances).
All already-open tests are also now run for Saves, in addition to Opens.
The new emoji support also applies to other non-BMP
Unicode text.
At present, Python 3.12 and its Tk 8.6.13 (Tk 8.6.12 on Linux) as well as the newly
released Python 3.13 and its Tk 8.6.15 support emojis on macOS, Windows, and Linux
but do not color them on Windows or Linux. These Pythons and Tks also support
dark mode on macOS but not on Windows or Linux, and the Tk 8.6.10
in today's Android Pydroid 3 app supports neither emojis nor dark mode. This is prone
to change in later Pythons and Tks for source-code users, and later Pydroid 3 releases
for Android users. Standalone PyEdit PC apps and executables embed Python and Tk
and will require rebuilds for future Tks.
This version also:
Avoids changing window size along with text size on all font changes:
picks, cycles, and zooms (now toolbar "+" and "-" on all hosts)
Redesigns the toolbar to both drop
hieroglyphics and remove rarely used items available in the program's
menus
Uses normal buttons for the toolbar on Linux instead of the
former feedback-less labels
Reformats custom dialogs' help text to word-wrap to the full
width of the dialog window in Change, Grep, Run Code, and Pick Font
Calls out Find/Change matches with underline and
bold font on all platforms and better colors on macOS, if enabled in
textConfig.py
Inserts process ID in auto-save filenames to make them unique when
more than one PyEdit instance is editing the same file
Rebuilds its macOS app and Windows executable
to use the newer Python 3.12 and Tk 8.6.13, but drops the Linux
executable due to library-skew potential; please use the source-code
package on Linux
Integrates former
patches
for Android:
simply unzip the source-code package
and open and run its textEditor.py in the Pydroid 3
app—no
patches required, but see also the Android usage notes below
Reduces Run Code code startup times in apps and executables by
no longer embedding a full Python standard library; for best results, set
your environment variables to a local Python per this
update, Run Code's in-dialog
Help, and the config file
Always uses its own icon on Windows, instead of one in a clicked
file's folder, or a blue-cloud OneDrive.ico when Explorer's "Open With" wrongly runs
the program in Windows' System32 folder (yes, really)
Accommodates non-backward-compatible changes in recent Pythons,
including error-message formatting (in Run Code) and string-escape rules (globally)
Internally uses a manual Python search to work around a hard crash
in the underlying Tk library for case-insensitive Finds when emojis are present
Please note that most screenshots in this doc reflect the 3.0 release,
and may not accurately capture 4.0. While there was only minor change to the
GUI in 4.0 (e.g., toolbar redesign), the updated Tk library that renders
the GUI does modify appearance substantially in ways that vary per platform.
For an up-to-date look at the GUI, download and run PyEdit on your devices
or see the brief 4.0 screenshot sampler.
Usage Notes
The following are additional usage notes for this release:
Source-code usage
The source-code package—useable
on all PCs and always used on Android—now requires Python 3.5 or later
(for coded f-strings), as well as an extra install of the
psutil third-party package on all platforms (for the new cross-process
already-open test). To install psutil into
your Python, try a pip3 install psutil command line (or its
py -3.12 -m pip install psutil equivalent), and visit
psutil's pages on PyPI
or the web for more info.
In addition, Python 3.12 or later and its Tk 3.6.12 or later are recommended for
best GUI rendering; older Pythons
work but may look subpar.
Standalone PyEdit apps and executables do not require a Python or psutil install because
they embed everything they need.
App/executable usage
The Windows executable
package
is a 64-bit binary that runs on both Windows 11 and 10; earlier Windows
are not vetted. The macOS app is a universal2 binary that runs natively
on Intel and Apple M chips and works on macOS Catalina (10.15) and newer. Both are
zipfiles which you download, unzip, and run. On Windows, run file "PyEdit.exe"
located in the unzip folder. On macOS, run the "PyEdit.app" unzip folder directly
and move it to "/Applications" for ease.
Both the Windows executable and macOS app may be associated to open text
files in clicks per platform conventions. In Windows Explorer, right-click a file to
associate PyEdit with a filename extension (e.g., ".py" or ".txt"). In macOS Finder,
choose PyEdit from a file's context-menu Get Info to use it to open all files with
the same extension.
Besides eliminating code patches per above, this version automatically
sizes windows to not exceed the size of the display.
This sizing is ignored for the first window when you enable the Pydroid 3
app's maximized mode (via setting "Tkinter: maximize first window" covered
here)
but is applied to all other windows in maximized mode, and all windows in
non-maximized mode, to avoid off-screen content.
You may also now run PyEdit's script from file-explorer apps and
their home-screen shortcuts by enabling the code line that begins "# [4.0] ANDROID"
near the top of textEditor.py (see docs there).
Despite this new support, usage is still
constrained on Android due to this program's multiwindow paradigm and
dependence on the Pydroid 3 app. The toolbar just fits a landscape Fold6 but may be
clipped elsewhere; some dialogs may still clip text; you must open files within PyEdit
itself instead of using it to handle file opens in explorer apps; and Linux native
file dialogs are so tedious on mobiles that the program now presets new configs to use
tkinter alternative dialogs in textConfig.py (change as desired).
Please scale expectations, and use a foldable or larger tablet for best results.
On some macOS, PyEdit's app may be stamped with a quarantine
attribute on download that impairs its ability to update content in its own folder,
which is used by default for auto-saves and more.
If you experience permission errors on macOS, try following the guidance
here
to remove the app's quarantine state. In some cases, it may help to grant
common-folder access to the app in System Preferences, Security & Privacy,
Privacy, Files and Folders; macOS should ask on first access but may not.
Lest Windows users gloat too much, it's also worth noting that unzipping this
program in C:\Program Files or its x86 sibling may similarly break
the program's same-folder updates; please install elsewhere. Windows discourages
unzips and moves to these folders today due to their constraints, but defeating
these safeguards means you won't get an auto-saves folder unless you change its
path config. For more details on
Windows install rules, see
this
coverage for an unrelated app.
There is a known and unfixable security sandboxing bug
in the macOS file dialogs used by the Tk GUI library underlying tkinter.
These dialogs are run by this program's Open and Save
actions, and Save's file dialog has been seen to intermittently crash—and
kill this program in the process. So far, these crashes have been seen only
when running the source-code package
using Tk 8.6.13 on macOS Catalina.
They may be macOS- and TK-version specific and might not impact the
macOS PyEdit app, but their elusiveness makes their exact scope unknown.
If you see a dialog crash, it may help to grant macOS Full Disk Access
to Terminal (for source) or the app, in System Preference's Security & Privacy;
this disables some macOS security steps but has not avoided crashes to date. If that
doesn't help, the workaround is to set the new UseCustomFileDialog
configs in
textConfig.py to use a simple alternative tkinter file dialog
for opens and/or saves instead of macOS's native dialogs. Be sure to also look for
your work in an auto-save folder after a crash, and bear in mind that
this macOS-only bug does not impact Windows, Android, or Linux.
Future plans a 4.1 may rebuild apps and executables with a later Python
and its later Tk for broader emoji and dark-mode support as well as Tk bug fixes; until
then, use the source-code package to leverage future upgrades. No rewrite for Android
in Kivy
(or Toga)
is scheduled at this time.
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:
Ported to run with full functionality on macOS, in addition to Windows and Linux
Now available as source, a macOS app, and Windows and Linux frozen executables
Run Code has become a mini-IDE, with rich and robust support for launching code
An auto-save feature now periodically saves your unsaved changes for recovery
Menus have grown accelerator key shortcuts, and support for macOS menu paradigms
Toolbars now have expandable spacers, and use Unicode symbols where legible
Fonts and colors now support configurable pick lists and automatic color cycling
Custom dialogs now have their own in-program help, opened by a simple button click
Opens now check whether a file is already open in another window and alert the user
Closes sharpen the check for changes anywhere, and provide an API for clients
The new View menu adds line-wrapping toggles and font-based zoom in/out
Grep searches now report statistics and use processes instead of threads for speed
Grep and Find/Change searches now have a case-sensitivity toggle in the GUI
Non-BMP Unicode characters unsupported by Tk are replaced instead of causing errors
The textConfig.py file allows additional appearance and behavior to be customized
macOS OpenDoc and ReopenApp UI events open files and new edit windows
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.
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:
![[icon]](icons/pyedit256.png){kind=icon}
![[GUI image]](docetc/docimgs/macosx/0-composite.png)
![[GUI image]](docetc/docimgs/windows/0-composite.png)
![[GUI image]](docetc/docimgs/linux/0-composite.png)
![[GUI image]](docetc/docimgs/macosx/1-filemenu.png)
![[GUI image]](docetc/docimgs/windows/1-filemenu.png)
![[GUI image]](docetc/docimgs/linux/1-filemenu.png)
![[GUI image]](docetc/docimgs/macosx/x-opendialog.png)
![[GUI image]](docetc/docimgs/macosx/x-savedialog.png)
![[GUI image]](docetc/docimgs/macosx/x-opencheck.png)
![[GUI image]](docetc/docimgs/macosx/x-closecheckall.png)
![[GUI image]](docetc/docimgs/macosx/x-closecheckone.png)
![[GUI image]](docetc/docimgs/macosx/7-macappmenu.png)
![[GUI image]](docetc/docimgs/macosx/x-unicode-text.png)
![[GUI image]](docetc/docimgs/macosx/unicode-prompts-open.png)
![[GUI image]](docetc/docimgs/macosx/unicode-prompts-save.png)
![[GUI image]](docetc/docimgs/macosx/2-editmenu.png)
![[GUI image]](docetc/docimgs/windows/2-editmenu.png)
![[GUI image]](docetc/docimgs/linux/2-editmenu.png)
![[GUI image]](docetc/docimgs/macosx/x-redoinfo.png)
![[GUI image]](docetc/docimgs/macosx/3-searchmenu.png)
![[GUI image]](docetc/docimgs/windows/3-searchmenu.png)
![[GUI image]](docetc/docimgs/linux/3-searchmenu.png)
![[GUI image]](docetc/docimgs/macosx/x-changedialog.png)
![[GUI image]](docetc/docimgs/macosx/x-grepdialog.png)
![[GUI image]](docetc/docimgs/macosx/x-grepmatches.png)
![[GUI image]](docetc/docimgs/macosx/4-viewmenu.png)
![[GUI image]](docetc/docimgs/windows/4-viewmenu.png)
![[GUI image]](docetc/docimgs/linux/4-viewmenu.png)
![[GUI image]](docetc/docimgs/macosx/x-fontdialog.png)
![[GUI image]](docetc/docimgs/macosx/x-pickcolor.png)
![[GUI image]](docetc/docimgs/macosx/5-toolsmenu.png)
![[GUI image]](docetc/docimgs/windows/5-toolsmenu.png)
![[GUI image]](docetc/docimgs/linux/5-toolsmenu.png)
![[GUI image]](docetc/docimgs/macosx/x-infodialog.png)
![[GUI image]](docetc/docimgs/macosx/x-runcodedialog.png)
![[GUI image]](docetc/docimgs/macosx/x-runcodestreams.png)
![[GUI image]](docetc/docimgs/macosx/x-runcodedialoghelp.png)
![[GUI image]](docetc/docimgs/macosx/x-runcode-compos.png)
![[GUI image]](docetc/docimgs/macosx/6-helpmenu.png)
![[GUI image]](docetc/docimgs/windows/6-helpmenu.png)
![[GUI image]](docetc/docimgs/linux/6-helpmenu.png)
![[GUI image]](docetc/docimgs/macosx/x-help.png)
![[Python Logo]](docetc/docimgs/PythonPowered.gif){kind=small}