CTStruct

텍스트 양식을 구조화하는 Python 트리 자료형 라이브러리

CTStruct는 Markdown, 일반 텍스트, JSON 등 다양한 텍스트 포맷을 통일된 트리 자료구조(CTTree) 로 파싱·변환·렌더링하는 Python 라이브러리입니다.

텍스트 입력  →  [Parser]  →  CTTree  →  [Renderer]  →  출력 포맷
                               ↑
                          (탐색 / 변환 / 병합)

---

특징

• 통일된 트리 API — 어떤 포맷이든 CTNode / CTTree 로 표현
• 플러그인형 파서 & 렌더러 — BaseParser / BaseRenderer 상속으로 손쉽게 확장
• 풍부한 탐색 API — walk(), find(), ancestors(), toc() 등
• 불변 변환 — filter(), map() 은 새 트리를 반환하여 원본 보존
• 직렬화 — to_dict() / from_dict() 로 JSON 직렬화 지원
• 의존성 없음 — 표준 라이브러리만 사용

---

빠른 시작

설치

pip install -e .

기본 사용 예시

from ctstruct import CTTree, CTNode, NodeType
from ctstruct.parsers import MarkdownParser
from ctstruct.renderers import MarkdownRenderer, JSONRenderer

# 1) 직접 트리 빌드
tree = CTTree(title="나의 문서")
sec = CTNode(NodeType.SECTION)
sec.append(CTNode(NodeType.HEADING, "소개", {"level": 1}))
sec.append(CTNode(NodeType.PARAGRAPH, "CTStruct 는 텍스트를 트리로 구조화합니다."))
sec.append(CTTree.make_list(["파싱", "변환", "렌더링"]))
tree.root.append(sec)

# 2) Markdown 파싱
parser = MarkdownParser()
tree = parser.parse(open("document.md").read())

# 3) 탐색
for heading in tree.find(NodeType.HEADING):
    print(heading.attr("level"), heading.content)

# 목차 생성
for entry in tree.toc():
    print("  " * (entry["level"] - 1) + entry["text"])

# 4) 렌더링
md_renderer = MarkdownRenderer()
print(md_renderer.render(tree))

json_renderer = JSONRenderer(indent=2)
print(json_renderer.render(tree))

# 5) 트리 변환 (불변)
filtered = tree.filter(lambda n: n.node_type != NodeType.CODE_BLOCK)
upper = tree.map(lambda n: setattr(n, "content", (n.content or "").upper()) or None)

트리 구조 시각화

print(tree.pretty())
# [a1b2c3d4] ROOT: None
#   [e5f6a7b8] SECTION: None
#     [c9d0e1f2] HEADING level=1: '소개'
#     [a3b4c5d6] PARAGRAPH: 'CTStruct 는 텍스트를…'
#     [e7f8a9b0] LIST style='unordered': None
#       [c1d2e3f4] LIST_ITEM: '파싱'
#       [a5b6c7d8] LIST_ITEM: '변환'
#       [e9f0a1b2] LIST_ITEM: '렌더링'

---

지원 노드 타입

카테고리	타입	설명
구조	ROOT	트리 최상위
구조	DOCUMENT	문서 단위
구조	SECTION	헤딩 + 내용 묶음
블록	HEADING	제목 (level 1–6)
블록	PARAGRAPH	문단
블록	LIST / LIST_ITEM	목록
블록	TABLE / TABLE_ROW / TABLE_CELL	표
블록	CODE_BLOCK	코드 블록
블록	BLOCKQUOTE	인용구
블록	DIVIDER	구분선
인라인	TEXT BOLD ITALIC CODE LINK IMAGE	인라인 요소
메타	METADATA	문서 메타 (frontmatter)
메타	ANNOTATION	주석/노트
메타	CUSTOM	사용자 정의 확장

---

프로젝트 구조

CTStruct/
├── ctstruct/
│   ├── __init__.py          # 공개 API
│   ├── types.py             # NodeType Enum
│   ├── node.py              # CTNode 클래스
│   ├── tree.py              # CTTree 클래스
│   ├── parsers/
│   │   ├── base.py          # BaseParser (추상)
│   │   └── markdown.py      # MarkdownParser
│   └── renderers/
│       ├── base.py          # BaseRenderer (추상)
│       ├── markdown.py      # MarkdownRenderer
│       └── json_renderer.py # JSONRenderer
├── tests/
│   ├── test_node.py
│   ├── test_tree.py
│   └── test_parsers.py
├── docs/
│   └── ARCHITECTURE.md
└── pyproject.toml

---

테스트 실행

pip install -e ".[dev]"
pytest -v --cov=ctstruct

---

라이선스

MIT