ansi-escapes 0.1.1
ANSI escape codes for manipulating the terminal
License: MIT
Requires Python: >=3.6,<4.0

# ansi-escapes

> [ANSI escape codes](https://web.archive.org/web/20200413124215/http://www.termsys.demon.co.uk/vtansi.htm) for manipulating the terminal


A port of the Node.js package [`ansi-escapes`](https://github.com/sindresorhus/ansi-escapes) to Python.

## Install

```
python3 -m pip install -U ansi-escapes
```

## Usage

```py
from ansi_escapes import ansiEscapes
import sys

# Moves the cursor two rows up and to the left
sys.stdout.write(ansiEscapes.cursorUp(2) + ansiEscapes.cursorLeft)
#>>> '\u001B[2A\u001B[1000D'
```


## API

### cursorTo(x, y?)

Set the absolute position of the cursor. `x0` `y0` is the top left of the screen.

### cursorMove(x, y?)

Set the position of the cursor relative to its current position.

### cursorUp(count)

Move cursor up a specific amount of rows. Default is `1`.

### cursorDown(count)

Move cursor down a specific amount of rows. Default is `1`.

### cursorForward(count)

Move cursor forward a specific amount of columns. Default is `1`.

### cursorBackward(count)

Move cursor backward a specific amount of columns. Default is `1`.

### cursorLeft

Move cursor to the left side.

### cursorSavePosition

Save cursor position.

### cursorRestorePosition

Restore saved cursor position.

### cursorGetPosition

Get cursor position.

### cursorNextLine

Move cursor to the next line.

### cursorPrevLine

Move cursor to the previous line.

### cursorHide

Hide cursor.

### cursorShow

Show cursor.

### eraseLines(count)

Erase from the current cursor position up the specified amount of rows.

### eraseEndLine

Erase from the current cursor position to the end of the current line.

### eraseStartLine

Erase from the current cursor position to the start of the current line.

### eraseLine

Erase the entire current line.

### eraseDown

Erase the screen from the current line down to the bottom of the screen.

### eraseUp

Erase the screen from the current line up to the top of the screen.

### eraseScreen

Erase the screen and move the cursor the top left position.

### scrollUp

Scroll display up one line.

### scrollDown

Scroll display down one line.

### clearScreen

Clear the terminal screen. (Viewport)

### clearTerminal

Clear the whole terminal, including scrollback buffer. (Not just the visible part of it)

### beep

Output a beeping sound.

### link(text, url)

Create a clickable link.

[Supported terminals.](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) Use [`supports-hyperlinks`](https://github.com/jamestalmage/supports-hyperlinks) to detect link support.

### image(filePath, options?)

(Not yet implemented.)

Display an image.

*Currently only supported on iTerm2 >=3*

See [term-img](https://github.com/sindresorhus/term-img) for a higher-level module.

#### input

Type: `Buffer`

Buffer of an image. Usually read in with `fs.readFile()`.

#### options

Type: `object`

##### width
##### height

Type: `string | number`

The width and height are given as a number followed by a unit, or the word "auto".

- `N`: N character cells.
- `Npx`: N pixels.
- `N%`: N percent of the session's width or height.
- `auto`: The image's inherent size will be used to determine an appropriate dimension.

##### preserveAspectRatio

Type: `boolean`\
Default: `true`

### iTerm.setCwd(path?)

Type: `string`\
Default: `process.cwd()`

[Inform iTerm2](https://www.iterm2.com/documentation-escape-codes.html) of the current directory to help semantic history and enable [Cmd-clicking relative paths](https://coderwall.com/p/b7e82q/quickly-open-files-in-iterm-with-cmd-click).

### iTerm.annotation(message, **options)

Creates an escape code to display an "annotation" in iTerm2.

An annotation looks like this when shown:

<img src="https://user-images.githubusercontent.com/924465/64382136-b60ac700-cfe9-11e9-8a35-9682e8dc4b72.png" width="500">

See the [iTerm Proprietary Escape Codes documentation](https://iterm2.com/documentation-escape-codes.html) for more information.

#### message

Type: `string`

The message to display within the annotation.

The `|` character is disallowed and will be stripped.

#### options

Type: `object`

##### length

Type: `number`\
Default: The remainder of the line

Nonzero number of columns to annotate.

##### x

Type: `number`\
Default: Cursor position

Starting X coordinate.

Must be used with `y` and `length`.

##### y

Type: `number`\
Default: Cursor position

Starting Y coordinate.

Must be used with `x` and `length`.

##### isHidden

Type: `boolean`\
Default: `false`

Create a "hidden" annotation.

Annotations created this way can be shown using the "Show Annotations" iTerm command.

## Related

- [ansi-styles](https://github.com/shawwn/ansi-styles-python) - ANSI escape codes for styling strings in the terminal

## License

MIT

## Contact

A library by [Shawn Presser](https://www.shawwn.com). If you found it useful, please consider [joining my patreon](https://www.patreon.com/shawwn)!

My Twitter DMs are always open; you should [send me one](https://twitter.com/theshawwn)! It's the best way to reach me, and I'm always happy to hear from you.

- Twitter: [@theshawwn](https://twitter.com/theshawwn)
- Patreon: [https://www.patreon.com/shawwn](https://www.patreon.com/shawwn)
- HN: [sillysaurusx](https://news.ycombinator.com/threads?id=sillysaurusx)
- Website: [shawwn.com](https://www.shawwn.com)