launch-editor-py 1.0.0__tar.gz

launch_editor_py-1.0.0/LICENSE

@@ -0,0 +1,34 @@
+MIT License
+
+Copyright (c) 2026 Adam Johnson
+Copyright (c) 2017-present, Yuxi (Evan) You
+Copyright (c) 2015-present, Facebook, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This package is a Python port of the launch-editor npm package:
+https://github.com/vitejs/launch-editor
+
+launch-editor is Copyright (c) 2017-present, Yuxi (Evan) You, and released
+under the MIT License. Its main module is derived from code in
+create-react-app, Copyright (c) 2015-present, Facebook, Inc., also released
+under the MIT License:
+https://github.com/facebook/create-react-app

launch_editor_py-1.0.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: launch-editor-py
+Version: 1.0.0
+Summary: Open files in the user’s editor, optionally at a given line and column.
+Keywords: editor,launch-editor,open-in-editor
+Author: Adam Johnson
+Author-email: Adam Johnson <me@adamj.eu>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Project-URL: Changelog, https://github.com/adamchainz/launch-editor-py/blob/main/CHANGELOG.rst
+Project-URL: Funding, https://adamj.eu/books/
+Project-URL: Repository, https://github.com/adamchainz/launch-editor-py
+Description-Content-Type: text/x-rst
+
+================
+launch-editor-py
+================
+
+.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/launch-editor-py/main.yml.svg?branch=main&style=for-the-badge
+   :target: https://github.com/adamchainz/launch-editor-py/actions?workflow=CI
+
+.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge
+   :target: https://github.com/adamchainz/launch-editor-py/actions?workflow=CI
+
+.. image:: https://img.shields.io/pypi/v/launch-editor-py.svg?style=for-the-badge
+   :target: https://pypi.org/project/launch-editor-py/
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
+   :target: https://github.com/psf/black
+
+.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
+   :target: https://github.com/pre-commit/pre-commit
+   :alt: pre-commit
+
+----
+
+Open files in the user’s editor, optionally at a given line and column.
+
+A Python port of the `launch-editor <https://github.com/vitejs/launch-editor>`__ npm package, as used by Vite to open files from the browser.
+It detects which editor is running, and knows how to pass a line and column to many editors.
+
+----
+
+**Get better at command line Git** with my book `Boost Your Git DX <https://adamchainz.gumroad.com/l/bygdx>`__.
+
+----
+
+Requirements
+------------
+
+Python 3.11 to 3.15 supported.
+
+Installation
+------------
+
+1. Install with **pip**:
+
+   .. code-block:: sh
+
+       python -m pip install launch-editor-py
+
+   The package imports as ``launch_editor``.
+
+Usage
+-----
+
+Call ``launch_editor()`` with a filename, and optionally a line and column:
+
+.. code-block:: python
+
+    from launch_editor import LaunchEditorError, launch_editor
+
+    try:
+        launch_editor("src/example.py", line=12, column=4)
+    except LaunchEditorError as exc:
+        print(f"Could not open editor: {exc}")
+
+API
+---
+
+``launch_editor(filename, line=None, column=None, *, editor=None)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Open ``filename`` in the user’s editor, at ``line`` and ``column`` if given, and return the editor’s ``subprocess.Popen`` object.
+
+The editor is picked by ``guess_editor()``, passing it ``editor``.
+
+GUI editors start in the background, and the function returns immediately.
+If a GUI editor exits with an error, a warning is logged to the ``launch_editor`` logger.
+
+Terminal editors, like Vim, take over the current terminal until they exit.
+While one is open, further attempts to open a terminal editor raise ``LaunchEditorError``.
+
+Raises ``LaunchEditorError`` if the file does not exist, no editor is found, or the editor cannot be run.
+
+``guess_editor(editor=None)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Return the command for the user’s editor, as a list of strings, or an empty list if none is found.
+The editor is chosen from, in order:
+
+1. The ``editor`` argument, as a command string like ``"code --new-window"`` or a list of arguments.
+2. The ``LAUNCH_EDITOR`` environment variable.
+3. A supported editor that is currently running, on macOS, Linux, and Windows.
+4. The ``VISUAL`` environment variable.
+5. The ``EDITOR`` environment variable.
+
+``LAUNCH_EDITOR`` is shared with the launch-editor npm package, so you can set it once for both.
+Like there, it’s treated as a single command, not split into arguments.
+It may name a script, which is passed the file, line, and column as separate arguments, unless it’s a supported editor.
+
+``position_args(editor, filename, line, column=None)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Return the arguments that open ``filename`` at ``line`` and ``column`` in the given ``editor`` command.
+Unsupported editors get only the filename, since passing a position incorrectly can cause errors or confusing behaviour.
+
+``LaunchEditorError``
+~~~~~~~~~~~~~~~~~~~~~
+
+A basic exception subclass, raised when the editor cannot be launched.
+
+Supported editors
+-----------------
+
+Opening at a line and column is supported for:
+
+* VS Code and its forks: Antigravity, Cursor, Trae, VSCodium
+* JetBrains IDEs: AppCode, CLion, GoLand, IntelliJ IDEA, PhpStorm, PyCharm, Rider, RubyMine, WebStorm
+* Atom, Emacs, Helix, joe, micro, nano, Neovim, Notepad++, Sublime Text, TextMate, Vim, Zed
+
+Command line
+------------
+
+Run ``python -m launch_editor`` to open a file from the command line, or check which editor would be used:
+
+.. code-block:: console
+
+    $ python -m launch_editor --guess
+    code
+    $ python -m launch_editor src/example.py:12:4
+
+Full help:
+
+.. [[[cog
+.. import cog
+.. import os
+.. import subprocess
+.. import sys
+.. result = subprocess.run(
+..     [sys.executable, "-m", "launch_editor", "--help"],
+..     capture_output=True,
+..     text=True,
+..     env={**os.environ, "COLUMNS": "80"},
+.. )
+.. cog.outl("")
+.. cog.outl(".. code-block:: console")
+.. cog.outl("")
+.. for line in result.stdout.splitlines():
+..     if line.strip() == "":
+..         cog.outl("")
+..     else:
+..         cog.outl("   " + line.rstrip())
+.. cog.outl("")
+.. ]]]
+
+.. code-block:: console
+
+   usage: python -m launch_editor [-h] [--editor EDITOR] [--guess] [FILE]
+
+   Open a file in your editor.
+
+   positional arguments:
+     FILE             The file to open, optionally followed by :LINE or
+                      :LINE:COLUMN, like example.py:12:4.
+
+   options:
+     -h, --help       show this help message and exit
+     --editor EDITOR  The editor command to use, instead of guessing.
+     --guess          Print the editor command that would be used, and exit.
+
+.. [[[end]]]
+
+Security
+--------
+
+Web applications often use this package to open files from a browser, via an endpoint on a local development server.
+Such an endpoint runs a program, so protect it:
+
+* Accept an identifier for a file the application already knows about, rather than an arbitrary path.
+
+* Only accept POST requests, and check the ``Sec-Fetch-Site`` and ``Origin`` headers to reject cross-origin requests.
+  Any website the user visits can send requests to ``localhost``.
+
+* Check the ``Host`` header is a local name, like ``localhost`` or ``127.0.0.1``, to prevent DNS rebinding attacks.
+
+Filenames are passed to editors as absolute paths, so a name starting with ``-`` cannot be interpreted as an option.
+
+On Windows, editors launched through batch files, such as VS Code’s ``code.cmd``, run through ``cmd.exe``, which has its own command line parsing.
+To prevent command injection, launch-editor-py quotes every argument and refuses to pass arguments containing ``"``, ``%``, ``!``, or line breaks to them.
+UNC paths are also refused on Windows, like the npm package, to avoid leaking NTLM credentials to remote hosts—see `its explanation <https://github.com/vitejs/launch-editor/tree/main/packages/launch-editor#unc-paths-on-windows>`__.
+
+Differences from the launch-editor npm package
+----------------------------------------------
+
+This package was last compared against the npm package at version `2.14.2 <https://github.com/vitejs/launch-editor/tree/v2.14.2>`__ (commit ``b533489``), on 2026-10-28.
+Upstream ``main`` had no further changes to the package at that time.
+
+It also includes the fix from upstream `PR #163 <https://github.com/vitejs/launch-editor/pull/163>`__, unmerged at that time, so Cursor, Trae, and Antigravity open at the given line and column when detected running on Windows.
+
+Additions:
+
+* Opening at a line and column for Helix (``hx``), micro, nano, Neovim (``nvim``), and vi.
+
+* Helix, micro, Neovim, and vi are treated as terminal editors, alongside Emacs, nano, and Vim.
+
+* A command line interface, ``python -m launch_editor``.
+
+Changes:
+
+* Errors raise ``LaunchEditorError``, rather than calling an error callback and printing to the console.
+  A missing file is an error, rather than being silently ignored.
+  A GUI editor that exits with an error logs a warning to the ``launch_editor`` logger.
+
+* ``launch_editor()`` takes the line and column as separate arguments, rather than parsing them from ``file:line:column``.
+  The command line interface still accepts ``file:line:column``, but not ``file://`` URLs.
+
+* Opening a terminal editor while one is already open raises an error, rather than killing the open editor.
+
+* ``VISUAL`` and ``EDITOR`` are split into arguments, so values like ``code --wait`` work.
+  ``LAUNCH_EDITOR`` is still treated as a single command, like the npm package.
+
+* On Linux, running editors are detected by exact process name, rather than by substring, so for example ``nvim`` isn’t detected as ``vim``.
+
+* On Windows, editor executables are run directly, rather than through ``cmd.exe``.
+  Batch file editors, like VS Code’s ``code.cmd``, are still run through ``cmd.exe``, with every argument quoted, rather than escaped with ``^``.
+  Arguments containing ``"``, ``%``, ``!``, or line breaks are refused for them, where the npm package refuses only ``%`` and line breaks.
+
+* There’s no special handling for StackBlitz WebContainers.
+
+License
+-------
+
+MIT.
+This package is a port of the launch-editor npm package, Copyright (c) 2017-present Yuxi (Evan) You, which in turn derives from code in create-react-app, Copyright (c) 2015-present Facebook, Inc., both MIT licensed.
+See the ``LICENSE`` file for details.

launch_editor_py-1.0.0/README.rst

@@ -0,0 +1,232 @@
+================
+launch-editor-py
+================
+
+.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/launch-editor-py/main.yml.svg?branch=main&style=for-the-badge
+   :target: https://github.com/adamchainz/launch-editor-py/actions?workflow=CI
+
+.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge
+   :target: https://github.com/adamchainz/launch-editor-py/actions?workflow=CI
+
+.. image:: https://img.shields.io/pypi/v/launch-editor-py.svg?style=for-the-badge
+   :target: https://pypi.org/project/launch-editor-py/
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
+   :target: https://github.com/psf/black
+
+.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
+   :target: https://github.com/pre-commit/pre-commit
+   :alt: pre-commit
+
+----
+
+Open files in the user’s editor, optionally at a given line and column.
+
+A Python port of the `launch-editor <https://github.com/vitejs/launch-editor>`__ npm package, as used by Vite to open files from the browser.
+It detects which editor is running, and knows how to pass a line and column to many editors.
+
+----
+
+**Get better at command line Git** with my book `Boost Your Git DX <https://adamchainz.gumroad.com/l/bygdx>`__.
+
+----
+
+Requirements
+------------
+
+Python 3.11 to 3.15 supported.
+
+Installation
+------------
+
+1. Install with **pip**:
+
+   .. code-block:: sh
+
+       python -m pip install launch-editor-py
+
+   The package imports as ``launch_editor``.
+
+Usage
+-----
+
+Call ``launch_editor()`` with a filename, and optionally a line and column:
+
+.. code-block:: python
+
+    from launch_editor import LaunchEditorError, launch_editor
+
+    try:
+        launch_editor("src/example.py", line=12, column=4)
+    except LaunchEditorError as exc:
+        print(f"Could not open editor: {exc}")
+
+API
+---
+
+``launch_editor(filename, line=None, column=None, *, editor=None)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Open ``filename`` in the user’s editor, at ``line`` and ``column`` if given, and return the editor’s ``subprocess.Popen`` object.
+
+The editor is picked by ``guess_editor()``, passing it ``editor``.
+
+GUI editors start in the background, and the function returns immediately.
+If a GUI editor exits with an error, a warning is logged to the ``launch_editor`` logger.
+
+Terminal editors, like Vim, take over the current terminal until they exit.
+While one is open, further attempts to open a terminal editor raise ``LaunchEditorError``.
+
+Raises ``LaunchEditorError`` if the file does not exist, no editor is found, or the editor cannot be run.
+
+``guess_editor(editor=None)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Return the command for the user’s editor, as a list of strings, or an empty list if none is found.
+The editor is chosen from, in order:
+
+1. The ``editor`` argument, as a command string like ``"code --new-window"`` or a list of arguments.
+2. The ``LAUNCH_EDITOR`` environment variable.
+3. A supported editor that is currently running, on macOS, Linux, and Windows.
+4. The ``VISUAL`` environment variable.
+5. The ``EDITOR`` environment variable.
+
+``LAUNCH_EDITOR`` is shared with the launch-editor npm package, so you can set it once for both.
+Like there, it’s treated as a single command, not split into arguments.
+It may name a script, which is passed the file, line, and column as separate arguments, unless it’s a supported editor.
+
+``position_args(editor, filename, line, column=None)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Return the arguments that open ``filename`` at ``line`` and ``column`` in the given ``editor`` command.
+Unsupported editors get only the filename, since passing a position incorrectly can cause errors or confusing behaviour.
+
+``LaunchEditorError``
+~~~~~~~~~~~~~~~~~~~~~
+
+A basic exception subclass, raised when the editor cannot be launched.
+
+Supported editors
+-----------------
+
+Opening at a line and column is supported for:
+
+* VS Code and its forks: Antigravity, Cursor, Trae, VSCodium
+* JetBrains IDEs: AppCode, CLion, GoLand, IntelliJ IDEA, PhpStorm, PyCharm, Rider, RubyMine, WebStorm
+* Atom, Emacs, Helix, joe, micro, nano, Neovim, Notepad++, Sublime Text, TextMate, Vim, Zed
+
+Command line
+------------
+
+Run ``python -m launch_editor`` to open a file from the command line, or check which editor would be used:
+
+.. code-block:: console
+
+    $ python -m launch_editor --guess
+    code
+    $ python -m launch_editor src/example.py:12:4
+
+Full help:
+
+.. [[[cog
+.. import cog
+.. import os
+.. import subprocess
+.. import sys
+.. result = subprocess.run(
+..     [sys.executable, "-m", "launch_editor", "--help"],
+..     capture_output=True,
+..     text=True,
+..     env={**os.environ, "COLUMNS": "80"},
+.. )
+.. cog.outl("")
+.. cog.outl(".. code-block:: console")
+.. cog.outl("")
+.. for line in result.stdout.splitlines():
+..     if line.strip() == "":
+..         cog.outl("")
+..     else:
+..         cog.outl("   " + line.rstrip())
+.. cog.outl("")
+.. ]]]
+
+.. code-block:: console
+
+   usage: python -m launch_editor [-h] [--editor EDITOR] [--guess] [FILE]
+
+   Open a file in your editor.
+
+   positional arguments:
+     FILE             The file to open, optionally followed by :LINE or
+                      :LINE:COLUMN, like example.py:12:4.
+
+   options:
+     -h, --help       show this help message and exit
+     --editor EDITOR  The editor command to use, instead of guessing.
+     --guess          Print the editor command that would be used, and exit.
+
+.. [[[end]]]
+
+Security
+--------
+
+Web applications often use this package to open files from a browser, via an endpoint on a local development server.
+Such an endpoint runs a program, so protect it:
+
+* Accept an identifier for a file the application already knows about, rather than an arbitrary path.
+
+* Only accept POST requests, and check the ``Sec-Fetch-Site`` and ``Origin`` headers to reject cross-origin requests.
+  Any website the user visits can send requests to ``localhost``.
+
+* Check the ``Host`` header is a local name, like ``localhost`` or ``127.0.0.1``, to prevent DNS rebinding attacks.
+
+Filenames are passed to editors as absolute paths, so a name starting with ``-`` cannot be interpreted as an option.
+
+On Windows, editors launched through batch files, such as VS Code’s ``code.cmd``, run through ``cmd.exe``, which has its own command line parsing.
+To prevent command injection, launch-editor-py quotes every argument and refuses to pass arguments containing ``"``, ``%``, ``!``, or line breaks to them.
+UNC paths are also refused on Windows, like the npm package, to avoid leaking NTLM credentials to remote hosts—see `its explanation <https://github.com/vitejs/launch-editor/tree/main/packages/launch-editor#unc-paths-on-windows>`__.
+
+Differences from the launch-editor npm package
+----------------------------------------------
+
+This package was last compared against the npm package at version `2.14.2 <https://github.com/vitejs/launch-editor/tree/v2.14.2>`__ (commit ``b533489``), on 2026-10-28.
+Upstream ``main`` had no further changes to the package at that time.
+
+It also includes the fix from upstream `PR #163 <https://github.com/vitejs/launch-editor/pull/163>`__, unmerged at that time, so Cursor, Trae, and Antigravity open at the given line and column when detected running on Windows.
+
+Additions:
+
+* Opening at a line and column for Helix (``hx``), micro, nano, Neovim (``nvim``), and vi.
+
+* Helix, micro, Neovim, and vi are treated as terminal editors, alongside Emacs, nano, and Vim.
+
+* A command line interface, ``python -m launch_editor``.
+
+Changes:
+
+* Errors raise ``LaunchEditorError``, rather than calling an error callback and printing to the console.
+  A missing file is an error, rather than being silently ignored.
+  A GUI editor that exits with an error logs a warning to the ``launch_editor`` logger.
+
+* ``launch_editor()`` takes the line and column as separate arguments, rather than parsing them from ``file:line:column``.
+  The command line interface still accepts ``file:line:column``, but not ``file://`` URLs.
+
+* Opening a terminal editor while one is already open raises an error, rather than killing the open editor.
+
+* ``VISUAL`` and ``EDITOR`` are split into arguments, so values like ``code --wait`` work.
+  ``LAUNCH_EDITOR`` is still treated as a single command, like the npm package.
+
+* On Linux, running editors are detected by exact process name, rather than by substring, so for example ``nvim`` isn’t detected as ``vim``.
+
+* On Windows, editor executables are run directly, rather than through ``cmd.exe``.
+  Batch file editors, like VS Code’s ``code.cmd``, are still run through ``cmd.exe``, with every argument quoted, rather than escaped with ``^``.
+  Arguments containing ``"``, ``%``, ``!``, or line breaks are refused for them, where the npm package refuses only ``%`` and line breaks.
+
+* There’s no special handling for StackBlitz WebContainers.
+
+License
+-------
+
+MIT.
+This package is a port of the launch-editor npm package, Copyright (c) 2017-present Yuxi (Evan) You, which in turn derives from code in create-react-app, Copyright (c) 2015-present Facebook, Inc., both MIT licensed.
+See the ``LICENSE`` file for details.

launch_editor_py-1.0.0/pyproject.toml

@@ -0,0 +1,117 @@
+[build-system]
+build-backend = "uv_build"
+requires = ["uv-build>=0.12.1,<0.13"]
+
+[project]
+name = "launch-editor-py"
+version = "1.0.0"
+description = "Open files in the user’s editor, optionally at a given line and column."
+readme = "README.rst"
+keywords = [
+    "editor",
+    "launch-editor",
+    "open-in-editor",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "Adam Johnson"
+email = "me@adamj.eu"
+
+[project.urls]
+Changelog = "https://github.com/adamchainz/launch-editor-py/blob/main/CHANGELOG.rst"
+Funding = "https://adamj.eu/books/"
+Repository = "https://github.com/adamchainz/launch-editor-py"
+
+[dependency-groups]
+test = [
+    "cogapp>=3.6",
+    "coverage[toml]>=7.10",
+    "pytest>=9",
+    "pytest-randomly",
+]
+
+[tool.uv.build-backend]
+module-name = "launch_editor"
+
+[tool.ruff.lint]
+select = [
+    "B",
+    "C4",
+    "E",
+    "F",
+    "I",
+    "SIM",
+    "TID",
+    "UP",
+    "W",
+]
+ignore = [
+    "B9",
+    "E501",
+    "SIM105",
+    "SIM108",
+]
+extend-safe-fixes = ["UP006"]
+
+[tool.ruff.lint.isort]
+required-imports = ["from __future__ import annotations"]
+
+[tool.pyproject-fmt]
+max_supported_python = "3.15"
+
+[tool.mypy]
+mypy_path = "src/"
+namespace_packages = false
+warn_unreachable = true
+enable_error_code = [
+    "ignore-without-code",
+    "redundant-expr",
+    "truthy-bool",
+]
+strict = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+allow_untyped_defs = true
+
+[tool.pytest]
+strict = true
+
+[tool.coverage.run]
+source = [
+    "launch_editor",
+    "tests",
+]
+branch = true
+data_file = ".coverage/cov"
+parallel = true
+
+[tool.coverage.paths]
+source = [
+    "src",
+    ".tox/**/site-packages",
+]
+
+[tool.coverage.report]
+skip_covered = true
+skip_empty = true
+show_missing = true
+
+[tool.rstcheck]
+report_level = "ERROR"

launch_editor_py-1.0.0/pyproject.toml.orig

@@ -0,0 +1,123 @@
+[build-system]
+build-backend = "uv_build"
+requires = [
+  "uv-build>=0.12.1,<0.13",
+]
+
+[project]
+name = "launch-editor-py"
+version = "1.0.0"
+description = "Open files in the user’s editor, optionally at a given line and column."
+readme = "README.rst"
+keywords = [
+  "editor",
+  "launch-editor",
+  "open-in-editor",
+]
+license = "MIT"
+license-files = [ "LICENSE" ]
+authors = [
+  { name = "Adam Johnson", email = "me@adamj.eu" },
+]
+requires-python = ">=3.11"
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Natural Language :: English",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Typing :: Typed",
+]
+urls.Changelog = "https://github.com/adamchainz/launch-editor-py/blob/main/CHANGELOG.rst"
+urls.Funding = "https://adamj.eu/books/"
+urls.Repository = "https://github.com/adamchainz/launch-editor-py"
+
+[dependency-groups]
+test = [
+  "cogapp>=3.6",
+  "coverage[toml]>=7.10",
+  "pytest>=9",
+  "pytest-randomly",
+]
+
+[tool.uv]
+build-backend.module-name = "launch_editor"
+
+[tool.ruff]
+lint.select = [
+  # flake8-bugbear
+  "B",
+  # flake8-comprehensions
+  "C4",
+  # pycodestyle
+  "E",
+  # Pyflakes errors
+  "F",
+  # isort
+  "I",
+  # flake8-simplify
+  "SIM",
+  # flake8-tidy-imports
+  "TID",
+  # pyupgrade
+  "UP",
+  # Pyflakes warnings
+  "W",
+]
+lint.ignore = [
+  # flake8-bugbear opinionated rules
+  "B9",
+  # line-too-long
+  "E501",
+  # suppressible-exception
+  "SIM105",
+  # if-else-block-instead-of-if-exp
+  "SIM108",
+]
+lint.extend-safe-fixes = [
+  # non-pep585-annotation
+  "UP006",
+]
+lint.isort.required-imports = [ "from __future__ import annotations" ]
+
+[tool.pyproject-fmt]
+max_supported_python = "3.15"
+
+[tool.mypy]
+mypy_path = "src/"
+namespace_packages = false
+warn_unreachable = true
+enable_error_code = [
+  "ignore-without-code",
+  "redundant-expr",
+  "truthy-bool",
+]
+strict = true
+overrides = [ { module = "tests.*", allow_untyped_defs = true } ]
+
+[tool.pytest]
+strict = true
+
+[tool.coverage]
+run.source = [
+  "launch_editor",
+  "tests",
+]
+run.branch = true
+run.data_file = ".coverage/cov"
+run.parallel = true
+paths.source = [
+  "src",
+  ".tox/**/site-packages",
+]
+report.skip_covered = true
+report.skip_empty = true
+report.show_missing = true
+
+[tool.rstcheck]
+report_level = "ERROR"

launch_editor_py-1.0.0/src/launch_editor/__init__.py

@@ -0,0 +1,535 @@
+"""
+Open files in the user’s editor, at a given line and column.
+
+A Python port of the launch-editor npm package:
+https://github.com/vitejs/launch-editor
+
+Last compared against version 2.14.2. See “Differences from the npm package”
+in README.rst for the upstream PRs included and other changes.
+
+Copyright (c) 2026 Adam Johnson
+Copyright (c) 2017-present, Yuxi (Evan) You
+Copyright (c) 2015-present, Facebook, Inc.
+
+Released under the MIT License, see the LICENSE file.
+"""
+
+from __future__ import annotations
+
+import logging
+import ntpath
+import os
+import platform
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import threading
+from collections.abc import Sequence
+from pathlib import Path, PureWindowsPath
+
+__all__ = [
+    "LaunchEditorError",
+    "guess_editor",
+    "launch_editor",
+    "position_args",
+]
+
+logger = logging.getLogger(__name__)
+
+
+class LaunchEditorError(Exception):
+    """
+    Raised when the editor cannot be launched.
+    """
+
+
+# Process names, as listed by `ps` on macOS, mapped to the command that opens
+# files in that editor. Where there’s no command-line launcher, the process
+# path maps to itself.
+MACOS_EDITORS = {
+    "/Applications/Atom.app/Contents/MacOS/Atom": "atom",
+    "/Applications/Atom Beta.app/Contents/MacOS/Atom Beta": (
+        "/Applications/Atom Beta.app/Contents/MacOS/Atom Beta"
+    ),
+    "/Applications/Brackets.app/Contents/MacOS/Brackets": "brackets",
+    "/Applications/Sublime Text.app/Contents/MacOS/Sublime Text": (
+        "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl"
+    ),
+    "/Applications/Sublime Text.app/Contents/MacOS/sublime_text": (
+        "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl"
+    ),
+    "/Applications/Sublime Text 2.app/Contents/MacOS/Sublime Text 2": (
+        "/Applications/Sublime Text 2.app/Contents/SharedSupport/bin/subl"
+    ),
+    "/Applications/Sublime Text Dev.app/Contents/MacOS/Sublime Text": (
+        "/Applications/Sublime Text Dev.app/Contents/SharedSupport/bin/subl"
+    ),
+    "/Applications/Visual Studio Code.app/Contents/MacOS/Code": "code",
+    "/Applications/Visual Studio Code.app/Contents/MacOS/Electron": "code",
+    "/Applications/Visual Studio Code - Insiders.app/Contents/MacOS/Code - Insiders": (
+        "code-insiders"
+    ),
+    "/Applications/Visual Studio Code - Insiders.app/Contents/MacOS/Electron": (
+        "code-insiders"
+    ),
+    "/Applications/VSCodium.app/Contents/MacOS/Electron": "codium",
+    "/Applications/Cursor.app/Contents/MacOS/Cursor": "cursor",
+    "/Applications/Trae.app/Contents/MacOS/Electron": "trae",
+    "/Applications/Antigravity.app/Contents/MacOS/Electron": "antigravity",
+    "/Applications/AppCode.app/Contents/MacOS/appcode": (
+        "/Applications/AppCode.app/Contents/MacOS/appcode"
+    ),
+    "/Applications/CLion.app/Contents/MacOS/clion": (
+        "/Applications/CLion.app/Contents/MacOS/clion"
+    ),
+    "/Applications/IntelliJ IDEA.app/Contents/MacOS/idea": (
+        "/Applications/IntelliJ IDEA.app/Contents/MacOS/idea"
+    ),
+    "/Applications/IntelliJ IDEA Ultimate.app/Contents/MacOS/idea": (
+        "/Applications/IntelliJ IDEA Ultimate.app/Contents/MacOS/idea"
+    ),
+    "/Applications/IntelliJ IDEA Community Edition.app/Contents/MacOS/idea": (
+        "/Applications/IntelliJ IDEA Community Edition.app/Contents/MacOS/idea"
+    ),
+    "/Applications/PhpStorm.app/Contents/MacOS/phpstorm": (
+        "/Applications/PhpStorm.app/Contents/MacOS/phpstorm"
+    ),
+    "/Applications/PyCharm.app/Contents/MacOS/pycharm": (
+        "/Applications/PyCharm.app/Contents/MacOS/pycharm"
+    ),
+    "/Applications/PyCharm CE.app/Contents/MacOS/pycharm": (
+        "/Applications/PyCharm CE.app/Contents/MacOS/pycharm"
+    ),
+    "/Applications/RubyMine.app/Contents/MacOS/rubymine": (
+        "/Applications/RubyMine.app/Contents/MacOS/rubymine"
+    ),
+    "/Applications/WebStorm.app/Contents/MacOS/webstorm": (
+        "/Applications/WebStorm.app/Contents/MacOS/webstorm"
+    ),
+    "/Applications/MacVim.app/Contents/MacOS/MacVim": "mvim",
+    "/Applications/GoLand.app/Contents/MacOS/goland": (
+        "/Applications/GoLand.app/Contents/MacOS/goland"
+    ),
+    "/Applications/Rider.app/Contents/MacOS/rider": (
+        "/Applications/Rider.app/Contents/MacOS/rider"
+    ),
+    "/Applications/Zed.app/Contents/MacOS/zed": "zed",
+}
+
+# Process names, as listed by `ps` on Linux, mapped to the command that opens
+# files in that editor. Order matters: earlier entries take precedence.
+LINUX_EDITORS = {
+    "atom": "atom",
+    "Brackets": "brackets",
+    "code-insiders": "code-insiders",
+    "code": "code",
+    "vscodium": "vscodium",
+    "codium": "codium",
+    "cursor": "cursor",
+    "trae": "trae",
+    "antigravity": "antigravity",
+    "emacs": "emacs",
+    "gvim": "gvim",
+    "idea": "idea",
+    "idea.sh": "idea",
+    "phpstorm": "phpstorm",
+    "phpstorm.sh": "phpstorm",
+    "pycharm": "pycharm",
+    "pycharm.sh": "pycharm",
+    "rubymine": "rubymine",
+    "rubymine.sh": "rubymine",
+    "sublime_text": "subl",
+    "vim": "vim",
+    "webstorm": "webstorm",
+    "webstorm.sh": "webstorm",
+    "goland": "goland",
+    "goland.sh": "goland",
+    "rider": "rider",
+    "rider.sh": "rider",
+    "zed": "zed",
+}
+
+# Executable names of editors on Windows. A running one is launched by its
+# full path.
+WINDOWS_EDITORS = [
+    "Brackets.exe",
+    "Code.exe",
+    "Code - Insiders.exe",
+    "VSCodium.exe",
+    "Cursor.exe",
+    "atom.exe",
+    "sublime_text.exe",
+    "notepad++.exe",
+    "clion.exe",
+    "clion64.exe",
+    "idea.exe",
+    "idea64.exe",
+    "phpstorm.exe",
+    "phpstorm64.exe",
+    "pycharm.exe",
+    "pycharm64.exe",
+    "rubymine.exe",
+    "rubymine64.exe",
+    "webstorm.exe",
+    "webstorm64.exe",
+    "goland.exe",
+    "goland64.exe",
+    "rider.exe",
+    "rider64.exe",
+    "Trae.exe",
+    "zed.exe",
+    "Antigravity.exe",
+]
+
+# Editors that run in the terminal, taking it over until they exit.
+TERMINAL_EDITORS = {"emacs", "hx", "micro", "nano", "nvim", "vi", "vim"}
+
+
+def guess_editor(editor: str | Sequence[str] | None = None) -> list[str]:
+    """
+    Return the command for the user’s editor, or an empty list if none is
+    found.
+
+    The editor is chosen from, in order:
+
+    1. The ``editor`` argument.
+    2. The ``LAUNCH_EDITOR`` environment variable.
+    3. A supported editor that is currently running.
+    4. The ``VISUAL`` environment variable.
+    5. The ``EDITOR`` environment variable.
+    """
+    if editor:
+        if isinstance(editor, str):
+            return _split_command(editor)
+        return list(editor)
+
+    launch_editor_env = os.environ.get("LAUNCH_EDITOR")
+    if launch_editor_env:
+        # Like the npm package, treat this as a single command, which is often
+        # a script that receives the file, line, and column.
+        return [launch_editor_env]
+
+    running = _guess_running_editor()
+    if running is not None:
+        return [running]
+
+    for var in ("VISUAL", "EDITOR"):
+        value = os.environ.get(var)
+        if value:
+            return _split_command(value)
+
+    return []
+
+
+def _split_command(command: str) -> list[str]:
+    return shlex.split(command, posix=(sys.platform != "win32"))
+
+
+def _guess_running_editor() -> str | None:
+    if sys.platform == "darwin":
+        args = ["ps", "x", "-o", "comm="]
+        parse = _editor_from_macos_processes
+    elif sys.platform == "win32":
+        args = [
+            "powershell",
+            "-NoProfile",
+            "-Command",
+            (
+                "[Console]::OutputEncoding=[Text.Encoding]::UTF8;"
+                + "Get-CimInstance -Query "
+                + '"select executablepath from win32_process '
+                + 'where executablepath is not null" '
+                + "| % { $_.ExecutablePath }"
+            ),
+        ]
+        parse = _editor_from_windows_processes
+    elif sys.platform == "linux":
+        args = ["ps", "x", "--no-heading", "-o", "comm", "--sort=comm"]
+        parse = _editor_from_linux_processes
+    else:
+        return None
+
+    try:
+        output = subprocess.run(
+            args,
+            stdin=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            encoding="utf-8",
+            errors="replace",
+            check=True,
+        ).stdout
+    except (OSError, subprocess.CalledProcessError):
+        return None
+
+    return parse(output)
+
+
+def _editor_from_macos_processes(output: str) -> str | None:
+    processes = output.splitlines()
+    for process_name, command in MACOS_EDITORS.items():
+        if process_name in processes:
+            return command
+        # Find editors installed outside /Applications.
+        suffix = process_name.removeprefix("/Applications")
+        if suffix in output:
+            # Use the command-line launcher, if there is one.
+            if command != process_name:
+                return command
+            # Otherwise, use the running process’ path.
+            for process in processes:
+                if process.endswith(suffix):
+                    return process
+    return None
+
+
+def _editor_from_windows_processes(output: str) -> str | None:
+    for line in output.splitlines():
+        path = line.strip()
+        if PureWindowsPath(path).name in WINDOWS_EDITORS:
+            return path
+    return None
+
+
+def _editor_from_linux_processes(output: str) -> str | None:
+    processes = set(output.split())
+    for process_name, command in LINUX_EDITORS.items():
+        if process_name in processes:
+            return command
+    return None
+
+
+# Editor names, grouped by how they take a position.
+_COLON_POSITION_EDITORS = {
+    "Atom",
+    "Atom Beta",
+    "atom",
+    "charm",
+    "hx",
+    "subl",
+    "sublime",
+    "sublime_text",
+    "wstorm",
+    "zed",
+}
+_VSCODE_LIKE_EDITORS = {
+    "Antigravity",
+    "Code",
+    "Code - Insiders",
+    "Cursor",
+    "Trae",
+    "VSCodium",
+    "antigravity",
+    "code",
+    "code-insiders",
+    "codium",
+    "cursor",
+    "trae",
+    "vscodium",
+}
+_JETBRAINS_EDITORS = {
+    "appcode",
+    "clion",
+    "clion64",
+    "goland",
+    "goland64",
+    "idea",
+    "idea64",
+    "phpstorm",
+    "phpstorm64",
+    "pycharm",
+    "pycharm64",
+    "rider",
+    "rider64",
+    "rubymine",
+    "rubymine64",
+    "webstorm",
+    "webstorm64",
+}
+
+
+def position_args(
+    editor: str, filename: str, line: int, column: int | None = None
+) -> list[str]:
+    """
+    Return the arguments to open ``filename`` at ``line`` and ``column`` in
+    the given editor command.
+    """
+    if column is None:
+        column = 1
+    name = PureWindowsPath(editor).name if "\\" in editor else Path(editor).name
+    name = re.sub(r"\.(exe|cmd|bat)$", "", name, flags=re.IGNORECASE)
+
+    if name in _COLON_POSITION_EDITORS:
+        return [f"{filename}:{line}:{column}"]
+    if name == "notepad++":
+        return [f"-n{line}", f"-c{column}", filename]
+    if name in {"vim", "mvim", "nvim"}:
+        return [f"+call cursor({line}, {column})", filename]
+    if name in {"joe", "gvim", "vi"}:
+        return [f"+{line}", filename]
+    if name in {"emacs", "emacsclient", "micro"}:
+        return [f"+{line}:{column}", filename]
+    if name == "nano":
+        return [f"+{line},{column}", filename]
+    if name in {"rmate", "mate", "mine"}:
+        return ["--line", str(line), filename]
+    if name in _VSCODE_LIKE_EDITORS:
+        return ["-r", "-g", f"{filename}:{line}:{column}"]
+    if name in _JETBRAINS_EDITORS:
+        return ["--line", str(line), "--column", str(column), filename]
+
+    if os.environ.get("LAUNCH_EDITOR"):
+        return [filename, str(line), str(column)]
+
+    # For other editors, drop the position, since passing it incorrectly can
+    # result in errors or confusing behaviour.
+    return [filename]
+
+
+_terminal_editor: subprocess.Popen[bytes] | None = None
+_terminal_editor_lock = threading.Lock()
+
+
+def launch_editor(
+    filename: str | os.PathLike[str],
+    line: int | None = None,
+    column: int | None = None,
+    *,
+    editor: str | Sequence[str] | None = None,
+) -> subprocess.Popen[bytes]:
+    """
+    Open ``filename`` in the user’s editor, at ``line`` and ``column`` if
+    given.
+
+    The editor is picked by :func:`guess_editor`, using ``editor`` if given.
+    GUI editors are started in the background and this function returns
+    immediately. Terminal editors, like Vim, take over the current terminal;
+    while one is open, further calls to open a terminal editor fail.
+
+    Returns the editor process. Raises :class:`LaunchEditorError` if the
+    editor cannot be launched.
+    """
+    global _terminal_editor
+
+    filename = os.fspath(filename)
+
+    if sys.platform == "win32" and ntpath.abspath(filename).startswith("\\\\"):
+        raise LaunchEditorError(
+            f"Cannot open {filename}: UNC paths are not supported on Windows to "
+            + "avoid security issues. See "
+            + "https://github.com/vitejs/launch-editor/tree/main/packages/"
+            + "launch-editor#unc-paths-on-windows for details."
+        )
+
+    # Like the npm package, use an absolute path, so a filename starting with
+    # "-" cannot be interpreted as an option by the editor.
+    filename = os.path.abspath(filename)
+
+    if not os.path.exists(filename):
+        raise LaunchEditorError(f"File does not exist: {filename}")
+
+    command = guess_editor(editor)
+    if not command:
+        raise LaunchEditorError(
+            "Could not find an editor. Set the LAUNCH_EDITOR, VISUAL, or EDITOR "
+            + "environment variable."
+        )
+    editor_command, *args = command
+
+    if (
+        sys.platform == "linux"
+        and filename.startswith("/mnt/")
+        and "microsoft" in platform.release().lower()
+    ):
+        # Assume WSL is being used, and that the file is on the Windows file
+        # system. Windows editors can translate the path, but only if it is
+        # relative. Prefix it with "./" so it cannot be interpreted as an
+        # option.
+        filename = "./" + os.path.relpath(filename)
+
+    if line is not None:
+        args += position_args(editor_command, filename, line, column)
+    else:
+        args.append(filename)
+
+    with _terminal_editor_lock:
+        is_terminal = Path(editor_command).name in TERMINAL_EDITORS
+        if is_terminal and _terminal_editor is not None:
+            if _terminal_editor.poll() is None:
+                raise LaunchEditorError(
+                    f"{Path(editor_command).name} is already open in the "
+                    + "terminal. Close it first."
+                )
+            _terminal_editor = None
+
+        process = _run(editor_command, args)
+
+        if is_terminal:
+            _terminal_editor = process
+
+    threading.Thread(
+        name=f"launch_editor-wait-{process.pid}",
+        target=_report_failure,
+        args=(process, editor_command, filename),
+        daemon=True,
+    ).start()
+    return process
+
+
+def _run(editor: str, args: list[str]) -> subprocess.Popen[bytes]:
+    executable = shutil.which(editor) or editor
+    try:
+        if sys.platform == "win32" and executable.lower().endswith((".cmd", ".bat")):
+            # Windows runs batch files, such as VS Code’s code.cmd, with
+            # cmd.exe, which applies its own parsing to the command line. Quote
+            # every argument, and reject characters that cmd.exe would still
+            # interpret inside quotes, to prevent command injection.
+            return subprocess.Popen(_cmd_command_line([executable, *args]))
+        return subprocess.Popen([executable, *args])
+    except FileNotFoundError as exc:
+        raise LaunchEditorError(
+            f"Could not run {editor!r}: command not found on PATH."
+        ) from exc
+    except OSError as exc:
+        raise LaunchEditorError(f"Could not run {editor!r}: {exc}") from exc
+
+
+_CMD_UNSAFE_CHARS = {
+    '"': "a double quote",
+    "%": 'a percent sign ("%")',
+    "!": 'an exclamation mark ("!")',
+    "\r": "a line break",
+    "\n": "a line break",
+}
+
+
+def _cmd_command_line(args: list[str]) -> str:
+    for arg in args:
+        for char, description in _CMD_UNSAFE_CHARS.items():
+            if char in arg:
+                raise LaunchEditorError(
+                    f"Cannot safely pass {arg!r} to {args[0]!r}: it contains "
+                    + f"{description}, which cmd.exe would interpret, allowing "
+                    + "command injection. Use an editor that is an executable "
+                    + "rather than a batch file, or rename the file. See "
+                    + "https://github.com/vitejs/launch-editor/blob/v2.14.2/"
+                    + "packages/launch-editor/construct-windows-launch-command.js "
+                    + "for details."
+                )
+    return " ".join(f'"{arg}"' for arg in args)
+
+
+def _report_failure(
+    process: subprocess.Popen[bytes], editor: str, filename: str
+) -> None:
+    returncode = process.wait()
+    if returncode:
+        logger.warning(
+            "Could not open %s in the editor: %r exited with code %d.",
+            os.path.basename(filename),
+            editor,
+            returncode,
+        )

launch_editor_py-1.0.0/src/launch_editor/__main__.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import argparse
+import re
+import shlex
+import sys
+from collections.abc import Sequence
+
+from launch_editor import LaunchEditorError, guess_editor, launch_editor
+
+_POSITION_RE = re.compile(r":(\d+)(?::(\d+))?$")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m launch_editor",
+        description="Open a file in your editor.",
+        allow_abbrev=False,
+    )
+    parser.add_argument(
+        "file",
+        metavar="FILE",
+        nargs="?",
+        help=(
+            "The file to open, optionally followed by :LINE or :LINE:COLUMN, "
+            + "like example.py:12:4."
+        ),
+    )
+    parser.add_argument(
+        "--editor",
+        help="The editor command to use, instead of guessing.",
+    )
+    parser.add_argument(
+        "--guess",
+        action="store_true",
+        help="Print the editor command that would be used, and exit.",
+    )
+    args = parser.parse_args(argv)
+
+    if args.guess:
+        command = guess_editor(args.editor)
+        if not command:
+            print("No editor found.", file=sys.stderr)
+            return 1
+        print(shlex.join(command))
+        return 0
+
+    if args.file is None:
+        parser.error("FILE is required.")
+
+    filename = args.file
+    line = column = None
+    match = _POSITION_RE.search(filename)
+    if match:
+        filename = filename[: match.start()]
+        line = int(match[1])
+        if match[2] is not None:
+            column = int(match[2])
+
+    try:
+        process = launch_editor(filename, line, column, editor=args.editor)
+    except LaunchEditorError as exc:
+        print(exc, file=sys.stderr)
+        return 1
+
+    # Wait, so terminal editors keep the terminal, and to report failures.
+    return process.wait()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())