# Termighty
### High-level utilities for cross-platform terminal interaction.
Termighty is a Python package that provides a comprehensive set of tools for managing and customizing the terminal environment, as well as handling user inputs and creating dynamic text displays. It consists of several classes, each serving specific purposes.
The Term class offers commands for modifying the terminal state, managing multiple buffers, and controlling terminal output. It includes methods for initializing the class, playing the terminal bell sound, clearing the terminal screen, hiding and showing the cursor, moving and saving the cursor position, and writing to the terminal.
The String class is an advanced version of Python's built-in str class, designed to handle ANSI Escape Sequences for custom text and background colors, as well as text styles. It provides methods for listing available styles, creating instances with specific colors and styles, and implementing magic methods to use the String class like a built-in string.
The Color class manages colors in RGB format and can be used in conjunction with the String class or for modifying terminal background and foreground colors directly. It supports many operations between colors, unary operations on colors, and color instantiation from a comprehensive catalog of colors.
The GetchIterator class is designed to iterate over a Listener's history, yielding all new additions to the history until the Listener is stopped. The Listener class, a superclass that must be inherited before instantiation, allows users to display live, dynamic text on the terminal while simultaneously accepting user inputs.
The TextBox class provides a base for rectangular shapes (with or without text) that display on the terminal. It simplifies and standardizes the creation of more complex objects. The TextEditor class, a subclass of TextBox, emulates a fully-functional word processor with advanced features such as cursor positioning, and text selection.
In summary, Termighty is a powerful package that enables developers to create customized terminal experiences with enhanced text manipulation, user input handling, and dynamic displays.
# Class Documentation: System
The `System` class is used to keep track of the terminal dimensions and detect the current OS. It also contains the `kill_all` class attribute, which is by default set to `False`. If it is set to `True`, all active Termighty threads will be killed.
## Attributes
### terminal_size: tuple[int, int]
Stores the terminal dimensions (width and height) as a tuple.
### os
Stores the name of the current operating system.
### escape_code_encoding
Stores the encoding type of escape codes, based on the operating system.
### kill_all
A boolean attribute that, if set to `True`, stops all processes.
## Methods
### track_terminal_shape(cls)
A class method that tracks the terminal size in a loop, updating the `terminal_size` attribute whenever the terminal dimensions change. The loop will run until `kill_all` is set to `True`. The method has a sleep time of `0.05` seconds to prevent excessive CPU usage.
## Threading
### track_terminal_shape_thread
A daemon thread created to run the `track_terminal_shape` method in the background. The thread will start automatically when the module is imported.
# Class Documentation: Term
The `Term` class is a collection of commands that can be used to make modifications to the terminal state. It allows for the existence of multiple buffers that each can be flushed and appended independently of others. By default, methods that write to the terminal are not set to flush the buffer when called, which improves performance. However, if the flush parameter is set to True, then the buffer is bypassed and the command outputs immediately to the terminal.
## Methods
### __init__(self, flush: bool = False) -> None
The constructor method initializes the instance variables needed for the class.
### bell(self, flush: bool = False) -> None
Play the terminal bell sound.
### clear(self, flush: bool = False) -> None
Clears the terminal screen.
### cursor_hide(self, flush: bool = False) -> None
Make the cursor invisible.
### cursor_load(self, flush: bool = False) -> None
Load the cursor position.
### cursor_move(self, line: int, column: int, flush: bool = False) -> None
Move the cursor to the given line and column.
### cursor_save(self, flush: bool = False) -> None
Save the cursor position.
### cursor_show(self, flush: bool = False) -> None
Make the cursor visible.
### flush(self) -> None
Flush the entire buffer to the terminal.
### flush_string(self, string: str) -> None
Write and flush the given string to the terminal.
### write(self, line: int, column: int, string: str, flush: bool = False) -> None
Write the given string starting at the designated line and column coordinates to the buffer.
# Class Documentation: String
The String class is a more advanced version of the built-in `str` class, which can handle ANSI Escape Sequences indirectly through calling various methods. These methods allow for custom text and background colors, as well as text styles. Most methods for `str` class function, such as `string.partition()`, `string.strip()`, etc.
## Class Methods
### list_styles() -> str
Return a list of all available styles (as viewable ANSI escape sequences) and their names. Remember to print the outputted string if you want to view the list in the terminal.
## Constructor
### __init__(string: str, foreground: Optional[Union[str, Color, tuple[int, int, int]]] = None, background: Optional[Union[str, Color, tuple[int, int, int]]] = None, style: Optional[str] = None) -> None
Create an instance of class String. Arguments foreground and background should be the names of known colors, or instances of Color. Argument style should be the name of a known style in /data/styles.json.
## Magic Methods
Several magic methods are implemented for the String class, allowing it to be used in a similar way to a built-in string. Magic methods include: `__add__`, `__format__`, `__getitem__`, `__iter__`, `__mul__`, `__next__`, `__radd__`, `__repr__`, `__rmul__`, `__set__`, and `__str__`.
## Properties
### background -> Color
Return a copy of the Color instance assigned to the current background.
### foreground -> Color
Return a copy of the Color instance assigned to the current foreground.
### string -> str
Return the uncolored and unformatted text currently assigned to this `String` instance.
### style -> str
Return the name of the text style associated with the current instance.
## Setter Methods
### background.setter(color: Optional[Union[str, Color, tuple[int, int, int]]] = None) -> None
Set the background color to a new value. Accepts the name of a color as a string, or an instance of `Color`, or a tuple containing three integers in the range [0, 255] representing RGB color channels.
### foreground.setter(color: Optional[Union[str, Color, tuple[int, int, int]]] = None) -> None
Set the foreground color to a new value. Accepts the name of a color as a string, or an instance of `Color`, or a tuple containing three integers in the range [0, 255] representing RGB color channels.
### string.setter(data: str) -> None
Overwrite the uncolored and unformatted text currently assigned to this `String` instance.
### style.setter(style: Optional[str] = None) -> None
Set the style to a new value.
# Class: Color
The Color class manages colors in RGB format for use in instances of the `String` class, or for modifying terminal background and foreground colors directly. It supports many operations between colors, as well as unary operations like adding and subtracting colors (by RGB value) or taking a color's negative.
Colors can be instantiated directly by inputting an RGB value (and optional color name), or they may be generated from a comprehensive catalog of colors using the classmethod `Color.palette` (the full catalog can be printed as a guide by executing the class method `Color.list_colors`).
## Class Methods:
### chart(r: Optional[int], g: Optional[int], b: Optional[int], term_width: int) -> str
Returns a terminal-printable color chart. Set exactly ONE of the parameters `r`, `g`, and `b` to a value in the range [0, 255], and the others must be set to None as they will be iterated over. Argument `term_width` should be a positive nonzero integer.
### is_color(name: str) -> bool
Returns True if `/data/rgb.json` contains the given string. Can be used to check whether or not a color you want to instantiate is included in Termighty.
### list_colors(sort_by="step") -> str
Returns a string containing a list of all available colors (as viewable ANSI escape sequences) and their names. Remember to print the outputted string if you want to view the list in the terminal.
### palette(name: str) -> "Color"
Initializes a `Color` instance using a color name; only succeeds if the name is found in `/data/rgb.json`.
## Properties:
### sample -> str
Returns a color sample in the form of a printable string, consisting of a single whitespace character with the background color set to that of the current instance of class Color.
## Constructor:
### init(self, rgb: Sequence[int], name: str = "Unnamed Color") -> None
Initializes a new instance of the `Color` class. Argument `rgb` should be a sequence containing three integers in the range [0, 255].
## Magic Methods:
### add(self, color: "Color") -> "Color"
Adds colors together by summing their RGB values.
### call(self, string: str) -> str
Returns the given string, but with the text colored using the current instance's RGB values.
### hash(self) -> int
Returns a unique hash for the combination of `rgb` values of the current Color instance.
### repr(self) -> str
Returns a color sample from the current instance that is machine-readable.
### str(self) -> str
Returns the current instance's color name, RGB value, and a sample of the color as a formatted human-readable multiline string.
### sub(self, color: "Color") -> "Color"
Subtracts colors from each other by subtracting their RGB values.
## Properties (Getters/Setters):
### b -> int
Returns the current instance's blue RGB value.
### g -> int
Returns the current instance's green RGB value.
### name -> str
Returns the current instance's color name.
### r -> int
Returns the current instance's red RGB value.
### rgb -> tuple[int, int, int]
Returns the current instance's RGB values as a tuple of integers.
## Public Methods:
### brightness(self) -> int
Returns the mean of the RGB values, which can be considered a measure of the color's brightness.
### copy(self) -> "Color"
Returns a deep copy of the current instance.
### hsv(self) -> tuple[float, float, float]
Return the color of the current instance in HSV form, which converts the red, green, and blue color channels to their equivalent hue, saturation, and brightness. HSV is a representation of color that attempts to more closely represent the way that human vision interprets color.
### lightness(self, weighted: bool = True) -> float
Return the norm of the RGB vector as fraction of 255. Should return a float in the range 0 to 1.
If weighted, multiply the squares of the `R`, `G`, and `B` color channels by 0.299, 0.587, and 0.114, respectively.
Source of weights: http://alienryderflex.com/hsp.html
### negative(self) -> "Color"
Return the color negative of the current instance, which is the element-wise difference (255-R, 255-G, 255-B), where `R`, `G`, and `B` are the current instance's color channels.
# Class: GetchIterator
The `GetchIterator` class is designed to be used in a for-loop to iterate over the `Listener`'s history, starting at the provided index, and continuously yielding all new additions to the history until the `Listener` is stopped.
## Methods
### __init__(self, idx: Optional[int] = None)
Initializes the GetchIterator object, preparing the indices for the iteration if they are given.
### __iter__(self)
Sets the start index for the iterator based on the current length of the Listener history if the index is not provided. Otherwise, it uses the given index.
### __next__(self)
Returns the next input detected by the Listener and appended to its history.
# Class: Listener
The `Listener` class is a superclass that allows users to display live, dynamic text on the terminal while simultaneously accepting user inputs. It must be inherited before instantiation, and the `_writer` attribute must be overwritten. The overwritten `_writer` should contain the main loop displayed to the terminal.
Only one instance of `Listener` may be active at once.
## Class Attributes
### _active
A boolean indicating whether the `Listener` is active.
### _escape_hits
The number of consecutive Esc key presses needed to stop the `Listener`.
### _history
A list of the user's input history.
### _raw
A boolean indicating whether the `Listener` should return raw escape codes or interpret them.
### _sleep_time
The time in seconds the `Listener` should sleep between input checks.
## Class Methods
### _getch_linux()
Listens for keyboard input on Linux systems and returns a string with a key name.
### _getch_windows()
Listens for keyboard input on Windows systems and returns a string with a key name.
### _interpret_escape_code(escape_code: bytes) -> str
Returns a character or command from the given escape code.
### _listener()
A method for updating the global `input_state` variable by appending the latest keypress to it (interpreted by `data/keymaps`).
Expects `_raw_mode` to be True, implying the terminal will read user inputs immediately without echoing to the
terminal.
To kill all running threads, hold key `ESC` for a few seconds, or hit it as many times in a row as the value
given in `cls._escape_hits` -- be sure not to press any other keys in between or the kill process is interrupted.
### _listener_raw()
A method for updating the global `input_state` variable by appending the latest keypress to it (as an ANSI escape sequence or character).
### _raw_mode_linux(state: bool)
Sets the terminal to raw mode on Linux systems if state is True, or to echo mode if state is False.
### _raw_mode_windows(state: bool)
Windows placeholder for raw mode, which is only necessary on Linux systems.
## Public Methods
### getch_iterator(cls, idx: Optional[int] = None, keytest: bool = False) -> GetchIterator
Returns a `GetchIterator` object for the given index.
### start(cls, raw: bool = False)
Activates the `Listener` session. If raw is True, the listener will return raw escape codes instead of interpreting them.
### stop(cls)
Deactivates the `Listener` session.
## OS-Specific Methods
### _getch
Alias for `_getch_linux` on Linux systems, and `_getch_windows` on Windows systems.
### _raw_mode
Alias for `_raw_mode_linux` on Linux systems, and `_raw_mode_windows` on Windows systems.
### _fd
File descriptor for the terminal input on Linux systems.
### _old_settings
The terminal's old settings on Linux systems.
# Class: TextBox
The `TextBox` class provides a base for rectangular shapes (that may or may not contain text) that display on the terminal. It is used to simplify and standardize more complex objects.
Magic Methods
## Constructor
### __init__(self, row_start: int, col_start: int, row_end: int, col_end: int, wrap_text: bool = False, wrap_subsequent_indent: str = "", wrap_text_break_on_hyphens: bool = True, wrap_text_break_long_words: bool = True, background: Optional[Union[str, Color]] = None, foreground: Optional[Union[str, Color]] = None, style: Optional[str] = None, alignment: Literal["left", "right", "center"] = "left", view: tuple[int, int] = (0, 0),) -> None
Return a new instance of class `TextBox` at the specified coordinates. If negative coordinates are given, they will be set dynamically relative to the size of the terminal; a thread will loop in the background keeping track of the terminal dimensions and resizing the `TextBox` if its coordinates are dynamic.
### __call__(self, text: Union[str, list[str, ...]]) -> None
This method modifies the current state of the `TextBox` by replacing its contents with the given text. It accepts a single string or a list of strings. If a list is given, each element will be placed in its own row within the `TextBox`. However, it does not support the use of strings containing ANSI escape sequences.
### _process_text(self) -> None
This method justifies the raw text given to the __call__ method such that all lines of text are equally-sized and wide enough to allow for the view of the text to be moved left, right, up, and down until the text is just out of view. It takes the `_alignment` attribute into account, aligning the text either to the left, right, or center of the `TextBox`.
### _init_color_attributes(self, background: Color, foreground: Color, style: str) -> None
This method prepares all the required instance attributes, such as colors, style, and the resulting ANSI sequences that will be used to correctly display the text with these colors and styles.
### _init_spacial_attributes(self, row_start: int, col_start: int, row_end: int, col_end: int, view: tuple[int, int]) -> None
This method initializes attributes that are related to the `TextBox` shape, position within the terminal, and the position of its contents. This includes the coordinates of the `TextBox` corners (user-defined), the initial size of the terminal, as obtained by the `System` class, and the window view, set to (0,0) by default.
### _process_text_wrapper(self) -> None
This method sets up the text wrapper.
### _init_arguments(self, background: Union[str, Color, tuple[int, int, int]], foreground: Union[str, Color, tuple[int, int, int]], style: str, defaults: tuple[Color, Color, str], argnames: tuple[str, str, str]) -> tuple[Color, Color, str]
This method performs checks making sure that the initialization arguments are correctly set up. It confirms that the `TextBox` dimensions are correctly set up (`start` < `end`), that the given background & foreground colors are valid, and that the given style is valid.
### _run_thread(self, dt: float) -> None
This method keeps updating the window every `dt` seconds and accounts for changes in the terminal size (useful when dealing with relative coordinates on initialization).
### _set_shape(self) -> None
This method sets the size of the `TextBox` to those given by the user at instantiation. If the terminal size is smaller than the `TextBox` size, it will decrease the `TextBox` size to make it fit in the terminal. It also accounts for negative size instantiation values; if a value is negative, it is subtracted from the terminal size (from the axis in question).
### _set_view(self) -> None
This method limits the view to prevent out of bounds errors by using commands min and max with the `TextBox` dimensions.
## Public Methods
### start(self, dt: float = 0.005) -> None
This method activates a thread that runs the method `_run_thread`.
### stop(self) -> None
This method kills the active thread.
### alignment(self, mode: str) -> None
This method sets the `TextBox` text alignment mode.
# TextEditor Class
`TextEditor` is a subclass of `TextBox` that emulates a fully-functional word processor. It uses class Listener to detect keyboard inputs and supports the following advanced functions:
* Cursor positioning with the arrow keys
* Ctrl-arrow key to move the cursor to the beginning/end of words
* Alt-arrow to select text
* Deletion of selected text
* Copying & pasting of selected text.
## Constructor
### __init__(self, row_start: int, col_start: int, row_end: int, col_end: int, wrap_text: bool = False, wrap_subsequent_indent: str = "", line_numbers: bool = False, background: Union[str, Color, tuple[int, int, int]] = None, foreground: Union[str, Color, tuple[int, int, int]] = None, style: Optional[str] = None, select_background: Union[str, Color, tuple[int, int, int]] = None, select_foreground: Union[str, Color, tuple[int, int, int]] = None, select_style: Optional[str] = None, line_number_background: Union[str, Color, tuple[int, int, int]] = None, line_number_foreground: Union[str, Color, tuple[int, int, int]] = None, line_number_style: Optional[str] = None, vertical_scroll_buffer: Optional[int] = None, horizontal_scroll_buffer: Optional[int] = None, cursor_position: tuple[int, int] = (0, 0), frozen: bool = False,)
The constructor in class TextEditor creates an instance of TextEditor and initializes its attributes and those of its inherited TextBox.
## Methods
### _init_editor_attributes(self, cursor_position, frozen, line_numbers, select_background, select_foreground, select_style, line_number_background, line_number_foreground, line_number_style, selected=None)
Prepare all the instance attributes for selected text, such as colors, style, and the resulting ANSI sequences that will be used to correctly display the text with these colors and styles. Also initializes the coordinate list of selected text, set to an empty list by default.
### _process_text_wrapper(self)
Prepare the TextWrapper object that wraps text when it is too long to fit on one line. If line numbers are enabled, this method also determines the maximum width required for the line numbers.
### _run_getch_thread(self) -> None
Keeps updating the window every set number of seconds (given by dt) and accounts for changes in the terminal size (useful when dealing with relative coordinates on initialization).
### _set_scroll_buffer(self) -> None
If the vertical and/or horizontal scroll buffers are dynamic, changes them based on the current terminal dimensions.
### _set_view(self) -> None
Updates the current view of the text based on the current cursor position and selected text.
### start(self)
Main loop which runs on one thread, while a listener runs on another and provides commands to be read by this method. These inputs are accessed via the superclass attribute LiveMenu._input_state and are processed in an infinite loop until broken.
### freeze(self)
Freeze the TextEditor -- the getch_iterator in method _run_getch_thread will continue to run, but it will not act on the inputs and leave the window unchanged.
### unfreeze(self)
Unfreeze the TextEditor and reopen it to getch inputs.
### write(self) -> None
Writes the text to its designated coordinates with the view taken into account.
Raw data
{
"_id": null,
"home_page": "https://github.com/GabrielSCabrera/Termighty",
"name": "Termighty",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "terminal,xterm,gui,windows,linux",
"author": "Gabriel S. Cabrera",
"author_email": "gabriel.sigurd.cabrera@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fe/ca/d61e3d82a26562853468905c5a26695c7690cca02cfdf292daa227c67048/Termighty-3.0.5.tar.gz",
"platform": null,
"description": "# Termighty\r\n### High-level utilities for cross-platform terminal interaction.\r\n\r\nTermighty is a Python package that provides a comprehensive set of tools for managing and customizing the terminal environment, as well as handling user inputs and creating dynamic text displays. It consists of several classes, each serving specific purposes.\r\n\r\nThe Term class offers commands for modifying the terminal state, managing multiple buffers, and controlling terminal output. It includes methods for initializing the class, playing the terminal bell sound, clearing the terminal screen, hiding and showing the cursor, moving and saving the cursor position, and writing to the terminal.\r\n\r\nThe String class is an advanced version of Python's built-in str class, designed to handle ANSI Escape Sequences for custom text and background colors, as well as text styles. It provides methods for listing available styles, creating instances with specific colors and styles, and implementing magic methods to use the String class like a built-in string.\r\n\r\nThe Color class manages colors in RGB format and can be used in conjunction with the String class or for modifying terminal background and foreground colors directly. It supports many operations between colors, unary operations on colors, and color instantiation from a comprehensive catalog of colors.\r\n\r\nThe GetchIterator class is designed to iterate over a Listener's history, yielding all new additions to the history until the Listener is stopped. The Listener class, a superclass that must be inherited before instantiation, allows users to display live, dynamic text on the terminal while simultaneously accepting user inputs.\r\n\r\nThe TextBox class provides a base for rectangular shapes (with or without text) that display on the terminal. It simplifies and standardizes the creation of more complex objects. The TextEditor class, a subclass of TextBox, emulates a fully-functional word processor with advanced features such as cursor positioning, and text selection.\r\n\r\nIn summary, Termighty is a powerful package that enables developers to create customized terminal experiences with enhanced text manipulation, user input handling, and dynamic displays.\r\n\r\n# Class Documentation: System\r\n\r\nThe `System` class is used to keep track of the terminal dimensions and detect the current OS. It also contains the `kill_all` class attribute, which is by default set to `False`. If it is set to `True`, all active Termighty threads will be killed.\r\n\r\n## Attributes\r\n\r\n### terminal_size: tuple[int, int]\r\nStores the terminal dimensions (width and height) as a tuple.\r\n\r\n### os\r\nStores the name of the current operating system.\r\n\r\n### escape_code_encoding\r\nStores the encoding type of escape codes, based on the operating system.\r\n\r\n### kill_all\r\nA boolean attribute that, if set to `True`, stops all processes.\r\n\r\n## Methods\r\n\r\n### track_terminal_shape(cls)\r\n\r\nA class method that tracks the terminal size in a loop, updating the `terminal_size` attribute whenever the terminal dimensions change. The loop will run until `kill_all` is set to `True`. The method has a sleep time of `0.05` seconds to prevent excessive CPU usage.\r\n\r\n## Threading\r\n### track_terminal_shape_thread\r\n\r\nA daemon thread created to run the `track_terminal_shape` method in the background. The thread will start automatically when the module is imported.\r\n\r\n# Class Documentation: Term\r\n\r\nThe `Term` class is a collection of commands that can be used to make modifications to the terminal state. It allows for the existence of multiple buffers that each can be flushed and appended independently of others. By default, methods that write to the terminal are not set to flush the buffer when called, which improves performance. However, if the flush parameter is set to True, then the buffer is bypassed and the command outputs immediately to the terminal.\r\n\r\n## Methods\r\n\r\n### __init__(self, flush: bool = False) -> None\r\nThe constructor method initializes the instance variables needed for the class.\r\n\r\n### bell(self, flush: bool = False) -> None\r\nPlay the terminal bell sound.\r\n\r\n### clear(self, flush: bool = False) -> None\r\nClears the terminal screen.\r\n\r\n### cursor_hide(self, flush: bool = False) -> None\r\nMake the cursor invisible.\r\n\r\n### cursor_load(self, flush: bool = False) -> None\r\nLoad the cursor position.\r\n\r\n### cursor_move(self, line: int, column: int, flush: bool = False) -> None\r\nMove the cursor to the given line and column.\r\n\r\n### cursor_save(self, flush: bool = False) -> None\r\nSave the cursor position.\r\n\r\n### cursor_show(self, flush: bool = False) -> None\r\nMake the cursor visible.\r\n\r\n### flush(self) -> None\r\nFlush the entire buffer to the terminal.\r\n\r\n### flush_string(self, string: str) -> None\r\nWrite and flush the given string to the terminal.\r\n\r\n### write(self, line: int, column: int, string: str, flush: bool = False) -> None\r\nWrite the given string starting at the designated line and column coordinates to the buffer.\r\n\r\n# Class Documentation: String\r\n\r\nThe String class is a more advanced version of the built-in `str` class, which can handle ANSI Escape Sequences indirectly through calling various methods. These methods allow for custom text and background colors, as well as text styles. Most methods for `str` class function, such as `string.partition()`, `string.strip()`, etc.\r\n\r\n## Class Methods\r\n\r\n### list_styles() -> str\r\n\r\nReturn a list of all available styles (as viewable ANSI escape sequences) and their names. Remember to print the outputted string if you want to view the list in the terminal.\r\n\r\n## Constructor\r\n\r\n### __init__(string: str, foreground: Optional[Union[str, Color, tuple[int, int, int]]] = None, background: Optional[Union[str, Color, tuple[int, int, int]]] = None, style: Optional[str] = None) -> None\r\n\r\nCreate an instance of class String. Arguments foreground and background should be the names of known colors, or instances of Color. Argument style should be the name of a known style in /data/styles.json.\r\n\r\n## Magic Methods\r\n\r\nSeveral magic methods are implemented for the String class, allowing it to be used in a similar way to a built-in string. Magic methods include: `__add__`, `__format__`, `__getitem__`, `__iter__`, `__mul__`, `__next__`, `__radd__`, `__repr__`, `__rmul__`, `__set__`, and `__str__`.\r\n\r\n## Properties\r\n\r\n### background -> Color\r\nReturn a copy of the Color instance assigned to the current background.\r\n\r\n### foreground -> Color\r\nReturn a copy of the Color instance assigned to the current foreground.\r\n\r\n### string -> str\r\nReturn the uncolored and unformatted text currently assigned to this `String` instance.\r\n\r\n### style -> str\r\nReturn the name of the text style associated with the current instance.\r\n\r\n## Setter Methods\r\n\r\n### background.setter(color: Optional[Union[str, Color, tuple[int, int, int]]] = None) -> None\r\nSet the background color to a new value. Accepts the name of a color as a string, or an instance of `Color`, or a tuple containing three integers in the range [0, 255] representing RGB color channels.\r\n\r\n### foreground.setter(color: Optional[Union[str, Color, tuple[int, int, int]]] = None) -> None\r\nSet the foreground color to a new value. Accepts the name of a color as a string, or an instance of `Color`, or a tuple containing three integers in the range [0, 255] representing RGB color channels.\r\n\r\n### string.setter(data: str) -> None\r\nOverwrite the uncolored and unformatted text currently assigned to this `String` instance.\r\n\r\n### style.setter(style: Optional[str] = None) -> None\r\nSet the style to a new value.\r\n\r\n# Class: Color\r\n\r\nThe Color class manages colors in RGB format for use in instances of the `String` class, or for modifying terminal background and foreground colors directly. It supports many operations between colors, as well as unary operations like adding and subtracting colors (by RGB value) or taking a color's negative.\r\n\r\nColors can be instantiated directly by inputting an RGB value (and optional color name), or they may be generated from a comprehensive catalog of colors using the classmethod `Color.palette` (the full catalog can be printed as a guide by executing the class method `Color.list_colors`).\r\n\r\n## Class Methods:\r\n\r\n### chart(r: Optional[int], g: Optional[int], b: Optional[int], term_width: int) -> str\r\nReturns a terminal-printable color chart. Set exactly ONE of the parameters `r`, `g`, and `b` to a value in the range [0, 255], and the others must be set to None as they will be iterated over. Argument `term_width` should be a positive nonzero integer.\r\n\r\n### is_color(name: str) -> bool\r\nReturns True if `/data/rgb.json` contains the given string. Can be used to check whether or not a color you want to instantiate is included in Termighty.\r\n\r\n### list_colors(sort_by=\"step\") -> str\r\nReturns a string containing a list of all available colors (as viewable ANSI escape sequences) and their names. Remember to print the outputted string if you want to view the list in the terminal.\r\n\r\n### palette(name: str) -> \"Color\"\r\nInitializes a `Color` instance using a color name; only succeeds if the name is found in `/data/rgb.json`.\r\n\r\n## Properties:\r\n\r\n### sample -> str\r\nReturns a color sample in the form of a printable string, consisting of a single whitespace character with the background color set to that of the current instance of class Color.\r\n\r\n## Constructor:\r\n\r\n### init(self, rgb: Sequence[int], name: str = \"Unnamed Color\") -> None\r\nInitializes a new instance of the `Color` class. Argument `rgb` should be a sequence containing three integers in the range [0, 255].\r\n\r\n## Magic Methods:\r\n\r\n### add(self, color: \"Color\") -> \"Color\"\r\nAdds colors together by summing their RGB values.\r\n\r\n### call(self, string: str) -> str\r\nReturns the given string, but with the text colored using the current instance's RGB values.\r\n\r\n### hash(self) -> int\r\nReturns a unique hash for the combination of `rgb` values of the current Color instance.\r\n\r\n### repr(self) -> str\r\nReturns a color sample from the current instance that is machine-readable.\r\n\r\n### str(self) -> str\r\nReturns the current instance's color name, RGB value, and a sample of the color as a formatted human-readable multiline string.\r\n\r\n### sub(self, color: \"Color\") -> \"Color\"\r\nSubtracts colors from each other by subtracting their RGB values.\r\n\r\n## Properties (Getters/Setters):\r\n\r\n### b -> int\r\nReturns the current instance's blue RGB value.\r\n\r\n### g -> int\r\nReturns the current instance's green RGB value.\r\n\r\n### name -> str\r\nReturns the current instance's color name.\r\n\r\n### r -> int\r\nReturns the current instance's red RGB value.\r\n\r\n### rgb -> tuple[int, int, int]\r\nReturns the current instance's RGB values as a tuple of integers.\r\n\r\n## Public Methods:\r\n\r\n### brightness(self) -> int\r\nReturns the mean of the RGB values, which can be considered a measure of the color's brightness.\r\n\r\n### copy(self) -> \"Color\"\r\nReturns a deep copy of the current instance.\r\n\r\n### hsv(self) -> tuple[float, float, float]\r\nReturn the color of the current instance in HSV form, which converts the red, green, and blue color channels to their equivalent hue, saturation, and brightness. HSV is a representation of color that attempts to more closely represent the way that human vision interprets color.\r\n\r\n### lightness(self, weighted: bool = True) -> float\r\nReturn the norm of the RGB vector as fraction of 255. Should return a float in the range 0 to 1.\r\nIf weighted, multiply the squares of the `R`, `G`, and `B` color channels by 0.299, 0.587, and 0.114, respectively.\r\nSource of weights: http://alienryderflex.com/hsp.html\r\n\r\n### negative(self) -> \"Color\"\r\nReturn the color negative of the current instance, which is the element-wise difference (255-R, 255-G, 255-B), where `R`, `G`, and `B` are the current instance's color channels.\r\n\r\n# Class: GetchIterator\r\n\r\nThe `GetchIterator` class is designed to be used in a for-loop to iterate over the `Listener`'s history, starting at the provided index, and continuously yielding all new additions to the history until the `Listener` is stopped.\r\n\r\n## Methods\r\n\r\n### __init__(self, idx: Optional[int] = None)\r\nInitializes the GetchIterator object, preparing the indices for the iteration if they are given.\r\n\r\n### __iter__(self)\r\nSets the start index for the iterator based on the current length of the Listener history if the index is not provided. Otherwise, it uses the given index.\r\n\r\n### __next__(self)\r\nReturns the next input detected by the Listener and appended to its history.\r\n\r\n# Class: Listener\r\n\r\nThe `Listener` class is a superclass that allows users to display live, dynamic text on the terminal while simultaneously accepting user inputs. It must be inherited before instantiation, and the `_writer` attribute must be overwritten. The overwritten `_writer` should contain the main loop displayed to the terminal.\r\n\r\nOnly one instance of `Listener` may be active at once.\r\n\r\n## Class Attributes\r\n\r\n### _active\r\nA boolean indicating whether the `Listener` is active.\r\n\r\n### _escape_hits\r\nThe number of consecutive Esc key presses needed to stop the `Listener`.\r\n\r\n### _history\r\nA list of the user's input history.\r\n\r\n### _raw\r\nA boolean indicating whether the `Listener` should return raw escape codes or interpret them.\r\n\r\n### _sleep_time\r\nThe time in seconds the `Listener` should sleep between input checks.\r\n\r\n## Class Methods\r\n\r\n### _getch_linux()\r\nListens for keyboard input on Linux systems and returns a string with a key name.\r\n\r\n### _getch_windows()\r\nListens for keyboard input on Windows systems and returns a string with a key name.\r\n\r\n### _interpret_escape_code(escape_code: bytes) -> str\r\nReturns a character or command from the given escape code.\r\n\r\n### _listener()\r\nA method for updating the global `input_state` variable by appending the latest keypress to it (interpreted by `data/keymaps`).\r\n\r\nExpects `_raw_mode` to be True, implying the terminal will read user inputs immediately without echoing to the\r\nterminal.\r\n\r\nTo kill all running threads, hold key `ESC` for a few seconds, or hit it as many times in a row as the value\r\ngiven in `cls._escape_hits` -- be sure not to press any other keys in between or the kill process is interrupted.\r\n\r\n### _listener_raw()\r\nA method for updating the global `input_state` variable by appending the latest keypress to it (as an ANSI escape sequence or character).\r\n\r\n### _raw_mode_linux(state: bool)\r\nSets the terminal to raw mode on Linux systems if state is True, or to echo mode if state is False.\r\n\r\n### _raw_mode_windows(state: bool)\r\nWindows placeholder for raw mode, which is only necessary on Linux systems.\r\n\r\n## Public Methods\r\n\r\n### getch_iterator(cls, idx: Optional[int] = None, keytest: bool = False) -> GetchIterator\r\nReturns a `GetchIterator` object for the given index.\r\n\r\n### start(cls, raw: bool = False)\r\nActivates the `Listener` session. If raw is True, the listener will return raw escape codes instead of interpreting them.\r\n\r\n### stop(cls)\r\nDeactivates the `Listener` session.\r\n\r\n## OS-Specific Methods\r\n\r\n### _getch\r\nAlias for `_getch_linux` on Linux systems, and `_getch_windows` on Windows systems.\r\n\r\n### _raw_mode\r\nAlias for `_raw_mode_linux` on Linux systems, and `_raw_mode_windows` on Windows systems.\r\n\r\n### _fd\r\nFile descriptor for the terminal input on Linux systems.\r\n\r\n### _old_settings\r\nThe terminal's old settings on Linux systems.\r\n\r\n# Class: TextBox\r\n\r\nThe `TextBox` class provides a base for rectangular shapes (that may or may not contain text) that display on the terminal. It is used to simplify and standardize more complex objects.\r\nMagic Methods\r\n\r\n## Constructor\r\n\r\n### __init__(self, row_start: int, col_start: int, row_end: int, col_end: int, wrap_text: bool = False, wrap_subsequent_indent: str = \"\", wrap_text_break_on_hyphens: bool = True, wrap_text_break_long_words: bool = True, background: Optional[Union[str, Color]] = None, foreground: Optional[Union[str, Color]] = None, style: Optional[str] = None, alignment: Literal[\"left\", \"right\", \"center\"] = \"left\", view: tuple[int, int] = (0, 0),) -> None\r\nReturn a new instance of class `TextBox` at the specified coordinates. If negative coordinates are given, they will be set dynamically relative to the size of the terminal; a thread will loop in the background keeping track of the terminal dimensions and resizing the `TextBox` if its coordinates are dynamic.\r\n\r\n### __call__(self, text: Union[str, list[str, ...]]) -> None\r\nThis method modifies the current state of the `TextBox` by replacing its contents with the given text. It accepts a single string or a list of strings. If a list is given, each element will be placed in its own row within the `TextBox`. However, it does not support the use of strings containing ANSI escape sequences.\r\n\r\n### _process_text(self) -> None\r\nThis method justifies the raw text given to the __call__ method such that all lines of text are equally-sized and wide enough to allow for the view of the text to be moved left, right, up, and down until the text is just out of view. It takes the `_alignment` attribute into account, aligning the text either to the left, right, or center of the `TextBox`.\r\n\r\n### _init_color_attributes(self, background: Color, foreground: Color, style: str) -> None\r\nThis method prepares all the required instance attributes, such as colors, style, and the resulting ANSI sequences that will be used to correctly display the text with these colors and styles.\r\n\r\n### _init_spacial_attributes(self, row_start: int, col_start: int, row_end: int, col_end: int, view: tuple[int, int]) -> None\r\nThis method initializes attributes that are related to the `TextBox` shape, position within the terminal, and the position of its contents. This includes the coordinates of the `TextBox` corners (user-defined), the initial size of the terminal, as obtained by the `System` class, and the window view, set to (0,0) by default.\r\n\r\n### _process_text_wrapper(self) -> None\r\nThis method sets up the text wrapper.\r\n\r\n### _init_arguments(self, background: Union[str, Color, tuple[int, int, int]], foreground: Union[str, Color, tuple[int, int, int]], style: str, defaults: tuple[Color, Color, str], argnames: tuple[str, str, str]) -> tuple[Color, Color, str]\r\nThis method performs checks making sure that the initialization arguments are correctly set up. It confirms that the `TextBox` dimensions are correctly set up (`start` < `end`), that the given background & foreground colors are valid, and that the given style is valid.\r\n\r\n### _run_thread(self, dt: float) -> None\r\nThis method keeps updating the window every `dt` seconds and accounts for changes in the terminal size (useful when dealing with relative coordinates on initialization).\r\n\r\n### _set_shape(self) -> None\r\nThis method sets the size of the `TextBox` to those given by the user at instantiation. If the terminal size is smaller than the `TextBox` size, it will decrease the `TextBox` size to make it fit in the terminal. It also accounts for negative size instantiation values; if a value is negative, it is subtracted from the terminal size (from the axis in question).\r\n\r\n### _set_view(self) -> None\r\nThis method limits the view to prevent out of bounds errors by using commands min and max with the `TextBox` dimensions.\r\n\r\n## Public Methods\r\n\r\n### start(self, dt: float = 0.005) -> None\r\nThis method activates a thread that runs the method `_run_thread`.\r\n\r\n### stop(self) -> None\r\nThis method kills the active thread.\r\n\r\n### alignment(self, mode: str) -> None\r\nThis method sets the `TextBox` text alignment mode.\r\n\r\n# TextEditor Class\r\n\r\n`TextEditor` is a subclass of `TextBox` that emulates a fully-functional word processor. It uses class Listener to detect keyboard inputs and supports the following advanced functions:\r\n\r\n* Cursor positioning with the arrow keys\r\n* Ctrl-arrow key to move the cursor to the beginning/end of words\r\n* Alt-arrow to select text\r\n* Deletion of selected text\r\n* Copying & pasting of selected text.\r\n\r\n## Constructor\r\n### __init__(self, row_start: int, col_start: int, row_end: int, col_end: int, wrap_text: bool = False, wrap_subsequent_indent: str = \"\", line_numbers: bool = False, background: Union[str, Color, tuple[int, int, int]] = None, foreground: Union[str, Color, tuple[int, int, int]] = None, style: Optional[str] = None, select_background: Union[str, Color, tuple[int, int, int]] = None, select_foreground: Union[str, Color, tuple[int, int, int]] = None, select_style: Optional[str] = None, line_number_background: Union[str, Color, tuple[int, int, int]] = None, line_number_foreground: Union[str, Color, tuple[int, int, int]] = None, line_number_style: Optional[str] = None, vertical_scroll_buffer: Optional[int] = None, horizontal_scroll_buffer: Optional[int] = None, cursor_position: tuple[int, int] = (0, 0), frozen: bool = False,)\r\nThe constructor in class TextEditor creates an instance of TextEditor and initializes its attributes and those of its inherited TextBox.\r\n\r\n## Methods\r\n### _init_editor_attributes(self, cursor_position, frozen, line_numbers, select_background, select_foreground, select_style, line_number_background, line_number_foreground, line_number_style, selected=None)\r\nPrepare all the instance attributes for selected text, such as colors, style, and the resulting ANSI sequences that will be used to correctly display the text with these colors and styles. Also initializes the coordinate list of selected text, set to an empty list by default.\r\n\r\n### _process_text_wrapper(self)\r\nPrepare the TextWrapper object that wraps text when it is too long to fit on one line. If line numbers are enabled, this method also determines the maximum width required for the line numbers.\r\n\r\n### _run_getch_thread(self) -> None\r\nKeeps updating the window every set number of seconds (given by dt) and accounts for changes in the terminal size (useful when dealing with relative coordinates on initialization).\r\n\r\n### _set_scroll_buffer(self) -> None\r\nIf the vertical and/or horizontal scroll buffers are dynamic, changes them based on the current terminal dimensions.\r\n\r\n### _set_view(self) -> None\r\nUpdates the current view of the text based on the current cursor position and selected text.\r\n\r\n### start(self)\r\nMain loop which runs on one thread, while a listener runs on another and provides commands to be read by this method. These inputs are accessed via the superclass attribute LiveMenu._input_state and are processed in an infinite loop until broken.\r\n\r\n### freeze(self)\r\nFreeze the TextEditor -- the getch_iterator in method _run_getch_thread will continue to run, but it will not act on the inputs and leave the window unchanged.\r\n\r\n### unfreeze(self)\r\nUnfreeze the TextEditor and reopen it to getch inputs.\r\n\r\n### write(self) -> None\r\nWrites the text to its designated coordinates with the view taken into account.\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Cross-Platform Terminal Coloring, Formatting, and Management Utilities.",
"version": "3.0.5",
"split_keywords": [
"terminal",
"xterm",
"gui",
"windows",
"linux"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "830378864e45f4a9b6e6786ece018245e7e3681076d329d85731e87cd8b659c6",
"md5": "8bbd7dbbfb5c8e3011ec7f4353e9373f",
"sha256": "9141ac23ed35e389557669adfb96c437a82c29648442f7489959b766cd6acf68"
},
"downloads": -1,
"filename": "Termighty-3.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8bbd7dbbfb5c8e3011ec7f4353e9373f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 63834,
"upload_time": "2023-04-17T20:45:21",
"upload_time_iso_8601": "2023-04-17T20:45:21.312288Z",
"url": "https://files.pythonhosted.org/packages/83/03/78864e45f4a9b6e6786ece018245e7e3681076d329d85731e87cd8b659c6/Termighty-3.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fecad61e3d82a26562853468905c5a26695c7690cca02cfdf292daa227c67048",
"md5": "a2fe3d30df639a9d1c8d9994562059bf",
"sha256": "81ba790f559b7d9d85a91b3f7e52bba75443e93cc8997727a2058971de39d653"
},
"downloads": -1,
"filename": "Termighty-3.0.5.tar.gz",
"has_sig": false,
"md5_digest": "a2fe3d30df639a9d1c8d9994562059bf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 65145,
"upload_time": "2023-04-17T20:45:23",
"upload_time_iso_8601": "2023-04-17T20:45:23.286804Z",
"url": "https://files.pythonhosted.org/packages/fe/ca/d61e3d82a26562853468905c5a26695c7690cca02cfdf292daa227c67048/Termighty-3.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-17 20:45:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "GabrielSCabrera",
"github_project": "Termighty",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "termighty"
}
JSON
