# Maguyva의 Python 지원: AI 코드 검색과 리팩터링

Canonical source: https://maguyva.ai/ko/languages/python

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Maguyva는 AST 파싱과 심볼 추출로 Python을 지원하여, AI 에이전트가 실제 Python 저장소에서 데코레이터, self/cls 메서드, import, 모듈 간 의존성을 따라갈 수 있도록 돕습니다.

## 지원 현황 요약

- 등급: AST 및 심볼 지원
- 프로그래밍
- 확장자: .py, .pyi, .pyw
- 구문 인식 검색과 구조적 컨텍스트를 위한 실제 AST 파싱을 제공합니다.
- 이름이 지정된 심볼은 시맨틱 조회와 상호 참조에 활용됩니다. 관계 추출이 활성화된 경우 그래프 내비게이션을 사용할 수 있습니다.
- 이 언어는 그래프 인식 검색에 심볼과 관계를 제공합니다. 지원되는 에지 유형은 언어 고유의 구문 구조에 따라 다릅니다.
- AST 파싱과 심볼 추출을 모두 지원합니다.

## 가장 적합한 경우

- 애플리케이션 코드와 운영 스크립트가 공존하는 FastAPI, Django, 데이터 플랫폼, 또는 내부 도구 저장소.
- 이미 데코레이터, 백그라운드 작업, 암묵적으로 얽힌 연결 관계가 많은 오래된 Python 서비스를 리팩터링하는 팀.
- 핸들러, 서비스, 모델, 헬퍼를 변경하기 전에 grep 이상이 필요한 에이전트 워크플로.

## 에이전트 워크플로

- 수정하기 전에 엔드포인트, 태스크, CLI 명령을 헬퍼와 공유 모듈을 거쳐 추적합니다.
- 서비스, 클래스, 유틸리티 함수가 저장소 전체에서 어디서 인스턴스화되고 재사용되는지 찾습니다.
- 에이전트가 가장 유사한 문자열이 아니라 올바른 추상화를 수정하도록 인접한 구현들을 비교합니다.

## Python 저장소가 얕은 AI 도구를 무너뜨리는 지점

Python은 많은 AI 코딩 도구가 처음에는 괜찮아 보이다가 프로덕션에서 추측을 시작하는 지점입니다. 어려운 부분들은 익숙합니다. 데코레이트된 진입점, 서비스 클래스, 타입 스텁, 곳곳에 흩어진 작은 헬퍼 모듈, 그리고 `self`나 `cls`를 그것이 속한 클래스에 다시 연결해야만 의미가 통하는 메서드들이죠.

Python의 경우, 진짜 질문은 "`.py` 파일을 읽을 수 있는가?"가 아닙니다. 질문은 에이전트가 엔드포인트에서 서비스로, 백그라운드 태스크에서 헬퍼로, 혹은 클래스 이름에서 실제로 그 동작을 구현하는 메서드로 이동하는 동안 근거를 잃지 않을 수 있는가입니다.

## Maguyva가 Python에서 실제로 추출하는 것

Maguyva는 Python에 완전한 코드 구조 분석 지원을 제공합니다. 설정은 `.py`, `.pyw`, `.pyi`를 다루고, `decorated_definition`을 함수 심볼로 다시 매핑하며, `self` / `cls` 메서드 호출을 그것을 감싸는 클래스로 다시 한정합니다. 이는 중요한데, 바로 이런 지점들이 Python 저장소가 사람에게는 명확하게 느껴지지만 LLM에게는 모호하게 느껴지기 시작하는 지점이기 때문입니다.

또한 관계 추출 과정에서 표준 라이브러리 노이즈를 대량으로 필터링합니다. 이는 `pathlib`, `typing`, `logging` 같은 모듈의 흔한 런타임 호출이 여러분이 실제로 관심 있는 저장소 고유의 관계를 뒤덮을 가능성을 낮춘다는 뜻입니다.

## Python 저장소를 위한 유용한 MCP 워크플로

가장 간단하면서도 유용한 워크플로는 다음과 같습니다.

- "인보이스 동기화 관련 재시도 로직"이나 "청구 엔드포인트의 권한 확인" 같은 동작 관련 질문에는 `intelligent_search`로 시작합니다.
- 관심 있는 클래스나 함수 이름을 알게 되면 `find_symbol`으로 전환합니다.
- 공유 서비스, 헬퍼, 베이스 클래스를 리팩터링하기 전에는 인바운드 탐색과 함께 `dependency_search`를 사용합니다.

이 패턴은 아무런 맥락 없이 에이전트에게 "청구 흐름을 업데이트해줘"라고 요청하는 것보다 낫습니다. 에이전트가 먼저 지도를 그리고, 그다음에 코드를 변경하도록 해주기 때문입니다.

## 이 페이지가 유용한 경우

이 페이지는 서비스 코드, 작업, 스크립트, 생성된 타입, 주변 설정 등 이미 어느 정도 연식과 복잡도를 갖춘 Python 저장소를 위한 것입니다. 주된 비교 대상이 폴리글랏 웹 모노레포 전반이라면 [TypeScript 가이드](/ko/languages/typescript)도 읽어보세요. 전체 지원 매트릭스만 필요하다면 [호환성](/ko/docs/compatibility)을 이용하세요.

## 엔진 세부 정보

- 데코레이터가 붙은 정의도 함수로 취급되어, 데코레이터가 적용된 뷰와 태스크가 심볼로 계속 검색 가능합니다.
- `self`와 `cls` 메서드 호출은 포함하는 클래스로 다시 한정되어, 클래스 중심 서비스 코드에서 그래프가 계속 유용하게 유지됩니다.
- 임포트, 호출, 심볼 정규화기가 활성화되어 있으며, `pathlib.*`, `typing.*`, `logging.*` 같은 흔한 표준 라이브러리 노이즈는 관계에서 필터링됩니다.

## 유용한 MCP 진입점

- `intelligent_search`: "인보이스 동기화 관련 재시도 로직"처럼 개념적인 쿼리로 시작하고, 저장소가 여러 언어를 섞어 쓴다면 `language_filter="python"`을 설정하세요.
- `find_symbol`: 클래스나 함수 이름을 알고 있고, 편집 전에 정의와 참조를 함께 확인해야 할 때 사용하세요.
- `dependency_search`: 공유 서비스나 헬퍼를 리팩터링하기 전에 무엇이 이에 의존하는지 보려면 해당 대상을 사용하는 쪽으로 거슬러 올라가는(incoming) 방향을 사용하세요.