python-editing-terminal README

Python Editing Terminal is a Python shell for your Visual Studio Code workspace. Right now, it can access and edit the current file, or a selection, and open a new or existing one. It is also possible to use Python Editing Terminal with other languages besides Python.

Examples & Features

Open the Python Editing Terminal from the Command Menu (Ctrl+P >Open Python Editing Terminal). A terminal will open, where you can run arbitrary Python code and use the vscode module.

Examples:

• Get or set the file text (Unicode-aware):

  >>> vscode.editor.text
  'This is the content of the current file open in Visual Studio Code.'
  >>> vscode.editor.text = "Hello World!"
  >>> vscode.editor.text
  'Hello World'
  

  On Python 2, this returns an unicode object; on Python 3, a str object is returned.
• Get or set the file content (UTF-8 encoded, relevant on Python 3):

  >>> vscode.editor.content
  b'This is the content of the current file open in Visual Studio Code.'
  >>> vscode.editor.content = "Hello World!"
  >>> vscode.editor.content
  b'Hello World'
  

  On Python 2, this returns a str object; on Python 3, a bytes object is returned.
• Get or set the selection:

  >>> vscode.selection.text
  's is the content o'
  >> vscode.selection.text = '-REDACTED-'
  >> vscode.editor.text
  'Thi-REDACTED-f the current file open in Visual Studio Code.`
  

• Get and set the lines in the file (without newlines):

  >>> vscode.editor.text
  'line1\r\nline2\r\nline3'
  >>> vscode.editor.lines
  ['line1', 'line2', 'line3']
  >>> vscode.editor.lines = range(4)
  >>> vscode.editor.text
  '0\r\n1\r\n2\r\n4'
  

• Get and set the file text as JSON:

  >>> vscode.editor.text
  '[{"field": "value1"}, {"field2": 0, "field": "value2"}]'
  >>> vscode.editor.json
  [{u'field': u'value1'}, {u'field2': 0, u'field': u'value2'}]
  >>> vscode.editor.json = range(4)
  >>> vscode.editor.json
  [0, 1, 2, 3]
  >>> vscode.editor.text
  '[\n 0, \n 1, \n 2, \n 3\n]'
  

• Get and set the file text as CSV:

  >>> vscode.editor.text
  '1, 2, 3, 4\r\n5, 6, 7, 8'
  >>> vscode.editor.csv
  [['1', ' 2', ' 3', ' 4'], ['5', ' 6', ' 7', ' 8']]
  >>> vscode.editor.csv = [range(2) for _ in range(3)]
  >>> vscode.editor.csv
  [['0', '1'], ['0', '1'], ['0', '1']]
  >>> vscode.editor.text
  '0,1\r\n0,1\r\n0,1\r\n'
  

• Get and set the file text as TSV:

  >>> vscode.editor.text
  '1\t2\t3\t4\r\n5\t6\t7\t8'
  >>> vscode.editor.tsv
  [['1', ' 2', ' 3', ' 4'], ['5', ' 6', ' 7', ' 8']]
  >>> vscode.editor.tsv = [range(2) for _ in range(3)]
  >>> vscode.editor.tsv
  [['0', '1'], ['0', '1'], ['0', '1']]
  >>> vscode.editor.text
  '0\t1\r\n0\t1\r\n0\t1\r\n'
  

• Open new tabs:

  >>> vscode.editor.new()  # This opens a new untitled tab
  >>> vscode.editor.new(text="Text to be added to the new tab")  # keyword arguments `content`, `lines`, `json`, `csv`, and `tsv` are also available, used as above
  >>> vscode.editor.text
  'Text to be added to the new tab'
  >>> vscode.editor.new(filename="new_file.txt")  # `text`, `content`, `lines`, `json`, `csv`, and `tsv` arguments are also available
  >>> vscode.editor.new(filename="existing_file.txt")  # the file will be opened, `text`, `content`, `lines`, `json`, `csv`, and `tsv` arguments can also modify it
  

• Query a REST API directly from your editor:

  >>> import requests
  >>> vscode.editor.new(text=requests.get("http://freegeoip.net/json/www.google.com").text)
  >>> vscode.editor.json
  {u'city': u'',
  u'country_code': u'US',
  u'country_name': u'United States',
  u'ip': u'2607:f8b0:4006:812::2004',
  u'latitude': 37.751,
  u'longitude': -97.822,
  u'metro_code': 0,
  u'region_code': u'',
  u'region_name': u'',
  u'time_zone': u'',
  u'zip_code': u''}
  

• Convert a file from CSV to TSV (or vice-versa):

  >>> vscode.editor.tsv = vscode.editor.csv
  

Reference

The vscode module contains two objects, vscode.editor and vscode.selection that access the entire document, or just the selection, respectively. These expose the following properties:

• vscode.editor.text (or vscode.selection.text): The text of the currently open document/selection. Getting it fetches the text from the editor, setting it changes it in the editor. Returns and is set with an Unicode-aware object (unicode under Python 2, str under Python 3).
• vscode.editor.content (or vscode.selection.content): The text of the current open document/selection, encoded as UTF-8. Can be set like vscode.editor.text. Returns and is set with a non-Unicode-aware object (str under Python 2, bytes under Python 3). The distinction is the same as content and text in the Requests Python module.
• vscode.editor.lines (or vscode.selection.lines): The current document/selection, split as a list of lines. Newlines are stripped (not included in the list entries). Setting it to a list of strings (without trailing newlines) sets the document text to those lines. OS-specific newline style is respected.
• vscode.editor.json (or vscode.selection.json): The current document/selection, parsed as JSON. Getting it gives you a object parsed from the current document, setting it writes an object as JSON.
• vscode.editor.csv (or vscode.selection.csv): The current document/selection, parsed as CSV. Getting it gives you a list of lists, setting it writes a list of lists as CSV.
• vscode.editor.tsv (or vscode.selection.tsv): The current document/selection, parsed as TSV. Getting it gives you a list of lists, setting it writes a list of lists as TSV.

The vscode.editor/vscode.selection objects also expose the following method:

• vscode.editor.new(filename=None, text=None, content==None, lines=None, json=None, csv=None, tsv=None): Open a new tab and optionally also set its content. All parameters are optional, but at most one of text, content, lines, json, csv, or tsv should be specified. The filename is relative to the open workspace.

Requirements

This extension depends on the requests Python module. Install it with pip install requests.

Extension Settings

This extension contributes the following settings:

• pythonEditingTerm.termPath: The Python executable. Can be either the main executable, or another Python shell, like IPython. (See the following section for using other languages.) Can be a full path or the name of a binary on the PATH environment variable.
• pythonEditingTerm.termArgs: Additional arguments to pass to the Python executable. Warning, may not work under certain OSs.
• pythonEditingTerm.termInit: The original code to run on startup. Necessary to connect the terminal to Visual Studio Code. {port} is replaced with the server port, and {extPath} is replaced with the extension root directory.

Changing the shell & using other languages

Python Editing Terminal exposes a pythonEditingTerm.termPath setting, containing the full path to the Python shell executable. This extension is tested under Python and IPython, versions 2.7 and 3.7, but any other languages with a shell (not necessarily Python) can work.

This extension runs a local Node.js REST server and responds to the following requests:

• GET request on /text: returns the text in the current editor tab. Use the Etag and If-None-Modified HTTP headers to prevent redownloading the file every time, if there was no change.
• PUT request on /text, with request body: sets the text in the current editor to the request body.
• POST request on /new, with a filename field (optionally empty): open a new tab with the given filename. If the filename is empty, the new tab is untitled.

To enable editing from other languages, change the pythonEditingTerm.termPath config to the path to your language's shell. Then, change the pythonEditingTerm.termInit config to some code that provides functions to easily GET, PUT and POST to that HTTP server. For example, for Python, this is the code:

import sys; import os; sys.path.insert(0, os.path.join(R'{extPath}', 'py')); import vscode; vscode.set_port({port});

As mentioned above, {extPath} is replaced with the extension install directory and {port} with the port on which the server is running.

Commented code:

# Import necessary modules
import sys; import os;
# The extension provides a module located at R"{extension_install_directory}/py/vscode.py"
# Update the paths to make it discoverable
sys.path.insert(0, os.path.join(R'{extPath}', 'py'));
# Import the module
import vscode;
# Set the port on which to make the HTTP requests
vscode.set_port({port});

See the Python module code here.

Release Notes

1.0

Initial release.

1.0.1

Documentation update.

1.0.2

Bugfix release, see the changelog.

1.0.3

Added vscode.editor.new Python function & server support, better help and instructions to add support for other languages.

1.0.4

Added lines support alongside json and csv.

1.0.5

• Added content property
• Fixed Python 3 support, Unicode support, and other minor bugs.
• Can now find the Python binaries on the path.
• Added vscode.selection.XX (where XX can be text, content, lines, json or csv).

1.0.6

• Added tsv property (to vscode.editor, vscode.selection, and help)

License

Python Editing Terminal is licensed under the MIT License.