# 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)
Raw data
{
"_id": null,
"home_page": "https://github.com/shawwn/ansi-escapes-python",
"name": "ansi-escapes",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Shawn Presser",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/57/3c/e90e9017f3fce4841ebdf39af12480e54dbfdb2592d0f9264733f4bfd23c/ansi-escapes-0.1.1.tar.gz",
"platform": "",
"description": "# ansi-escapes\n\n> [ANSI escape codes](https://web.archive.org/web/20200413124215/http://www.termsys.demon.co.uk/vtansi.htm) for manipulating the terminal\n\n\nA port of the Node.js package [`ansi-escapes`](https://github.com/sindresorhus/ansi-escapes) to Python.\n\n## Install\n\n```\npython3 -m pip install -U ansi-escapes\n```\n\n## Usage\n\n```py\nfrom ansi_escapes import ansiEscapes\nimport sys\n\n# Moves the cursor two rows up and to the left\nsys.stdout.write(ansiEscapes.cursorUp(2) + ansiEscapes.cursorLeft)\n#>>> '\\u001B[2A\\u001B[1000D'\n```\n\n\n## API\n\n### cursorTo(x, y?)\n\nSet the absolute position of the cursor. `x0` `y0` is the top left of the screen.\n\n### cursorMove(x, y?)\n\nSet the position of the cursor relative to its current position.\n\n### cursorUp(count)\n\nMove cursor up a specific amount of rows. Default is `1`.\n\n### cursorDown(count)\n\nMove cursor down a specific amount of rows. Default is `1`.\n\n### cursorForward(count)\n\nMove cursor forward a specific amount of columns. Default is `1`.\n\n### cursorBackward(count)\n\nMove cursor backward a specific amount of columns. Default is `1`.\n\n### cursorLeft\n\nMove cursor to the left side.\n\n### cursorSavePosition\n\nSave cursor position.\n\n### cursorRestorePosition\n\nRestore saved cursor position.\n\n### cursorGetPosition\n\nGet cursor position.\n\n### cursorNextLine\n\nMove cursor to the next line.\n\n### cursorPrevLine\n\nMove cursor to the previous line.\n\n### cursorHide\n\nHide cursor.\n\n### cursorShow\n\nShow cursor.\n\n### eraseLines(count)\n\nErase from the current cursor position up the specified amount of rows.\n\n### eraseEndLine\n\nErase from the current cursor position to the end of the current line.\n\n### eraseStartLine\n\nErase from the current cursor position to the start of the current line.\n\n### eraseLine\n\nErase the entire current line.\n\n### eraseDown\n\nErase the screen from the current line down to the bottom of the screen.\n\n### eraseUp\n\nErase the screen from the current line up to the top of the screen.\n\n### eraseScreen\n\nErase the screen and move the cursor the top left position.\n\n### scrollUp\n\nScroll display up one line.\n\n### scrollDown\n\nScroll display down one line.\n\n### clearScreen\n\nClear the terminal screen. (Viewport)\n\n### clearTerminal\n\nClear the whole terminal, including scrollback buffer. (Not just the visible part of it)\n\n### beep\n\nOutput a beeping sound.\n\n### link(text, url)\n\nCreate a clickable link.\n\n[Supported terminals.](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) Use [`supports-hyperlinks`](https://github.com/jamestalmage/supports-hyperlinks) to detect link support.\n\n### image(filePath, options?)\n\n(Not yet implemented.)\n\nDisplay an image.\n\n*Currently only supported on iTerm2 >=3*\n\nSee [term-img](https://github.com/sindresorhus/term-img) for a higher-level module.\n\n#### input\n\nType: `Buffer`\n\nBuffer of an image. Usually read in with `fs.readFile()`.\n\n#### options\n\nType: `object`\n\n##### width\n##### height\n\nType: `string | number`\n\nThe width and height are given as a number followed by a unit, or the word \"auto\".\n\n- `N`: N character cells.\n- `Npx`: N pixels.\n- `N%`: N percent of the session's width or height.\n- `auto`: The image's inherent size will be used to determine an appropriate dimension.\n\n##### preserveAspectRatio\n\nType: `boolean`\\\nDefault: `true`\n\n### iTerm.setCwd(path?)\n\nType: `string`\\\nDefault: `process.cwd()`\n\n[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).\n\n### iTerm.annotation(message, **options)\n\nCreates an escape code to display an \"annotation\" in iTerm2.\n\nAn annotation looks like this when shown:\n\n<img src=\"https://user-images.githubusercontent.com/924465/64382136-b60ac700-cfe9-11e9-8a35-9682e8dc4b72.png\" width=\"500\">\n\nSee the [iTerm Proprietary Escape Codes documentation](https://iterm2.com/documentation-escape-codes.html) for more information.\n\n#### message\n\nType: `string`\n\nThe message to display within the annotation.\n\nThe `|` character is disallowed and will be stripped.\n\n#### options\n\nType: `object`\n\n##### length\n\nType: `number`\\\nDefault: The remainder of the line\n\nNonzero number of columns to annotate.\n\n##### x\n\nType: `number`\\\nDefault: Cursor position\n\nStarting X coordinate.\n\nMust be used with `y` and `length`.\n\n##### y\n\nType: `number`\\\nDefault: Cursor position\n\nStarting Y coordinate.\n\nMust be used with `x` and `length`.\n\n##### isHidden\n\nType: `boolean`\\\nDefault: `false`\n\nCreate a \"hidden\" annotation.\n\nAnnotations created this way can be shown using the \"Show Annotations\" iTerm command.\n\n## Related\n\n- [ansi-styles](https://github.com/shawwn/ansi-styles-python) - ANSI escape codes for styling strings in the terminal\n\n## License\n\nMIT\n\n## Contact\n\nA library by [Shawn Presser](https://www.shawwn.com). If you found it useful, please consider [joining my patreon](https://www.patreon.com/shawwn)!\n\nMy 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.\n\n- Twitter: [@theshawwn](https://twitter.com/theshawwn)\n- Patreon: [https://www.patreon.com/shawwn](https://www.patreon.com/shawwn)\n- HN: [sillysaurusx](https://news.ycombinator.com/threads?id=sillysaurusx)\n- Website: [shawwn.com](https://www.shawwn.com)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "ANSI escape codes for manipulating the terminal",
"version": "0.1.1",
"project_urls": {
"@theshawwn on Twitter": "https://www.twitter.com/theshawwn",
"Homepage": "https://github.com/shawwn/ansi-escapes-python",
"Shawn's Website": "https://www.shawwn.com",
"Support me on Patreon": "https://www.patreon.com/shawwn",
"sillysaurusx on Hacker News": "https://news.ycombinator.com/threads?id=sillysaurusx"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6bccd7fe3ab06f2f5ce3056cdbcc5424d77f58fbc34355ef5de995b9ffc3119b",
"md5": "91ce943e49e314092a3a6c3e65762f89",
"sha256": "543035918c38b758ddf80661178eecc67f602b035c37ebfa75c319382bfd9219"
},
"downloads": -1,
"filename": "ansi_escapes-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "91ce943e49e314092a3a6c3e65762f89",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6,<4.0",
"size": 4709,
"upload_time": "2021-05-22T22:40:48",
"upload_time_iso_8601": "2021-05-22T22:40:48.680314Z",
"url": "https://files.pythonhosted.org/packages/6b/cc/d7fe3ab06f2f5ce3056cdbcc5424d77f58fbc34355ef5de995b9ffc3119b/ansi_escapes-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "573ce90e9017f3fce4841ebdf39af12480e54dbfdb2592d0f9264733f4bfd23c",
"md5": "ea3e4f4c6be2a08efa881f40f1bcfde9",
"sha256": "dbe59dd683e9a05a9821cdc3f190ed2a98ffd08d555920da2c36a898d67724d4"
},
"downloads": -1,
"filename": "ansi-escapes-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "ea3e4f4c6be2a08efa881f40f1bcfde9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6,<4.0",
"size": 5142,
"upload_time": "2021-05-22T22:40:47",
"upload_time_iso_8601": "2021-05-22T22:40:47.393741Z",
"url": "https://files.pythonhosted.org/packages/57/3c/e90e9017f3fce4841ebdf39af12480e54dbfdb2592d0f9264733f4bfd23c/ansi-escapes-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-05-22 22:40:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shawwn",
"github_project": "ansi-escapes-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ansi-escapes"
}
JSON
