Open the default text editor

1.7.0 · active · verified Thu Apr 09

The 'editor' library provides a programmatic interface to open the system's default text editor from within Python scripts. It allows editing new content, existing files, or temporary files, and returns the modified content. Currently at version 1.7.0, the library is actively maintained with frequent patch releases, primarily for dependency updates and minor improvements.

Warnings

gotcha When providing initial content to the editor (via the `contents` argument), it must be a `bytes` object, not a `str`, in Python 3. Passing a string will result in a `TypeError`.
Fix: Ensure your content is encoded to bytes, e.g., `contents=b"Your message"` or `contents="Your message".encode('utf-8')`.
gotcha The specific editor launched by the library is determined by the `VISUAL` or `EDITOR` environment variables, in that order. If neither is set, it defaults to 'Notepad' on Windows and 'vim' on other operating systems. This can lead to unexpected editors opening if the environment variables are not explicitly configured.
Fix: Set the `VISUAL` or `EDITOR` environment variable to your preferred editor's command (e.g., `export EDITOR=nano` in bash) or pass the `editor` argument directly to `editor.edit(..., editor='code --wait')`.
gotcha The `editor.edit()` (or `editor.editor()`) function is blocking. It will pause the execution of your Python script until the user closes the external text editor. This behavior is by design, but developers should be aware that their application will halt during the editing session.
Fix: Design your application flow to account for the blocking nature of the editor call. If non-blocking behavior is required, consider using `subprocess` directly for background execution and handling file watching separately, or explore alternative libraries.
gotcha If no `file` argument is provided to `editor.edit()`, the library creates a temporary file. The content is written to this temporary file for editing, and once the editor is closed, the modified content is returned, and the temporary file is automatically deleted. Changes made are not persistently saved to disk unless an explicit `file` path is provided.
Fix: To save changes permanently, always specify a `file` argument: `editor.edit(file="path/to/your/file.txt")`. If you want to use a temporary file but need to save the content, capture the returned bytes and write them to your desired location.

Install

pip install editor Install stable version

Imports

editor
```
import editor
```
The primary way to import the library is to import the 'editor' module itself. Functions are then accessed via `editor.edit()` or `editor.editor()`.

Quickstart

This quickstart demonstrates how to use `editor.edit()` to open the default system editor. It shows two common use cases: editing initial content in a temporary file (which is returned and then deleted), and editing an existing file (changes are saved in place). Note that the `contents` argument requires a `bytes` object on Python 3. Both `editor.edit()` and `editor.editor()` functions are available and provide similar functionality for opening the editor.

import editor
import os

# Example 1: Edit new content in a temporary file
# The content must be a bytes object for Python 3.
initial_content = b"# Enter your commit message here\n\n"
commit_message = editor.edit(contents=initial_content)

print(f"User entered: {commit_message.decode('utf-8')}")

# Example 2: Edit an existing file (or create a new one)
# Ensure a dummy file exists for the example
file_path = "my_document.txt"
with open(file_path, "w") as f:
    f.write("Hello, World!\nThis is a test file.\n")

edited_content = editor.edit(file=file_path)

print(f"Content of {file_path} after editing: {edited_content.decode('utf-8')}")

# Clean up the dummy file
os.remove(file_path)

view raw JSON →