# stty.py
A Python library for manipulating terminal settings in the style of POSIX `stty(1)`.
---
## Overview
`stty` provides a high-level, Pythonic interface to terminal I/O settings, including control characters, baud rates, and window size, using the `termios` and related modules. It allows you to get, set, save, and restore terminal attributes, and to apply them to file descriptors or pseudo-terminals.
---
## Features
- Read and modify terminal attributes (iflag, oflag, cflag, lflag, control characters, speeds, window size)
- Save and load settings to/from JSON files
- Apply settings to file descriptors or pseudo-terminals
- Symbolic and string-based access to all settings
- Emulates many `stty(1)` features and modes (e.g., raw, evenp, oddp, nl, ek)
- Cross-platform support (where `termios` is available)
---
## Requirements and Installation
**Python 3.13 or above** is required. To install this package, run:
```bash
pip install stty
```
Alternatively, since this library does not have any dependencies outside of the Python standard library, simply place `stty.py` in your project.
---
## Examples
### 1. Reading and Printing Terminal Settings
```python
from stty import Stty
# Open terminal and get current settings from stdin (fd=0)
tty = Stty(fd=0)
print(tty) # Print all settings in a compact form
```
---
### 2. Setting Individual Attributes
```python
from stty import Stty
tty = Stty(fd=0)
# Turn off echo
tty.echo = False
# Set erase character to Ctrl-H
tty.erase = "^H"
# Set input baud rate to 9600
tty.ispeed = 9600
# Set number of rows in the terminal window (if supported)
tty.rows = 40
```
---
### 3. Setting Multiple Attributes at Once
```python
from stty import Stty
tty = Stty(fd=0)
# Set several attributes in one call
tty.set(
echo=False,
icanon=False,
erase="^H",
ispeed=19200,
ospeed=19200,
rows=30,
cols=100
)
```
---
### 4. Saving and Loading Settings
```python
from stty import Stty
tty = Stty(fd=0)
# Save current settings to a file
tty.save("my_tty_settings.json")
# Later, restore settings from the file
tty2 = Stty(path="my_tty_settings.json")
tty2.tofd(0) # Apply to stdin
```
---
### 5. Using Raw Mode
```python
from stty import Stty
tty = Stty(fd=0)
tty.raw() # Set raw mode
tty.tofd(0) # Apply to stdin
```
---
### 6. Working with Pseudo-terminals
```python
from stty import Stty
tty = Stty(fd=0)
m, s, sname = tty.openpty() # Open a new pty pair and apply settings to slave
print(f"Master fd: {m}, Slave fd: {s}, Slave name: {sname}")
```
---
### 7. Setting Control Characters
```python
from stty import Stty
tty = Stty(fd=0)
# Set interrupt character to Ctrl-C
tty.intr = "^C"
# Set end-of-file character to Ctrl-D
tty.eof = "^D"
# Set suspend character to DEL
tty.susp = "^?"
```
---
### 8. Querying Settings as a Dictionary
```python
from stty import Stty
tty = Stty(fd=0)
settings = tty.get()
print(settings["echo"]) # True or False
print(settings["erase"]) # e.g., '^H'
```
---
### 9. Using Symbolic Constants
```python
from stty import Stty, cs8, tab0
tty = Stty(fd=0)
# Set character size to 8 bits using symbolic constant
tty.csize = cs8
# Set tab delay to tab0
tty.tabdly = tab0
```
---
### 10. Fork new process with pseudo-terminal
```python
x = stty.Stty(0)
x.intr = "^p"
pid, m, sname = x.forkpty()
if pid == 0: # Child process
with open("out", "w") as f:
f.write(str(stty.Stty(0)))
else: # Parent process
print(sname)
print("")
s = os.open(sname, os.O_RDWR)
print("Parent:", stty.Stty(s))
os.close(s)
```
---
### 11. Check equality of (all termios and winsize attributes of) 2 Stty objects
```python
x = stty.Stty(0)
y = stty.Stty(0)
if x.get() == y.get():
print("equal")
else:
print("not equal")
```
---
### 12. Check equality of (some termios and winsize attributes of) 2 Stty objects
```python
x = stty.Stty(0)
if x.eq(echo=True, eof="^D")
print("echo is True and eof is ^D")
else:
print("echo is False or eof is not ^D")
```
---
## API Reference
### Classes
#### `Stty`
Manipulate terminal settings in the style of `stty(1)`.
**Constructor:**
```python
Stty(fd: int = None, path: str = None, **opts)
```
- `fd`: File descriptor to read settings from.
- `path`: Path to JSON file to load settings from.
- `**opts`: Any supported terminal attribute as a keyword argument.
**Methods:**
- `get() -> dict`
Return dictionary of termios and winsize attributes available on the system mapped to their respective values.
- `set(**opts)`
Set multiple attributes as named arguments.
- `eq(**opts)`
Return True if all attributes, which are specified as named arguments, have values equal to those of the corresponding named arguments; return False otherwise.
- `save(path: str = None)`
Return deep copy of self or save JSON. This mimics "stty -g".
- `load(path: str)`
Load termios and winsize from JSON file.
- `fromfd(fd: int)`
Get settings from terminal.
- `tofd(fd: int, when=TCSANOW, apply_termios=True, apply_winsize=True)`
Apply settings to terminal.
- `evenp(plus=True)`
Set/unset evenp combination mode.
- `oddp(plus=True)`
Set/unset oddp combination mode.
- `raw()`
Set raw combination mode.
- `nl(plus=True)`
Set/unset nl combination mode.
- `ek()`
Set ek combination mode.
- `openpty(apply_termios=True, apply_winsize=True)`
Open a new pty pair and apply settings to slave end.
- `forkpty(apply_termios=True, apply_winsize=True)`
Call os.forkpty() and apply settings to slave end.
**Attribute Access:**
- All terminal attributes (e.g., `echo`, `icanon`, `erase`, `ispeed`, `rows`, etc.) are accessible as properties.
- Setting an attribute updates the internal state and validates the value.
---
### Constants
- `TCSANOW`, `TCSADRAIN`, `TCSAFLUSH`: the values accepted by the `when` named argument of `Stty.tofd()`. Compare with `termios.tcsetattr()`.
- Symbolic constants for masks and values (e.g., `cs8`, `tab0`, etc.) are available as module attributes.
---
### Data
- `settings`: A dictionary describing all available Stty attributes and their possible values on the current platform.
---
### Functions
- `settings_help_str`: Return help string about all available Stty attributes and their possible values on the current platform.
- `settings_help`: Print help message about all available Stty attributes and their possible values on the current platform.
---
## Compatibility
- Requires Python 3.x and a POSIX-like system with the `termios` module.
- Some features depend on platform support (e.g., window size).
---
## License
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
---
## Author
Soumendra Ganguly, 2025
---
## See Also
- [stty(1) manpage](https://man7.org/linux/man-pages/man1/stty.1.html)
- [Python termios documentation](https://docs.python.org/3/library/termios.html)
Raw data
{
"_id": null,
"home_page": null,
"name": "stty",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": "Soumendra Ganguly <soumendraganguly@gmail.com>",
"keywords": "terminal, tty, stty, termios, winsize, posix, terminal-settings, pseudo-terminal, pty, terminal-attributes",
"author": null,
"author_email": "Soumendra Ganguly <soumendraganguly@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/29/9a/96c9468e2a2ad751da8a1acabc2f2dbd8d427f5f66518d43bd564f148232/stty-0.0.5.tar.gz",
"platform": null,
"description": "# stty.py\n\nA Python library for manipulating terminal settings in the style of POSIX `stty(1)`.\n\n---\n\n## Overview\n\n`stty` provides a high-level, Pythonic interface to terminal I/O settings, including control characters, baud rates, and window size, using the `termios` and related modules. It allows you to get, set, save, and restore terminal attributes, and to apply them to file descriptors or pseudo-terminals.\n\n---\n\n## Features\n\n- Read and modify terminal attributes (iflag, oflag, cflag, lflag, control characters, speeds, window size)\n- Save and load settings to/from JSON files\n- Apply settings to file descriptors or pseudo-terminals\n- Symbolic and string-based access to all settings\n- Emulates many `stty(1)` features and modes (e.g., raw, evenp, oddp, nl, ek)\n- Cross-platform support (where `termios` is available)\n\n---\n\n## Requirements and Installation\n\n**Python 3.13 or above** is required. To install this package, run:\n\n```bash\npip install stty\n```\n\nAlternatively, since this library does not have any dependencies outside of the Python standard library, simply place `stty.py` in your project.\n\n---\n\n## Examples\n\n### 1. Reading and Printing Terminal Settings\n\n```python\nfrom stty import Stty\n\n# Open terminal and get current settings from stdin (fd=0)\ntty = Stty(fd=0)\nprint(tty) # Print all settings in a compact form\n```\n\n---\n\n### 2. Setting Individual Attributes\n\n```python\nfrom stty import Stty\n\ntty = Stty(fd=0)\n\n# Turn off echo\ntty.echo = False\n\n# Set erase character to Ctrl-H\ntty.erase = \"^H\"\n\n# Set input baud rate to 9600\ntty.ispeed = 9600\n\n# Set number of rows in the terminal window (if supported)\ntty.rows = 40\n```\n\n---\n\n### 3. Setting Multiple Attributes at Once\n\n```python\nfrom stty import Stty\n\ntty = Stty(fd=0)\n\n# Set several attributes in one call\ntty.set(\n echo=False,\n icanon=False,\n erase=\"^H\",\n ispeed=19200,\n ospeed=19200,\n rows=30,\n cols=100\n)\n```\n\n---\n\n### 4. Saving and Loading Settings\n\n```python\nfrom stty import Stty\n\ntty = Stty(fd=0)\n\n# Save current settings to a file\ntty.save(\"my_tty_settings.json\")\n\n# Later, restore settings from the file\ntty2 = Stty(path=\"my_tty_settings.json\")\ntty2.tofd(0) # Apply to stdin\n```\n\n---\n\n### 5. Using Raw Mode\n\n```python\nfrom stty import Stty\n\ntty = Stty(fd=0)\ntty.raw() # Set raw mode\ntty.tofd(0) # Apply to stdin\n```\n\n---\n\n### 6. Working with Pseudo-terminals\n\n```python\nfrom stty import Stty\n\ntty = Stty(fd=0)\nm, s, sname = tty.openpty() # Open a new pty pair and apply settings to slave\nprint(f\"Master fd: {m}, Slave fd: {s}, Slave name: {sname}\")\n```\n\n---\n\n### 7. Setting Control Characters\n\n```python\nfrom stty import Stty\n\ntty = Stty(fd=0)\n\n# Set interrupt character to Ctrl-C\ntty.intr = \"^C\"\n\n# Set end-of-file character to Ctrl-D\ntty.eof = \"^D\"\n\n# Set suspend character to DEL\ntty.susp = \"^?\"\n```\n\n---\n\n### 8. Querying Settings as a Dictionary\n\n```python\nfrom stty import Stty\n\ntty = Stty(fd=0)\nsettings = tty.get()\nprint(settings[\"echo\"]) # True or False\nprint(settings[\"erase\"]) # e.g., '^H'\n```\n\n---\n\n### 9. Using Symbolic Constants\n\n```python\nfrom stty import Stty, cs8, tab0\n\ntty = Stty(fd=0)\n\n# Set character size to 8 bits using symbolic constant\ntty.csize = cs8\n\n# Set tab delay to tab0\ntty.tabdly = tab0\n```\n\n---\n\n### 10. Fork new process with pseudo-terminal\n\n```python\nx = stty.Stty(0)\nx.intr = \"^p\"\npid, m, sname = x.forkpty()\n\nif pid == 0: # Child process\n with open(\"out\", \"w\") as f:\n f.write(str(stty.Stty(0)))\nelse: # Parent process\n print(sname)\n print(\"\")\n s = os.open(sname, os.O_RDWR)\n print(\"Parent:\", stty.Stty(s))\n os.close(s)\n```\n\n---\n\n### 11. Check equality of (all termios and winsize attributes of) 2 Stty objects\n\n```python\nx = stty.Stty(0)\ny = stty.Stty(0)\n\nif x.get() == y.get():\n print(\"equal\")\nelse:\n print(\"not equal\")\n```\n\n---\n\n### 12. Check equality of (some termios and winsize attributes of) 2 Stty objects\n\n```python\nx = stty.Stty(0)\n\nif x.eq(echo=True, eof=\"^D\")\n print(\"echo is True and eof is ^D\")\nelse:\n print(\"echo is False or eof is not ^D\")\n```\n\n---\n\n## API Reference\n\n### Classes\n\n#### `Stty`\n\nManipulate terminal settings in the style of `stty(1)`.\n\n**Constructor:**\n```python\nStty(fd: int = None, path: str = None, **opts)\n```\n- `fd`: File descriptor to read settings from.\n- `path`: Path to JSON file to load settings from.\n- `**opts`: Any supported terminal attribute as a keyword argument.\n\n**Methods:**\n\n- `get() -> dict`\n Return dictionary of termios and winsize attributes available on the system mapped to their respective values.\n\n- `set(**opts)`\n Set multiple attributes as named arguments.\n\n- `eq(**opts)`\n Return True if all attributes, which are specified as named arguments, have values equal to those of the corresponding named arguments; return False otherwise.\n\n- `save(path: str = None)`\n Return deep copy of self or save JSON. This mimics \"stty -g\".\n\n- `load(path: str)`\n Load termios and winsize from JSON file.\n\n- `fromfd(fd: int)`\n Get settings from terminal.\n\n- `tofd(fd: int, when=TCSANOW, apply_termios=True, apply_winsize=True)`\n Apply settings to terminal.\n\n- `evenp(plus=True)`\n Set/unset evenp combination mode.\n\n- `oddp(plus=True)`\n Set/unset oddp combination mode.\n\n- `raw()`\n Set raw combination mode.\n\n- `nl(plus=True)`\n Set/unset nl combination mode.\n\n- `ek()`\n Set ek combination mode.\n\n- `openpty(apply_termios=True, apply_winsize=True)`\n Open a new pty pair and apply settings to slave end.\n\n- `forkpty(apply_termios=True, apply_winsize=True)`\n Call os.forkpty() and apply settings to slave end.\n\n**Attribute Access:**\n\n- All terminal attributes (e.g., `echo`, `icanon`, `erase`, `ispeed`, `rows`, etc.) are accessible as properties.\n- Setting an attribute updates the internal state and validates the value.\n\n---\n\n### Constants\n\n- `TCSANOW`, `TCSADRAIN`, `TCSAFLUSH`: the values accepted by the `when` named argument of `Stty.tofd()`. Compare with `termios.tcsetattr()`.\n- Symbolic constants for masks and values (e.g., `cs8`, `tab0`, etc.) are available as module attributes.\n\n---\n\n### Data\n\n- `settings`: A dictionary describing all available Stty attributes and their possible values on the current platform.\n\n---\n\n### Functions\n\n- `settings_help_str`: Return help string about all available Stty attributes and their possible values on the current platform.\n- `settings_help`: Print help message about all available Stty attributes and their possible values on the current platform.\n\n---\n\n## Compatibility\n\n- Requires Python 3.x and a POSIX-like system with the `termios` module.\n- Some features depend on platform support (e.g., window size).\n\n---\n\n## License\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\n---\n\n## Author\n\nSoumendra Ganguly, 2025\n\n---\n\n## See Also\n\n- [stty(1) manpage](https://man7.org/linux/man-pages/man1/stty.1.html)\n- [Python termios documentation](https://docs.python.org/3/library/termios.html)\n",
"bugtrack_url": null,
"license": "# Copyright (C) 2025 Soumendra Ganguly\n \n # This program is free software: you can redistribute it and/or modify\n # it under the terms of the GNU General Public License as published by\n # the Free Software Foundation, either version 3 of the License, or\n # (at your option) any later version.\n \n # This program is distributed in the hope that it will be useful,\n # but WITHOUT ANY WARRANTY; without even the implied warranty of\n # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n # GNU General Public License for more details.\n \n # You should have received a copy of the GNU General Public License\n # along with this program. If not, see <https://www.gnu.org/licenses/>.",
"summary": "A Python library for manipulating terminal settings in the style of POSIX stty(1).",
"version": "0.0.5",
"project_urls": {
"Homepage": "https://github.com/8vasu/stty.py",
"Issues": "https://github.com/8vasu/stty.py/issues"
},
"split_keywords": [
"terminal",
" tty",
" stty",
" termios",
" winsize",
" posix",
" terminal-settings",
" pseudo-terminal",
" pty",
" terminal-attributes"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "34b39693f631cc78ad3c09ce7dc2e76d23f6b39a53c829ac04f30e8e49472344",
"md5": "a717843965cd6789400d2ebb439f6840",
"sha256": "a4af60d84df47f6bfc2929922f36a1aee5d52e50c138cb984117cf062643c118"
},
"downloads": -1,
"filename": "stty-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a717843965cd6789400d2ebb439f6840",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 14983,
"upload_time": "2025-09-14T17:35:22",
"upload_time_iso_8601": "2025-09-14T17:35:22.518390Z",
"url": "https://files.pythonhosted.org/packages/34/b3/9693f631cc78ad3c09ce7dc2e76d23f6b39a53c829ac04f30e8e49472344/stty-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "299a96c9468e2a2ad751da8a1acabc2f2dbd8d427f5f66518d43bd564f148232",
"md5": "e369fff93826b82a793754ac9c6b7fcb",
"sha256": "3b03d86d081c9fc6e0af9fa2d4dc9e5ca676cecec64a85905f0a75695ef69c37"
},
"downloads": -1,
"filename": "stty-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "e369fff93826b82a793754ac9c6b7fcb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 13111,
"upload_time": "2025-09-14T17:35:23",
"upload_time_iso_8601": "2025-09-14T17:35:23.728746Z",
"url": "https://files.pythonhosted.org/packages/29/9a/96c9468e2a2ad751da8a1acabc2f2dbd8d427f5f66518d43bd564f148232/stty-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-14 17:35:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "8vasu",
"github_project": "stty.py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "stty"
}
