# 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)
---
## Installation
This is a pure Python library. Place `stty.py` in your project or install via your preferred method.
---
## 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)
```
---
## 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 a dictionary of all current settings.
- `set(**opts)`
Set multiple attributes at once.
- `save(path: str = None)`
Save settings to a JSON file, or return a deep copy if no path is given.
- `load(path: str)`
Load settings from a JSON file.
- `fromfd(fd: int)`
Load settings from a file descriptor.
- `tofd(fd: int, when=TCSANOW, apply_termios=True, apply_winsize=True)`
Apply settings to a file descriptor.
- `evenp(plus=True)`
Set/unset even parity mode.
- `oddp(plus=True)`
Set/unset odd parity mode.
- `raw()`
Set terminal to raw mode.
- `nl(plus=True)`
Set/unset nl combination mode.
- `ek()`
Set ek combination mode.
- `openpty(apply_termios=True, apply_winsize=True)`
Open a new pseudo-terminal pair and apply settings.
- `forkpty(apply_termios=True, apply_winsize=True)`
Fork a new process with a pseudo-terminal and apply settings.
**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.9",
"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/e3/2c/32fe1f9a23763985e4e796fcf3e6f72cf669d1443cfb16fa653ea5fe4e38/stty-0.0.2.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## Installation\n\nThis is a pure Python library. Place `stty.py` in your project or install via your preferred method.\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## 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 a dictionary of all current settings.\n\n- `set(**opts)`\n Set multiple attributes at once.\n\n- `save(path: str = None)`\n Save settings to a JSON file, or return a deep copy if no path is given.\n\n- `load(path: str)`\n Load settings from a JSON file.\n\n- `fromfd(fd: int)`\n Load settings from a file descriptor.\n\n- `tofd(fd: int, when=TCSANOW, apply_termios=True, apply_winsize=True)`\n Apply settings to a file descriptor.\n\n- `evenp(plus=True)`\n Set/unset even parity mode.\n\n- `oddp(plus=True)`\n Set/unset odd parity mode.\n\n- `raw()`\n Set terminal to raw 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 pseudo-terminal pair and apply settings.\n\n- `forkpty(apply_termios=True, apply_winsize=True)`\n Fork a new process with a pseudo-terminal and apply settings.\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.2",
"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": "5ac530357a7ffb24721f4123d01f8a9cbfa400ca557f50427d06411fc22349d3",
"md5": "0ec7e180ef13849d80bb62403b470b6e",
"sha256": "45e0e76dc85350f9e1cb9a04cd06d494e87abd5604b2eb20bc63601b740310fb"
},
"downloads": -1,
"filename": "stty-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0ec7e180ef13849d80bb62403b470b6e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 14173,
"upload_time": "2025-08-25T03:30:02",
"upload_time_iso_8601": "2025-08-25T03:30:02.958839Z",
"url": "https://files.pythonhosted.org/packages/5a/c5/30357a7ffb24721f4123d01f8a9cbfa400ca557f50427d06411fc22349d3/stty-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e32c32fe1f9a23763985e4e796fcf3e6f72cf669d1443cfb16fa653ea5fe4e38",
"md5": "be012f286c72af5094554198e4632a01",
"sha256": "3163e13c2a034c7c09f0dc318994c0dc52c2cfcbefdd6632eace41713d81e0ac"
},
"downloads": -1,
"filename": "stty-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "be012f286c72af5094554198e4632a01",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12427,
"upload_time": "2025-08-25T03:30:03",
"upload_time_iso_8601": "2025-08-25T03:30:03.956871Z",
"url": "https://files.pythonhosted.org/packages/e3/2c/32fe1f9a23763985e4e796fcf3e6f72cf669d1443cfb16fa653ea5fe4e38/stty-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-25 03:30:03",
"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"
}
