Metadata-Version: 2.5
Name: printsection
Version: 0.4.0
Summary: 출력 구간을 나누는 가운데 정렬 구분선 + 라이브러리 호출 흐름 추적 출력
License-Expression: MIT
License-File: LICENSE
Keywords: center,console,debug,divider,korean,print,section,trace
Classifier: Natural Language :: Korean
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# printsection

`print("\n", "실습 결과".center(50, "-"), end="\n\n")` 를 한 줄로.
출력 결과를 구간별로 나눠 보기 좋게 구분해 줍니다.

```bash
pip install printsection
# uv 사용 시: uv add printsection
```

```python
from printsection import print_section

print_section("실습 1")
print("...")
print_section("실습 2")
```

```

----------------------실습 1----------------------

...

----------------------실습 2----------------------

```

위아래 빈 줄과 가운데 정렬이 기본입니다. 한글처럼 화면에서 2칸을 차지하는 글자도 폭을 계산해서 실제 화면 기준으로 가운데에 맞춥니다.

## 옵션

호출할 때 원하는 값만 바꾸면 됩니다.

```python
print_section("실습 결과", width=60, fillchar="=")
print_section("왼쪽 정렬", align="left")          # "center" / "left" / "right"
print_section("빈 줄 조절", top=2, bottom=0)
print_section("str.center처럼", wide=False)       # 글자 수 기준으로 계산
print_section()                                   # 글자 없이 구분선만
```

| 옵션 | 기본값 | 설명 |
|---|---|---|
| `width` | `50` | 전체 너비 |
| `fillchar` | `"-"` | 채움 문자 (한 글자) |
| `align` | `"center"` | `"center"`, `"left"`, `"right"` |
| `top` | `1` | 위쪽 빈 줄 수 |
| `bottom` | `1` | 아래쪽 빈 줄 수 |
| `wide` | `True` | 한글 등 전각 문자를 2칸으로 계산 |
| `file` | `sys.stdout` | 출력 대상 |

## 기본값 한 번에 바꾸기

```python
from printsection import print_section, set_defaults, reset_defaults

set_defaults(width=70, fillchar="*")
print_section("1번 문제")
print_section("2번 문제")
reset_defaults()
```

## 문자열만 받기

```python
from printsection import format_section

s = format_section("실습 결과")   # 출력하지 않고 문자열 반환
```

## 라이브러리 호출 추적: `print_trace_start` / `print_trace_end`

두 함수 사이에서 실행된 **라이브러리 내부 호출**을 순서대로 보여줍니다.
**메소드 · 파일:줄 · 경로**를 들여쓰기 트리로 출력하고, 끝나면 파일·메소드별로 묶은 요약을 출력합니다.
라이브러리가 내부에서 어떤 순서로 무엇을 호출하는지 공부할 때 쓰면 좋습니다.

```python
from printsection import print_trace_start, print_trace_end
from packaging.requirements import Requirement

print_trace_start()
Requirement("requests>=2.0; python_version>'3.8'")
print_trace_end()
```

```
-------------------TRACE START--------------------

메소드  ·  파일:줄  ·  경로
├ Requirement.__init__  ·  requirements.py:82  ·  packaging
│  ├ parse_requirement  ·  _parser.py:106  ·  packaging
│  │  ├ Tokenizer.__init__  ·  _tokenizer.py:105  ·  packaging
│  │  ├ _parse_requirement  ·  _parser.py:110  ·  packaging
│  │  │  ├ Tokenizer.consume  ·  _tokenizer.py:116  ·  packaging
...

--------------------TRACE END---------------------

[요약] 호출 87회 · 메소드 29개 · 파일 6개 · 전체 0.008초

packaging/requirements.py
        1회        6.3ms  Requirement.__init__

packaging/_tokenizer.py
       14회        0.2ms  Tokenizer.consume
       33회        0.1ms  Tokenizer.check
...
```

기본으로는 `site-packages`에 설치된 라이브러리만 보여줍니다. 내가 작성한 코드와 파이썬 표준 라이브러리는 빠집니다.

### 추적 옵션

```python
print_trace_start(["langchain_core", "openai"])   # 이 패키지들만 보기
print_trace_start(max_depth=2)                     # 3단계 깊이까지만
print_trace_start(user=True)                       # 내 코드 호출도 함께
print_trace_start(file="trace.log")                # 화면 대신 파일로 저장
print_trace_start(hide_private=True)               # _로 시작하는 내부 함수 숨기기
```

| 옵션 | 기본값 | 설명 |
|---|---|---|
| `packages` | `None` | 추적할 패키지 이름 목록. 지정하면 위치와 상관없이 이 패키지만 출력 |
| `stdlib` | `False` | 파이썬 표준 라이브러리 호출도 출력 |
| `user` | `False` | 내가 작성한 프로젝트 코드 호출도 출력 |
| `max_depth` | `None` | 이 깊이보다 깊은 호출은 생략 (0부터 시작) |
| `max_lines` | `2000` | 최대 출력 줄 수. 넘으면 생략하고 개수만 알려줌 (`None`이면 무제한) |
| `file` | 화면 | 파일 객체 또는 파일 경로 |
| `show_line` | `True` | 파일 이름 뒤에 함수 정의 줄 번호 표시 |
| `hide_private` | `False` | `_parse`, `_Foo.run`처럼 `_`로 시작하는 내부 함수·클래스 숨김 (`__init__` 같은 특수 메소드는 표시) |
| `threads` | `False` | 이후 새로 시작되는 스레드도 추적 |
| `header` | `True` | 시작/종료 구분선 출력 |

`print_trace_end(summary=False)`로 요약 출력을 끌 수 있습니다.
반환값은 호출 목록입니다: `[{"depth", "method", "file", "line", "path"}, ...]`.

`with` 문으로도 쓸 수 있습니다.

```python
from printsection import trace

with trace(["langchain_core"], max_depth=3):
    chain.invoke({"question": "안녕"})
```

### 참고

- 출력이 너무 많으면 `packages`로 패키지를 좁히고, `hide_private=True`로 내부 함수를 숨기고, `max_depth`로 깊이를 제한해 보세요. 숨긴 함수 안에서 호출된 공개 함수는 그대로 보이고, 가장 가까운 상위 호출 아래에 붙습니다.
- LangChain 같은 큰 라이브러리는 호출이 수천 개 나올 수 있습니다. `packages`나 `max_depth`로 범위를 좁혀 쓰세요.
- 제너레이터/코루틴(스트리밍, async)은 처음 호출될 때 한 번만 표시합니다.
- 추적하는 동안에는 코드가 느려집니다. 공부하거나 디버깅할 때만 쓰세요.
