Metadata-Version: 2.4
Name: terminal-conio
Version: 0.1.0
Summary: In-place terminal rendering for Python — a conio.h port with double-buffered dirty-cell rendering
Project-URL: Homepage, https://github.com/yourname/terminal-conio
Project-URL: Repository, https://github.com/yourname/terminal-conio
Project-URL: Issues, https://github.com/yourname/terminal-conio/issues
Author-email: Your Name <you@example.com>
License: MIT
Keywords: ansi,cli,conio,console,cursor,ncurses,rendering,terminal,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

**terminal.py · conio.py**

In-place terminal rendering for Python

**Python** 3.8+ **Platform** Windows · macOS · Linux **Deps** zero

**What is this?**

A pure-Python library that replicates the core of C\'s conio.h /
platform_conio.h and adds a double-buffered, dirty-cell terminal
renderer on top --- so you can build live-updating TUI applications
without flickering, full-screen clears, or third-party dependencies.

Two files, drop them into your project:

- conio.py --- low-level primitives: getch, kbhit, gotoxy, textcolor,
  clrscr ...

- terminal.py --- high-level double-buffered renderer built on top of
  conio.py

**The Core Idea**

Classic terminal rendering problems: either you clear the whole screen
every frame (causes flicker) or you manually track every xy position (a
thousand gotoxy calls). This library solves both with a front/back
buffer pair --- identical to how ncurses works.

  --------------------------------------------
  **Step**   **What happens**     **Cost**
  ---------- -------------------- ------------
  1\. Draw   Write into the back  Pure Python
             buffer               list writes
                                  --- instant

  2\. Diff   Compare back vs      Only changed
             front buffer         cells emit
                                  cursor
                                  moves +
                                  chars

  3\. Flush  One                  One syscall
             sys.stdout.write()   per frame
                                  regardless
                                  of size
  --------------------------------------------

**Quick Start**

**Installation**

No pip install --- just copy the files into your project:

> cp terminal.py conio.py your_project/

**Minimal example**

> from terminal import Terminal, Color
>
> t = Terminal()
>
> t.print(0, 0, \'Hello, world!\', fg=Color.YELLOW)
>
> t.render() \# only writes changed cells
>
> \# next frame --- only the changed region is redrawn
>
> t.print(0, 0, \'Hello, Python!\', fg=Color.YELLOW)
>
> t.render()

**Game loop pattern**

> import time
>
> from terminal import Terminal, Color
>
> from conio import kbhit, getch
>
> with Terminal() as t: \# hides cursor automatically
>
> while True:
>
> if kbhit() and getch() == \'q\':
>
> break
>
> t.clear() \# wipe back buffer (free --- no I/O)
>
> draw_everything(t) \# paint into back buffer (free --- no I/O)
>
> t.render() \# diff + write only dirty cells
>
> time.sleep(1/30) \# \~30 fps

**terminal.py API**

**Constructor**

> t = Terminal(width=None, height=None)

Auto-detects terminal size via shutil.get_terminal_size(). Pass explicit
values to override.

**Drawing (writes to back buffer --- zero I/O)**

  ---------------------------------
  **Method**     **Description**
  -------------- ------------------
  t.put(col,     Write one
  row, char, fg, character
  bg, bold)      

  t.print(col,   Write a string
  row, text, fg, 
  bg, bold)      

  t.hline(col,   Horizontal line
  row, length,   
  char, fg, bg)  

  t.vline(col,   Vertical line
  row, length,   
  char, fg, bg)  

  t.box(col,     Border box.
  row, w, h, fg, style=\'single\'
  bg, style)     or \'double\'

  t.fill(col,    Flood-fill a
  row, w, h,     rectangle
  char, fg, bg)  

  t.clear(fg,    Clear the entire
  bg)            back buffer
  ---------------------------------

**Rendering (touches the terminal)**

  -----------------------------------
  **Method**        **Description**
  ----------------- -----------------
  t.render()        Diff buffers and
                    write only
                    changed cells

  t.hide_cursor()   Hide the terminal
                    cursor

  t.show_cursor()   Restore the
                    terminal cursor

  t.resize()        Re-detect size
                    and rebuild
                    buffers
  -----------------------------------

**Context manager**

Using with Terminal() as t: automatically hides the cursor on entry and
restores it (plus moves the cursor below the drawn area) on exit ---
even if an exception is raised.

**conio.py API**

Low-level primitives that mirror conio.h. Can be used standalone without
terminal.py.

**Input**

  --------------------------------------------------------
  **Function**            **conio.h      **Description**
                          equivalent**   
  ----------------------- -------------- -----------------
  getch()                 getch()        Read one char, no
                                         Enter, no echo

  getche()                getche()       Read one char, no
                                         Enter, echoes
                                         char

  kbhit()                 kbhit()        True if a key is
                                         waiting in the
                                         buffer

  putch(ch)               putch(c)       Write one
                                         character to
                                         stdout

  ungetch(ch)             ungetch(c)     Push character
                                         back into input
                                         buffer

  getpass_conio(prompt)   ---            Password input
                                         (hides chars,
                                         supports
                                         backspace)
  --------------------------------------------------------

**Screen**

  -----------------------------------------------
  **Function**   **conio.h      **Description**
                 equivalent**   
  -------------- -------------- -----------------
  clrscr()       clrscr()       Clear the
                                terminal screen

  gotoxy(x, y)   gotoxy(x, y)   Move cursor
                                (1-based, like
                                conio.h)

  wherex()       wherex()       Current cursor
                                column (1-based)

  wherey()       wherey()       Current cursor
                                row (1-based)
  -----------------------------------------------

**Color**

  ---------------------------------------------------------
  **Function**        **conio.h           **Description**
                      equivalent**        
  ------------------- ------------------- -----------------
  textcolor(c)        textcolor(c)        Set foreground
                                          color using
                                          Color.\*

  textbackground(c)   textbackground(c)   Set background
                                          color using
                                          Color.\*

  normvideo()         normvideo()         Reset to terminal
                                          defaults

  highvideo()         highvideo()         Enable
                                          bright/bold text

  lowvideo()          lowvideo()          Switch to dim
                                          variant of
                                          current color

  cprintf(text, fg,   cprintf(\...)       Print with
  bg, end)                                colors, then
                                          restore previous
                                          colors

  cputs(text)         cputs(s)            Write string to
                                          stdout, no
                                          newline
  ---------------------------------------------------------

**Color constants (Color.\*)**

16 named constants matching the classic DOS/conio palette:

> BLACK BLUE GREEN CYAN RED MAGENTA YELLOW WHITE DARK_GRAY LIGHT_BLUE
> LIGHT_GREEN LIGHT_CYAN LIGHT_RED LIGHT_MAGENTA BRIGHT_YELLOW
> BRIGHT_WHITE

**Platform Notes**

  -----------------------------------------------------------
  **Feature**   **Windows**               **macOS / Linux**
  ------------- ------------------------- -------------------
  Input (getch  msvcrt                    termios + tty
  / kbhit)                                

  Cursor        Win32 Console API         ANSI DSR escape
  position      (ctypes)                  \\033\[6n

  Color         SetConsoleTextAttribute   ANSI escape
                                          sequences

  Cursor        SetConsoleCursorInfo      \\033\[?25l /
  show/hide                               \\033\[?25h

  Screen clear  os.system(\'cls\')        \\033\[2J\\033\[H
  -----------------------------------------------------------

**Note:** terminal.py uses ANSI escape sequences for all rendering, so
it targets any terminal emulator that supports ANSI (virtually
everything on macOS/Linux; Windows Terminal and modern cmd.exe on
Windows).

**Files**

  ------------------------------------
  **File**           **Purpose**
  ------------------ -----------------
  terminal.py        Double-buffered
                     renderer --- main
                     library

  conio.py           Low-level conio.h
                     primitives

  demo_terminal.py   Live demo:
                     bouncing ball,
                     sine wave, clock,
                     progress bar

  demo_conio.py      Color palette,
                     cursor
                     positioning,
                     password input
                     demo
  ------------------------------------
