curses — 문자 셀 디스플레이용 터미널 처리

curses 모듈은 curses 라이브러리에 대한 인터페이스를 제공해요. curses는 이식 가능한 고급 터미널 처리의 사실상 표준(de-facto standard)이죠.

출처: Python 표준 라이브러리

본문

curses는 Unix 환경에서 가장 널리 쓰이지만, Windows, DOS, 그 외 다른 시스템용 버전도 존재해요. 이 확장 모듈은 Linux와 BSD 계열 Unix에서 호스팅되는 오픈소스 curses 라이브러리인 ncurses의 API와 일치하도록 설계됐어요. 모바일 플랫폼이나 WebAssembly 플랫폼에서는 지원되지 않아요. Unix 계열에서 사용 가능하죠. 선택적(optional) 모듈입니다.

[!NOTE] 참고 문서에서 "문자(character)"를 언급할 때마다 그것은 정수, 한 문자 유니코드 문자열, 또는 한 바이트 바이트 문자열로 지정할 수 있어요. 정수는 단일 인코딩된 바이트의 코드이며, 선택적으로 속성 및 컬러 페어와 결합된 값이에요(window.inch()가 반환하는 값처럼). 문서에서 "문자열(character string)"을 언급할 때마다 유니코드 문자열이나 바이트 문자열로 지정할 수 있습니다.

[!NOTE] 참고 curses를 여러 스레드에서 사용할 수 있는지 여부는 기반 라이브러리와 그것이 어떻게 빌드됐느냐에 따라 달라요. 여러 구현에서 불가능할 수 있으니 주의하세요.

함수

curses 모듈은 여러 함수를 정의해요. 주요 함수들은 다음과 같습니다.

curses.initscr() — 스크립트의 진입점에서 터미널을 초기화하고 화면 전체를 나타내는 window 객체를 반환해요. 일반적으로 프로그램 종료 시 curses.endwin()을 호출해 터미널을 원래 상태로 복원하는 걸 잊지 마세요.
curses.endwin() — 터미널을 원래 상태로 되돌려요.
curses.cbreak(), curses.nocbreak() — cbreak 모드를 켜고 끄세요. cbreak 모드에서는 입력이 한 글자씩 즉시 처리되고 신호 키도 즉시 전달돼요.
curses.echo(), curses.noecho() — 입력된 문자를 화면에 다시 표시할지(echo) 제어해요.
curses.raw(), curses.noraw() — raw 모드를 켜고 꺼요. raw 모드는 cbreak 모드보다 더 강해서, Ctrl+C 같은 신호조차도 원래 핸들러로 가지 않고 즉시 처리돼요.
curses.newwin(nlines, ncols, begin_y, begin_x) — 지정한 크기와 위치의 새 창을 반환해요.
curses.newpad(nlines, ncols) — 새 패드를 반환해요. 패드는 화면보다 클 수 있는 창이에요.
curses.start_color() — 컬러 지원을 초기화해요. 컬러를 쓰려면 사용하기 전에 이 함수를 호출해야 해요.
curses.init_pair(pair_number, fg, bg) — 컬러 페어를 정의해요. 페어 번호를 color_pair(n)과 함께 쓰면 배경·전경색을 한 번에 지정할 수 있어요.
curses.keypad(win, flag) — 방향키와 함수 키가 특수 키 값으로 변환될지 제어해요.
curses.getch() — 한 문자를 읽어요. 키패드가 활성화되면 KEY_* 상수 값이 반환돼요.
curses.curs_set(visibility) — 커서의 가시성을 제어해요.
curses.doupdate() — 여러 창의 내용을 한 번에 화면에 반영해 깜빡임을 줄여요.

Window 객체

initscr(), newwin() 등으로 얻는 window 객체는 텍스트를 화면에 그리는 데 쓰는 핵심 객체예요. 주요 메서드들을 정리할게요:

window.addstr([y, x], str[, attr]) — 지정한 위치에 문자열을 그려요. 속성 인자로 강조(반전, 밑줄 등)를 줄 수 있어요.
window.addch([y, x], ch[, attr]) — 한 문자를 그려요.
window.move(new_y, new_x) — 커서를 이동해요.
window.clear(), window.erase() — 창을 지워요.
window.refresh() — 창 내용을 실제 화면에 반영해요.
window.noutrefresh() — 창 내용을 내부 버퍼에만 반영하고, 다음 doupdate() 호출 때 함께 그려요.
window.getch() — 창 입력을 한 글자 읽어요.
window.getkey() — 특수 키를 문자열로 읽어요(예: 위쪽 화살표는 KEY_UP).
window.getstr() — 사용자 입력 문자열을 읽어요.
window.attrset(attr), window.attron(attr), window.attroff(attr) — 창에 쓸 모든 내용에 적용되는 "배경" 속성 집합을 설정/추가/제거해요.
window.bkgd(ch[, attr]) — 창의 배경 특성을 문자 ch와 속성 attr로 설정해요. 변경은 창의 모든 문자 위치에 적용돼요.
window.border([ls, rs, ts, bs, tl, tr, bl, br]) — 창 가장자리에 테두리를 그려요. 각 매개변수는 테두리 특정 부분에 쓸 문자를 지정해요.
window.box([vertch, horch]) — 창 주위에 테두리를 그려요.
window.scroll([lines]) — 창을 스크롤해요.
window.subwin(nlines, ncols, begin_y, begin_x) — 기존 창의 하위 창을 만들어요.
window.redrawwin() — 화면의 이 전체 창 부분을 다시 그리도록 표시해요.
window.nodelay(flag) — getch()가 입력을 기다리지 않고 바로 반환할지 제어해요.
window.inch() — 커서 위치의 문자를 속성·컬러 페어 정보와 함께 정수로 반환해요.
window.isendwin() — 창이 전체 화면을 사용하는지 여부를 반환해요.

상수

키 상수

KEY_* 상수는 getch()가 반환하는 특수 키 값이에요. 주요 항목들:

상수	의미
`curses.KEY_UP`	Up arrow
`curses.KEY_DOWN`	Down arrow
`curses.KEY_LEFT`	Left arrow
`curses.KEY_RIGHT`	Right arrow
`curses.KEY_HOME`	Home key
`curses.KEY_BACKSPACE`	Backspace
`curses.KEY_F1` … `curses.KEY_F63`	Function keys
`curses.KEY_DL`	Delete line
`curses.KEY_IL`	Insert line
`curses.KEY_DC`	Delete character
`curses.KEY_IC`	Insert char or enter insert mode
`curses.KEY_CLEAR`	Clear screen
`curses.KEY_EOS`	Clear to end of screen
`curses.KEY_EOL`	Clear to end of line
`curses.KEY_SF`	Scroll 1 line forward
`curses.KEY_SR`	Scroll 1 line backward
`curses.KEY_NPAGE`	Next page (Page Down)
`curses.KEY_PPAGE`	Previous page (Page Up)
`curses.KEY_STAB`	Set tab
`curses.KEY_CTAB`	Clear tab
`curses.KEY_CATAB`	Clear all tabs
`curses.KEY_ENTER`	Enter or send (unreliable)
`curses.KEY_RESET`	Reset or hard reset (unreliable)
`curses.KEY_PRINT`	Print
`curses.KEY_LL`	Home down or bottom (lower left)
`curses.KEY_A1`	Upper left of keypad
`curses.KEY_A3`	Upper right of keypad
`curses.KEY_B2`	Center of keypad
`curses.KEY_C1`	Lower left of keypad
`curses.KEY_C3`	Lower right of keypad
`curses.KEY_BTAB`	Back tab
`curses.KEY_BEG`	Beg (beginning)
`curses.KEY_CANCEL`	Cancel
`curses.KEY_CLOSE`	Close
`curses.KEY_COMMAND`	Cmd (command)
`curses.KEY_COPY`	Copy
`curses.KEY_CREATE`	Create
`curses.KEY_END`	End
`curses.KEY_EXIT`	Exit
`curses.KEY_FIND`	Find
`curses.KEY_HELP`	Help
`curses.KEY_MARK`	Mark
`curses.KEY_MESSAGE`	Message
`curses.KEY_MOVE`	Move
`curses.KEY_NEXT`	Next
`curses.KEY_OPEN`	Open
`curses.KEY_OPTIONS`	Options
`curses.KEY_PREVIOUS`	Prev
`curses.KEY_REDO`	Redo
`curses.KEY_REFERENCE`	Ref
`curses.KEY_REFRESH`	Refresh
`curses.KEY_REPLACE`	Replace
`curses.KEY_RESTART`	Restart
`curses.KEY_RESUME`	Resume
`curses.KEY_SAVE`	Save
`curses.KEY_SBEG`	Shifted Beg
`curses.KEY_SDC`	Shifted Delete char
`curses.KEY_SELECT`	Select
`curses.KEY_SEND`	Shifted End
`curses.KEY_SEXIT`	Shifted Exit
`curses.KEY_SFIND`	Shifted Find
`curses.KEY_SHELP`	Shifted Help
`curses.KEY_SHOME`	Shifted Home
`curses.KEY_SLEFT`	Shifted Left arrow
`curses.KEY_SMESSAGE`	Shifted Message
`curses.KEY_SMOVE`	Shifted Move
`curses.KEY_SNEXT`	Shifted Next
`curses.KEY_SOPTIONS`	Shifted Options
`curses.KEY_SPREVIOUS`	Shifted Prev
`curses.KEY_SPRINT`	Shifted Print
`curses.KEY_SREDO`	Shifted Redo
`curses.KEY_SREPLACE`	Shifted Replace
`curses.KEY_SRIGHT`	Shifted Right arrow
`curses.KEY_SRSUME`	Shifted Resume
`curses.KEY_SSAVE`	Shifted Save
`curses.KEY_SSUSPEND`	Shifted Suspend
`curses.KEY_SUNDO`	Shifted Undo
`curses.KEY_SUSPEND`	Suspend
`curses.KEY_UNDO`	Undo
`curses.KEY_MOUSE`	Mouse event has occurred
`curses.KEY_RESIZE`	Terminal resize event
`curses.KEY_MAX`	Maximum key value

VT100과 그 소프트웨어 에뮬레이션(X 터미널 에뮬레이터 같은)에는 보통 최소한 네 개의 함수 키(KEY_F1–KEY_F4)가 있고 방향키는 자연스럽게 KEY_UP·KEY_DOWN·KEY_LEFT·KEY_RIGHT에 매핑돼요. PC 키보드라면 방향키와 열두 개의 함수 키를 기대해도 안전해요. 표준 키패드 매핑은: Insert → KEY_IC, Delete → KEY_DC, Home → KEY_HOME, End → KEY_END, Page Up → KEY_PPAGE, Page Down → KEY_NPAGE예요.

대체 문자 집합 (ACS)

ACS_* 상수는 VT100 터미널에서 물려받은 대체 문자 집합의 문자들이에요. 소프트웨어 에뮬레이션에서 일반적으로 사용 가능하죠. 그래픽이 없으면 curses는 조잡한 인쇄 가능한 ASCII 근사치로 대체해요. (이것들은 initscr()이 호출된 후에만 사용 가능해요.)

ACS 코드	의미
`curses.ACS_BLOCK`	solid square block
`curses.ACS_BOARD`	board of squares
`curses.ACS_BULLET`	bullet
`curses.ACS_CKBOARD`	checker board (stipple)
`curses.ACS_DARROW`	arrow pointing down
`curses.ACS_DEGREE`	degree symbol
`curses.ACS_DIAMOND`	diamond
`curses.ACS_GEQUAL`	greater-than-or-equal-to
`curses.ACS_HLINE`	horizontal line
`curses.ACS_LANTERN`	lantern symbol
`curses.ACS_LARROW`	left arrow
`curses.ACS_LEQUAL`	less-than-or-equal-to
`curses.ACS_LLCORNER`	lower-left corner
`curses.ACS_LRCORNER`	lower-right corner
`curses.ACS_LTEE`	left tee
`curses.ACS_NEQUAL`	not-equal sign
`curses.ACS_PI`	letter pi
`curses.ACS_PLMINUS`	plus-or-minus sign
`curses.ACS_PLUS`	big plus sign
`curses.ACS_RARROW`	right arrow
`curses.ACS_RTEE`	right tee
`curses.ACS_S1` … `curses.ACS_S9`	scan lines 1–9
`curses.ACS_STERLING`	pound sterling
`curses.ACS_TTEE`	top tee
`curses.ACS_UARROW`	up arrow
`curses.ACS_ULCORNER`	upper-left corner
`curses.ACS_URCORNER`	upper-right corner
`curses.ACS_VLINE`	vertical line

(코너·티·선 조합의 대체 이름인 ACS_BBSS, ACS_BSBS, ACS_BSSB, ACS_BSSS, ACS_SBBS, ACS_SBSB, ACS_SBSS, ACS_SSBB, ACS_SSBS, ACS_SSSB, ACS_SSSS도 존재해요.)

마우스 버튼 상수

getmouse()가 사용하는 마우스 버튼 상수들이에요:

마우스 버튼 상수	의미
`curses.BUTTONn_PRESSED`	Mouse button n pressed
`curses.BUTTONn_RELEASED`	Mouse button n released
`curses.BUTTONn_CLICKED`	Mouse button n clicked
`curses.BUTTONn_DOUBLE_CLICKED`	Mouse button n double clicked
`curses.BUTTONn_TRIPLE_CLICKED`	Mouse button n triple clicked
`curses.BUTTON_SHIFT`	Shift was down during button state change
`curses.BUTTON_CTRL`	Control was down during button state change
`curses.BUTTON_ALT`	Alt was down during button state change

(3.10부터 기반 curses 라이브러리가 제공하면 BUTTON5_* 상수도 노출돼요.)

사전 정의된 색상

상수	색상
`curses.COLOR_BLACK`	Black
`curses.COLOR_BLUE`	Blue
`curses.COLOR_CYAN`	Cyan (light greenish blue)
`curses.COLOR_GREEN`	Green
`curses.COLOR_MAGENTA`	Magenta (purplish red)
`curses.COLOR_RED`	Red
`curses.COLOR_WHITE`	White
`curses.COLOR_YELLOW`	Yellow

curses.textpad — curses 프로그램용 텍스트 입력 위젯

curses.textpad 모듈은 curses 창에서 기본 텍스트 편집을 처리하는 Textbox 클래스를 제공해요. Emacs의 키바인딩과 비슷한 키 세트를 지원해요(Netscape Navigator, BBedit 6.x, FrameMaker 등과도 비슷하죠). 이 모듈은 텍스트 박스 테두리나 다른 용도로 쓸 수 있는 직사각형 그리기 함수도 함께 제공합니다.

curses.textpad.rectangle(win, uly, ulx, lry, lrx)

rectangle()은 직사각형을 그려요. 첫 인자는 창 객체여야 하고 나머지 인자는 그 창에 상대적인 좌표예요. 두 번째·세 번째 인자는 직사각형 왼쪽 위 모서리의 y·x 좌표이고, 네 번째·다섯 번째 인자는 오른쪽 아래 모서리의 y·x 좌표예요. 가능한 터미널(xterm 및 대부분의 소프트웨어 터미널 에뮬레이터 포함)에서는 VT100/IBM PC 폼 문자로 그리고, 그렇지 않으면 ASCII 대시·세로 막대·플러스 기호로 그려요.

Textbox 객체

class curses.textpad.Textbox(win, insert_mode=False)

Textbox 객체로 textbox 위젯 객체를 반환해요. win 인자는 textbox가 들어갈 curses 창 객체여야 해요. insert_mode가 참이면 textbox는 입력 문자를 삽입해 기존 텍스트를 오른쪽으로 밀어내고, 거짓이면 덮어써요. textbox의 편집 커서는 처음에 포함 창의 왼쪽 위 모서리 좌표 (0, 0)에 놓여 있어요. 인스턴스의 stripspaces 플래그는 처음에 켜져 있습니다.

주요 메서드:

Textbox.edit([validator]) — 사용자 입력을 처리하고, 나중에 Textbox.gather()가 반환할 문자열을 편집해요.
Textbox.do_command(ch) — 단일 키 입력을 처리해요.
Textbox.gather() — textbox에 담긴 텍스트를 문자열로 반환해요. stripspaces가 참이면 각 행에서 뒤따르는 공백을 제거해요.

더 알아보기

curses.ascii 모듈: ASCII 문자 상수와 헬퍼
curses.panel 모듈: 창의 스택을 관리하는 패널
ncurses의 C 문서와 curses 소스 코드