"ast" --- 추상 구문 트리
************************

**소스 코드:** Lib/ast.py

======================================================================

"ast" 모듈은 파이썬 응용 프로그램이 파이썬 추상 구문 문법의 트리를 처
리하는 데 도움을 줍니다. 추상 구문 자체는 각 파이썬 릴리스마다 바뀔 수
있습니다; 이 모듈은 프로그래밍 방식으로 현재 문법의 모양을 찾는 데 도
움이 됩니다.

"ast.PyCF_ONLY_AST"를 플래그로 "compile()" 내장 함수에 전달하거나, 이
모듈에서 제공된 "parse()" 도우미를 사용하여 추상 구문 트리를 생성할 수
있습니다. 결과는 클래스가 모두 "ast.AST"에서 상속되는 객체들의 트리가
됩니다. 내장 "compile()" 함수를 사용하여 추상 구문 트리를 파이썬 코드
객체로 컴파일할 수 있습니다.


노드 클래스
===========

class ast.AST

   이것은 모든 AST 노드 클래스의 베이스입니다. 실제 노드 클래스는
   "Parser/Python.asdl" 파일에서 파생되며, 이 파일의 내용은 아래에서
   볼 수 있습니다. "_ast" C 모듈에 정의되어 있으며 "ast"로 다시 내보내
   집니다.

   추상 문법의 각 좌변 심볼마다 하나의 클래스가 정의되어 있습니다 (예
   를 들어, "ast.stmt"나 "ast.expr"). 또한, 우변의 생성자마다 하나의
   클래스가 정의되어 있습니다; 이 클래스는 좌변 트리의 클래스에서 상속
   됩니다. 예를 들어, "ast.BinOp"는 "ast.expr"에서 상속됩니다. 대안을
   갖는 생성 규칙(일명 "합")의 경우, 좌변 클래스는 추상입니다: 특정 생
   성자 노드의 인스턴스만 만들어집니다.

   _fields

      각 구상 클래스에는 모든 자식 노드의 이름을 제공하는 어트리뷰트
      "_fields"가 있습니다.

      구상 클래스의 각 인스턴스에는 각 자식 노드마다 문법에 정의된 형
      의 어트리뷰트가 하나씩 있습니다. 예를 들어, "ast.BinOp" 인스턴스
      는 "ast.expr" 형의 어트리뷰트 "left"를 갖습니다.

      문법에서 이러한 어트리뷰트가 선택적으로 표시되면 (물음표를 사용
      해서), 값은 "None"일 수 있습니다. 어트리뷰트가 0개 이상의 값을
      가질 수 있으면 (애스터리스크로 표시됩니다), 값은 파이썬 리스트로
      표현됩니다. "compile()"로 AST를 컴파일할 때 가능한 모든 어트리뷰
      트가 존재하고 유효한 값을 가져야 합니다.

   lineno
   col_offset
   end_lineno
   end_col_offset

      "ast.expr"과 "ast.stmt" 서브 클래스의 인스턴스에는 "lineno",
      "col_offset", "lineno" 및 "col_offset" 어트리뷰트가 있습니다.
      "lineno"와 "end_lineno"는 소스 텍스트 스팬의 첫 번째와 마지막 줄
      번호(1-인덱싱이라서 첫 번째 줄은 줄 1입니다)이고 "col_offset"과
      "end_col_offset"은 노드를 생성한 첫 번째와 마지막 토큰의 해당
      UTF-8 바이트 오프셋입니다. 구문 분석기가 UTF-8을 내부적으로 사용
      하기 때문에 UTF-8 오프셋이 기록됩니다.

      종료 위치는 컴파일러에 필요하지 않아서 선택 사항입니다. 종료 오
      프셋은 마지막 심볼 *뒤*입니다. 예를 들어
      "source_line[node.col_offset : node.end_col_offset]"를 사용하여
      한 줄 표현식 노드의 소스 세그먼트를 가져올 수 있습니다.

   "ast.T" 클래스의 생성자는 다음과 같이 인자를 구문 분석합니다:

   * 위치 인자가 있으면, "T._fields"에 있는 항목 수만큼 있어야 합니다;
     이러한 이름의 어트리뷰트로 대입될 것입니다.

   * 키워드 인자가 있으면, 같은 이름의 어트리뷰트를 지정된 값으로 설정
     합니다.

   예를 들어, "ast.UnaryOp" 노드를 만들고 채우려면, 다음과 같이 할 수
   있습니다

      node = ast.UnaryOp()
      node.op = ast.USub()
      node.operand = ast.Constant()
      node.operand.value = 5
      node.operand.lineno = 0
      node.operand.col_offset = 0
      node.lineno = 0
      node.col_offset = 0

   또는 더 간결하게

      node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0),
                         lineno=0, col_offset=0)

버전 3.8에서 변경: "ast.Constant" 클래스는 이제 모든 상수에 사용됩니다
.

버전 3.8부터 폐지: 이전 클래스 "ast.Num", "ast.Str", "ast.Bytes",
"ast.NameConstant" 및 "ast.Ellipsis"는 계속 사용할 수 있지만, 향후 파
이썬 릴리스에서 제거될 예정입니다. 한편, 이들을 인스턴스 화하면 다른
클래스의 인스턴스가 반환됩니다.


추상 문법
=========

추상 문법은 현재 다음과 같이 정의됩니다:

   -- ASDL's 5 builtin types are:
   -- identifier, int, string, object, constant

   module Python
   {
       mod = Module(stmt* body, type_ignore *type_ignores)
           | Interactive(stmt* body)
           | Expression(expr body)
           | FunctionType(expr* argtypes, expr returns)

           -- not really an actual node but useful in Jython's typesystem.
           | Suite(stmt* body)

       stmt = FunctionDef(identifier name, arguments args,
                          stmt* body, expr* decorator_list, expr? returns,
                          string? type_comment)
             | AsyncFunctionDef(identifier name, arguments args,
                                stmt* body, expr* decorator_list, expr? returns,
                                string? type_comment)

             | ClassDef(identifier name,
                expr* bases,
                keyword* keywords,
                stmt* body,
                expr* decorator_list)
             | Return(expr? value)

             | Delete(expr* targets)
             | Assign(expr* targets, expr value, string? type_comment)
             | AugAssign(expr target, operator op, expr value)
             -- 'simple' indicates that we annotate simple name without parens
             | AnnAssign(expr target, expr annotation, expr? value, int simple)

             -- use 'orelse' because else is a keyword in target languages
             | For(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
             | AsyncFor(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
             | While(expr test, stmt* body, stmt* orelse)
             | If(expr test, stmt* body, stmt* orelse)
             | With(withitem* items, stmt* body, string? type_comment)
             | AsyncWith(withitem* items, stmt* body, string? type_comment)

             | Raise(expr? exc, expr? cause)
             | Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
             | Assert(expr test, expr? msg)

             | Import(alias* names)
             | ImportFrom(identifier? module, alias* names, int? level)

             | Global(identifier* names)
             | Nonlocal(identifier* names)
             | Expr(expr value)
             | Pass | Break | Continue

             -- XXX Jython will be different
             -- col_offset is the byte offset in the utf8 string the parser uses
             attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

             -- BoolOp() can use left & right?
       expr = BoolOp(boolop op, expr* values)
            | NamedExpr(expr target, expr value)
            | BinOp(expr left, operator op, expr right)
            | UnaryOp(unaryop op, expr operand)
            | Lambda(arguments args, expr body)
            | IfExp(expr test, expr body, expr orelse)
            | Dict(expr* keys, expr* values)
            | Set(expr* elts)
            | ListComp(expr elt, comprehension* generators)
            | SetComp(expr elt, comprehension* generators)
            | DictComp(expr key, expr value, comprehension* generators)
            | GeneratorExp(expr elt, comprehension* generators)
            -- the grammar constrains where yield expressions can occur
            | Await(expr value)
            | Yield(expr? value)
            | YieldFrom(expr value)
            -- need sequences for compare to distinguish between
            -- x < 4 < 3 and (x < 4) < 3
            | Compare(expr left, cmpop* ops, expr* comparators)
            | Call(expr func, expr* args, keyword* keywords)
            | FormattedValue(expr value, int? conversion, expr? format_spec)
            | JoinedStr(expr* values)
            | Constant(constant value, string? kind)

            -- the following expression can appear in assignment context
            | Attribute(expr value, identifier attr, expr_context ctx)
            | Subscript(expr value, slice slice, expr_context ctx)
            | Starred(expr value, expr_context ctx)
            | Name(identifier id, expr_context ctx)
            | List(expr* elts, expr_context ctx)
            | Tuple(expr* elts, expr_context ctx)

             -- col_offset is the byte offset in the utf8 string the parser uses
             attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

       expr_context = Load | Store | Del | AugLoad | AugStore | Param

       slice = Slice(expr? lower, expr? upper, expr? step)
             | ExtSlice(slice* dims)
             | Index(expr value)

       boolop = And | Or

       operator = Add | Sub | Mult | MatMult | Div | Mod | Pow | LShift
                    | RShift | BitOr | BitXor | BitAnd | FloorDiv

       unaryop = Invert | Not | UAdd | USub

       cmpop = Eq | NotEq | Lt | LtE | Gt | GtE | Is | IsNot | In | NotIn

       comprehension = (expr target, expr iter, expr* ifs, int is_async)

       excepthandler = ExceptHandler(expr? type, identifier? name, stmt* body)
                       attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

       arguments = (arg* posonlyargs, arg* args, arg? vararg, arg* kwonlyargs,
                    expr* kw_defaults, arg? kwarg, expr* defaults)

       arg = (identifier arg, expr? annotation, string? type_comment)
              attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

       -- keyword arguments supplied to call (NULL identifier for **kwargs)
       keyword = (identifier? arg, expr value)

       -- import name with optional 'as' alias.
       alias = (identifier name, identifier? asname)

       withitem = (expr context_expr, expr? optional_vars)

       type_ignore = TypeIgnore(int lineno, string tag)
   }


"ast" 도우미
============

노드 클래스 외에도, "ast" 모듈은 추상 구문 트리를 탐색하기 위해 다음
유틸리티 함수와 클래스를 정의합니다:

ast.parse(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None)

   소스를 AST 노드로 구문 분석합니다. "compile(source, filename, mode,
   ast.PyCF_ONLY_AST)"와 동등합니다.

   "type_comments=True"가 제공되면, 구문 분석기는 **PEP 484**와 **PEP
   526**에 지정된 형 주석을 확인하고 반환하도록 수정됩니다. 이는
   "compile()"에 전달된 플래그에 "ast.PyCF_TYPE_COMMENTS"를 추가하는
   것과 같습니다. 이것은 잘못 배치된 형 주석에 대한 문법 에러를 보고합
   니다. 이 플래그가 없으면, 형 주석은 무시되고, 선택한 AST 노드의
   "type_comment" 필드는 항상 "None"입니다. 또한, "# type: ignore" 주
   석의 위치는 "Module"의 "type_ignores" 어트리뷰트로 반환됩니다 (그렇
   지 않으면 항상 빈 리스트입니다).

   또한, "mode"가 "'func_type'"이면, 입력 문법은 **PEP 484** "서명 형
   주석"에 따라 수정됩니다, 예를 들어 "(str, int) -> List[str]".

   또한, "feature_version"을 튜플 "(major, minor)"로 설정하면 해당 파
   이썬 버전의 문법을 사용하여 구문 분석을 시도합니다. 현재 "major"는
   "3"과 같아야 합니다. 예를 들어, "feature_version=(3, 4)"를 설정하면
   변수 이름으로 "async"와 "await"를 사용할 수 있습니다. 가장 낮은 지
   원 버전은 "(3, 4)"입니다; 가장 높은 것은 "sys.version_info[0:2]"입
   니다.

   경고:

     파이썬 AST 컴파일러의 스택 깊이 제한으로 인해 충분히 크고/복잡한
     문자열로 파이썬 인터프리터가 충돌하도록 만들 수 있습니다.

   버전 3.8에서 변경: "type_comments", "mode='func_type'" 및
   "feature_version"추가했습니다.

ast.literal_eval(node_or_string)

   파이썬 리터럴 이나 컨테이너 디스플레이를 포함하는 표현식 노드나 문
   자열을 안전하게 평가합니다. 제공된 문자열이나 노드는 다음과 같은 파
   이썬 리터럴 구조로만 구성될 수 있습니다: 문자열, 바이트열, 숫자, 튜
   플, 리스트, 딕셔너리, 집합, 불리언 및 "None".

   값을 직접 구문 분석할 필요 없이 신뢰할 수 없는 소스의 파이썬 값을
   포함하는 문자열을 안전하게 평가하는 데 사용할 수 있습니다. 예를 들
   어 연산자나 인덱싱이 개입한, 임의의 복잡한 표현식을 평가할 수 없습
   니다.

   경고:

     파이썬 AST 컴파일러의 스택 깊이 제한으로 인해 충분히 크고/복잡한
     문자열로 파이썬 인터프리터가 충돌하도록 만들 수 있습니다.

   버전 3.2에서 변경: 이제 바이트열과 집합 리터럴을 허용합니다.

ast.get_docstring(node, clean=True)

   주어진 *node*("FunctionDef", "AsyncFunctionDef", "ClassDef" 또는
   "Module" 노드이어야 합니다)의 독스트링이나, 독스트링이 없으면
   "None"을 반환합니다. *clean*이 참이면, "inspect.cleandoc()"으로 독
   스트링의 들여쓰기를 정리합니다.

   버전 3.5에서 변경: "AsyncFunctionDef" 가 이제 지원됩니다.

ast.get_source_segment(source, node, *, padded=False)

   *node*를 생성한 *source*의 소스 코드 세그먼트를 가져옵니다. 일부 위
   치 정보("lineno", "end_lineno", "col_offset" 또는 "end_col_offset")
   가 없으면, "None"을 반환합니다.

   *padded*가 "True"이면, 여러 줄 문장의 첫 번째 줄은 원래 위치와 일치
   하도록 스페이스로 채워집니다.

   버전 3.8에 추가.

ast.fix_missing_locations(node)

   "compile()"로 노드 트리를 컴파일할 때, 컴파일러는 지원하는 모든 노
   드에 대해 "lineno"와 "col_offset" 어트리뷰트를 기대합니다. 생성된
   노드를 채울 때는 이것이 다소 지루하므로, 이 도우미는 이러한 어트리
   뷰트를 재귀적으로 아직 설정되지 않은 위치에 부모 노드의 값으로 설정
   하여 추가합니다. *node*부터 재귀적으로 작동합니다.

ast.increment_lineno(node, n=1)

   *node*에서 시작하는 트리에서 각 노드의 줄 번호와 끝 줄 번호를 *n*만
   큼 증가시킵니다. 파일의 다른 위치로 "코드를 이동"하는 데 유용합니다
   .

ast.copy_location(new_node, old_node)

   가능하면 소스 위치("lineno", "col_offset", "end_lineno" 및
   "end_col_offset")를 *old_node*에서 *new_node*로 복사하고,
   *new_node*를 반환합니다.

ast.iter_fields(node)

   *node*에 존재하는 "node._fields"의 각 필드에 대해 "(fieldname,
   value)" 튜플을 산출합니다.

ast.iter_child_nodes(node)

   *node*의 모든 직접 자식 노드, 즉 노드인 모든 필드와 노드 리스트인
   필드의 모든 항목을 산출합니다.

ast.walk(node)

   *node*로 시작하는 트리(*node* 자체를 포함합니다)의 모든 자손 노드를
   지정된 순서 없이 재귀적으로 산출합니다. 이는 노드를 제자리에서 수정
   하고 문맥을 신경 쓰지 않을 때 유용합니다.

class ast.NodeVisitor

   추상 구문 트리를 걷고 발견된 모든 노드에 대해 방문자 함수를 호출하
   는 노드 방문자 베이스 클래스. 이 함수는 "visit()" 메서드에 의해 전
   달되는 값을 반환할 수 있습니다.

   이 클래스는 서브 클래싱하고자 하는 것이며, 서브 클래스는 방문자 메
   서드를 추가합니다.

   visit(node)

      노드를 방문합니다. 기본 구현은 "self.visit_*classname*"이라는 메
      서드를 호출하는데, 여기서 *classname* 은 노드 클래스의 이름입니
      다. 또는 이 메서드가 없으면 "generic_visit()"를 호출합니다.

   generic_visit(node)

      이 방문자는 노드의 자식에 대해 "visit()"를 호출합니다.

      방문자가 "generic_visit()"를 호출하거나 직접 방문하지 않는 한,
      사용자 정의 방문자 메서드가 있는 노드의 자식 노드는 방문 되지 않
      음에 유의하십시오.

   탐색 중에 노드에 변경 사항을 적용하려면 "NodeVisitor"를 사용하지 마
   십시오. 이를 위해 수정을 허락하는 특수한 방문자("NodeTransformer")
   가 있습니다.

   버전 3.8부터 폐지: 메서드 "visit_Num()", "visit_Str()",
   "visit_Bytes()", "visit_NameConstant()" 및 "visit_Ellipsis()"는 이
   제 폐지되었고 향후 파이썬 버전에서는 호출되지 않을 것입니다. 모든
   상수 노드를 처리하려면 "visit_Constant()" 메서드를 추가하십시오.

class ast.NodeTransformer

   추상 구문 트리를 걷고 노드 수정을 허락하는 "NodeVisitor" 서브 클래
   스.

   "NodeTransformer"는 AST를 걷고 방문자 메서드의 반환 값을 사용하여
   이전 노드를 바꾸거나 제거합니다. 방문자 메서드의 반환 값이 "None"이
   면, 노드가 그 위치에서 제거되고, 그렇지 않으면 반환 값으로 치환됩니
   다. 반환 값은 원래 노드일 수 있으며, 이때는 치환이 일어나지 않습니
   다.

   다음은 모든 이름 조회("foo")를 "data['foo']"로 다시 쓰는 변환기 예
   제입니다:

      class RewriteName(NodeTransformer):

          def visit_Name(self, node):
              return Subscript(
                  value=Name(id='data', ctx=Load()),
                  slice=Index(value=Constant(value=node.id)),
                  ctx=node.ctx
              )

   작업 중인 노드에 자식 노드가 있으면 자식 노드를 직접 변환하거나 노
   드에 대한 "generic_visit()" 메서드를 먼저 호출해야 함을 염두에 두십
   시오.

   문장의 컬렉션의 일부인 노드의 경우 (모든 문장 노드에 적용됩니다),
   방문자는 단일 노드가 아닌 노드 리스트를 반환 할 수도 있습니다.

   "NodeTransformer"가 위치 정보(가령 "lineno")를 제공하지 않고 (원래
   트리의 일부가 아닌) 새 노드를 도입하면, 위치 정보를 다시 계산하려면
   "fix_missing_locations()"를 새 서브 트리로 호출해야 합니다:

      tree = ast.parse('foo', mode='eval')
      new_tree = fix_missing_locations(RewriteName().visit(tree))

   일반적으로 다음과 같이 변환기를 사용합니다:

      node = YourTransformer().visit(node)

ast.dump(node, annotate_fields=True, include_attributes=False)

   *node*에서 포맷된 트리 덤프를 반환합니다. 이것은 주로 디버깅 목적으
   로 유용합니다. *annotate_fields*가 참이면 (기본값), 반환된 문자열에
   필드의 이름과 값이 표시됩니다. *annotate_fields*가 거짓이면, 모호하
   지 않은 필드 이름을 생략하여 결과 문자열이 더 간결해집니다. 줄 번호
   와 열 오프셋과 같은 어트리뷰트는 기본적으로 덤프 되지 않습니다. 원
   한다면, *include_attributes*를 참으로 설정할 수 있습니다.

더 보기:

  Green Tree Snakes, 파이썬 AST로 작업하는 것에 대한 자세한 내용이 있
  는 외부 문서 자원.

  ASTTokens는 토큰의 위치와 토큰을 생성한 소스 코드의 텍스트로 파이썬
  AST에 주석을 추가합니다. 이는 소스 코드 변환을 수행하는 도구에 유용
  합니다.

  leoAst.py는 토큰과 ast 노드 사이에 양방향 링크를 삽입하여 파이썬 프
  로그램의 토큰 기반과 구문 분석 트리 기반 뷰를 통합합니다.

  LibCST는 코드를 ast 트리처럼 보이고 모든 포매팅 세부 정보를 유지하는
  구상 구문 트리(Concrete Syntax Tree)로 구문 분석합니다. 자동화된 리
  팩토링 (codemod) 응용 프로그램과 린터(linter)를 구축하는 데 유용합니
  다.

  Parso는 다른 파이썬 버전(여러 Python 버전에서)에 대한 에러 복구와 왕
  복 구문 분석(round-trip parsing)을 지원하는 파이썬 파서입니다. Parso
  는 여러분의 파이썬 파일에 있는 여러 구문 에러를 나열 할 수도 있습니
  다.
