{"id":2018,"library":"editor","title":"Open the default text editor","description":"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.","status":"active","version":"1.7.0","language":"en","source_language":"en","source_url":"https://github.com/rec/editor","tags":["editor","text-editor","cli","utility","environment-variable"],"install":[{"cmd":"pip install editor","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false}],"imports":[{"note":"The primary way to import the library is to import the 'editor' module itself. Functions are then accessed via `editor.edit()` or `editor.editor()`.","symbol":"editor","correct":"import editor"}],"quickstart":{"code":"import editor\nimport os\n\n# Example 1: Edit new content in a temporary file\n# The content must be a bytes object for Python 3.\ninitial_content = b\"# Enter your commit message here\\n\\n\"\ncommit_message = editor.edit(contents=initial_content)\n\nprint(f\"User entered: {commit_message.decode('utf-8')}\")\n\n# Example 2: Edit an existing file (or create a new one)\n# Ensure a dummy file exists for the example\nfile_path = \"my_document.txt\"\nwith open(file_path, \"w\") as f:\n    f.write(\"Hello, World!\\nThis is a test file.\\n\")\n\nedited_content = editor.edit(file=file_path)\n\nprint(f\"Content of {file_path} after editing: {edited_content.decode('utf-8')}\")\n\n# Clean up the dummy file\nos.remove(file_path)\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your content is encoded to bytes, e.g., `contents=b\"Your message\"` or `contents=\"Your message\".encode('utf-8')`.","message":"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`.","severity":"gotcha","affected_versions":"Python 3.x"},{"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')`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}