# `xml.sax.handler` — SAX 처리기의 베이스 클래스

소스 코드: Lib/xml/sax/handler.py

SAX API는 네 가지 처리기를 정의합니다: 콘텐츠 처리기, DTD 처리기, 에러 처리기 및 엔티티 해석기. 응용 프로그램은 일반적으로 이벤트에 관심이 있는 인터페이스 만 구현하면 됩니다; 단일 객체나 여러 객체에서 인터페이스를 구현할 수 있습니다. 처리기 구현은 모든 메서드가 기본 구현을 갖도록 `xml.sax.handler` 모듈에서 제공된 베이스 클래스에서 상속해야 합니다.

class `xml.sax.handler.``ContentHandler`

  이것은 SAX의 주 콜백 인터페이스이며, 응용 프로그램에 가장 중요한 인터페이스입니다. 이 인터페이스의 이벤트 순서는 문서에서의 정보 순서를 반영합니다.

class `xml.sax.handler.``DTDHandler`

  DTD 이벤트를 처리합니다.

  이 인터페이스는 기본 구문 분석에 필요한 DTD 이벤트만 지정합니다 (구문 분석되지 않은 엔티티와 어트리뷰트).

class `xml.sax.handler.``EntityResolver`

  엔티티 해석을 위한 기본 인터페이스. 이 인터페이스를 구현하는 객체를 만든 후 구문 분석기에 객체를 등록하면, 구문 분석기는 객체의 메서드를 호출하여 모든 외부 엔티티를 해석합니다.

class `xml.sax.handler.``ErrorHandler`

  응용 프로그램에 에러와 경고 메시지를 표시하기 위해 구문 분석기에서 사용하는 인터페이스. 이 객체의 메서드는 에러가 즉시 예외로 변환되는지 또는 다른 방식으로 처리되는지를 제어합니다.

이러한 클래스 외에도, `xml.sax.handler`는 기능과 속성 이름에 대한 기호 상수를 제공합니다.

`xml.sax.handler.``feature_namespaces`
  값: `"http://xml.org/sax/features/namespaces"`
  참: 이름 공간 처리를 수행합니다.
  거짓: 선택적으로 이름 공간 처리를 수행하지 않습니다 (namespace-prefixes를 암시합니다; 기본값).
  액세스: (구문 분석) 읽기 전용; (구문 분석하지 않음) 읽기/쓰기

`xml.sax.handler.``feature_namespace_prefixes`
  값: `"http://xml.org/sax/features/namespace-prefixes"`
  참: 이름 공간 선언에 사용된 원래 접두사 이름과 어트리뷰트를 보고합니다.
  거짓: 이름 공간 선언에 사용된 어트리뷰트를 보고하지 않고, 선택적으로 원래 접두사 이름을 보고하지 않습니다 (기본값).
  액세스: (구문 분석) 읽기 전용; (구문 분석하지 않음) 읽기/쓰기

`xml.sax.handler.``feature_string_interning`
  값: `"http://xml.org/sax/features/string-interning"`
  참: 모든 엘리먼트 이름, 접두사, 어트리뷰트 이름, 이름 공간 URI 및 지역 이름은 내장 intern 함수를 사용하여 인턴 됩니다.
  거짓: 그럴 수 있지만, 이름이 반드시 인턴 될 필요는 없습니다 (기본값).
  액세스: (구문 분석) 읽기 전용; (구문 분석하지 않음) 읽기/쓰기

`xml.sax.handler.``feature_validation`
  값: `"http://xml.org/sax/features/validation"`
  참: 모든 유효성 검사 에러를 보고합니다 (external-general-entities와 external-parameter-entities를 암시합니다).
  거짓: 유효성 검사 에러를 보고하지 않습니다.
  액세스: (구문 분석) 읽기 전용; (구문 분석하지 않음) 읽기/쓰기

`xml.sax.handler.``feature_external_ges`
  값: `"http://xml.org/sax/features/external-general-entities"`
  참: 모든 외부 일반 (텍스트) 엔티티를 포함합니다.
  거짓: 외부 일반 엔티티를 포함하지 않습니다.
  액세스: (구문 분석) 읽기 전용; (구문 분석하지 않음) 읽기/쓰기

`xml.sax.handler.``feature_external_pes`
  값: `"http://xml.org/sax/features/external-parameter-entities"`
  참: 외부 DTD 서브 세트를 포함하여, 모든 외부 파라미터 엔티티를 포함합니다.
  거짓: 외부 DTD 서브 세트를 포함하여, 어떤 외부 파라미터 엔티티도 포함하지 않습니다.
  액세스: (구문 분석) 읽기 전용; (구문 분석하지 않음) 읽기/쓰기

`xml.sax.handler.``all_features`

  모든 기능 리스트.

`xml.sax.handler.``property_lexical_handler`
  값: `"http://xml.org/sax/properties/lexical-handler"`
  데이터형: xml.sax.sax2lib.LexicalHandler (파이썬 2에서는 지원되지 않습니다)
  설명: 주석과 같은 어휘 이벤트에 대한 선택적 확장 처리기.
  액세스: 읽기/쓰기

`xml.sax.handler.``property_declaration_handler`
  값: `"http://xml.org/sax/properties/declaration-handler"`
  데이터형: xml.sax.sax2lib.DeclHandler (파이썬 2에서는 지원되지 않습니다)
  설명: 표기법과 구문 분석되지 않은 엔티티 이외의 DTD 관련 이벤트에 대한 선택적 확장 처리기.
  액세스: 읽기/쓰기

`xml.sax.handler.``property_dom_node`
  값: `"http://xml.org/sax/properties/dom-node"`
  데이터형: org.w3c.dom.Node (파이썬 2에서는 지원되지 않습니다)
  설명: 구문 분석할 때, 이것이 DOM 이터레이터이면 방문 중인 현재 DOM 노드; 구문 분석하지 않을 때, 이터레이션을 위한 루트 DOM 노드.
  액세스: (구문 분석) 읽기 전용; (구문 분석하지 않음) 읽기/쓰기

`xml.sax.handler.``property_xml_string`
  값: `"http://xml.org/sax/properties/xml-string"`
  data type: Bytes
  설명: 현재 이벤트의 소스인 리터럴 문자열.
  액세스: 읽기 전용

`xml.sax.handler.``all_properties`

  알려진 모든 속성 이름 리스트

## ContentHandler 객체

사용자는 자신의 응용 프로그램을 지원하기 위해 `ContentHandler`를 서브 클래싱 할 것으로 기대됩니다. 입력 문서에서 적절한 이벤트에 대해 구문 분석기가 다음 메서드를 호출합니다:

`ContentHandler.``setDocumentLocator`(locator)

  응용 프로그램에 문서 이벤트의 출처를 찾기 위한 로케이터(locator)를 제공하기 위해 구문 분석기가 호출합니다.

  SAX 구문 분석기가 (절대적으로 필요한 것은 아니지만) 로케이터를 제공할 것을 강력히 권장합니다: 그렇게 한다면, DocumentHandler 인터페이스의 다른 메서드를 호출하기 전에 이 메서드를 호출하여 로케이터를 응용 프로그램에 제공해야 합니다.

  로케이터를 사용하면 구문 분석기가 에러를 보고하지 않더라도 응용 프로그램이 문서 관련 이벤트의 종료 위치를 판별할 수 있습니다. 일반적으로, 응용 프로그램은 이 정보를 사용하여 자체 에러(가령 응용 프로그램의 비즈니스 규칙과 일치하지 않는 문자 내용)를 보고합니다. 로케이터가 반환한 정보는 아마도 검색 엔진에 사용하기에는 충분하지 않을 것입니다.

  로케이터는 이 인터페이스에서 이벤트를 호출하는 동안에만 올바른 정보를 반환함에 유의하십시오. 응용 프로그램은 다른 시간에 사용하려고 시도해서는 안 됩니다.

`ContentHandler.``startDocument`()

  문서 시작 알림을 받습니다.

  SAX 구문 분석기는 이 인터페이스나 DTDHandler의 다른 모든 메서드(`setDocumentLocator()` 제외) 전에 이 메서드를 한 번만 호출합니다.

`ContentHandler.``endDocument`()

  문서 끝 알림을 받습니다.

  SAX 구문 분석기는 이 메서드를 한 번만 호출하며, 그것이 구문 분석 중에 마지막으로 호출된 메서드가 됩니다. 구문 분석기는 (복구할 수 없는 에러로 인해) 구문 분석을 포기했거나 입력 끝에 도달할 때까지 이 메서드를 호출하지 않아야 합니다.

`ContentHandler.``startPrefixMapping`(prefix, uri)

  접두사 URI 이름 공간 매핑의 스코프를 시작합니다.

  이 이벤트의 정보는 일반적인 이름 공간 처리에 필요하지 않습니다: SAX XML 판독기는 `feature_namespaces` 기능이 활성화되면 (기본값) 엘리먼트와 어트리뷰트 이름의 접두사를 자동으로 대체합니다.

  그러나, 응용 프로그램이 문자 데이터나 어트리뷰트 값에 접두사를 사용해야 할 때 자동으로 안전하게 확장할 수 없는 경우가 있습니다; `startPrefixMapping()` 과 `endPrefixMapping()` 이벤트는 필요한 경우 해당 컨텍스트에서 스스로 접두사를 확장하도록 정보를 응용 프로그램에 제공합니다.

  `startPrefixMapping()` 과 `endPrefixMapping()` 이벤트는 서로에 대해 올바르게 중첩된다고 보장되지 않음에 유의하십시오: 모든 `startPrefixMapping()` 이벤트는 해당 `startElement()` 이벤트 전에 발생하고, 모든 `endPrefixMapping()` 이벤트는 해당 `endElement()` 이벤트 후에 발생하지만, 그들 간의 순서는 보장되지 않습니다.

`ContentHandler.``endPrefixMapping`(prefix)

  접두사 URI 매핑 스코프를 끝냅니다.

  자세한 내용은 `startPrefixMapping()` 을 참조하십시오. 이 이벤트는 항상 해당 `endElement()` 이벤트 이후에 발생하지만, `endPrefixMapping()` 이벤트의 순서는 이 이상으로는 보장되지 않습니다.

`ContentHandler.``startElement`(name, attrs)

  이름 공간이 아닌 모드에서 엘리먼트의 시작을 알립니다.

  name 매개 변수는 엘리먼트 유형의 원시 XML 1.0 이름을 문자열로 포함하고 attrs 매개 변수는 엘리먼트의 어트리뷰트를 포함하는 `Attributes` 인터페이스 (Attributes 인터페이스를 참조하십시오)의 객체를 담습니다. attrs로 전달된 객체는 구문 분석기에 의해 재사용 될 수 있습니다; 그것에 대한 참조를 유지하는 것은 어트리뷰트의 사본을 유지하는 신뢰할 수 있는 방법이 아닙니다. 어트리뷰트의 사본을 유지하려면, attrs 객체의 `copy()` 메서드를 사용하십시오.

`ContentHandler.``endElement`(name)

  이름 공간이 아닌 모드에서 엘리먼트의 끝을 알립니다.

  name 매개 변수는 `startElement()` 이벤트와 마찬가지로 엘리먼트 유형의 이름을 포함합니다.

`ContentHandler.``startElementNS`(name, qname, attrs)

  이름 공간 모드에서 엘리먼트의 시작을 알립니다.

  name 매개 변수는 엘리먼트 유형의 이름을 `(uri, localname)` 튜플로 포함하고, qname 매개 변수는 소스 문서에서 사용된 원시 XML 1.0 이름을 포함하며, attrs 매개 변수는 엘리먼트의 어트리뷰트를 포함하는 `AttributesNS` 인터페이스(AttributesNS 인터페이스를 참조하십시오)의 인스턴스를 담습니다. 아무런 이름 공간도 엘리먼트와 연관되지 않았으면 name의 uri 구성 요소는 `None`입니다. attrs로 전달된 객체는 구문 분석기에 의해 재사용 될 수 있습니다; 그것에 대한 참조를 유지하는 것은 어트리뷰트의 사본을 유지하는 신뢰할 수 있는 방법이 아닙니다. 어트리뷰트의 사본을 유지하려면 attrs 객체의 `copy()` 메서드를 사용하십시오.

  `feature_namespace_prefixes` 기능이 활성화되지 않는 한, 구문 분석기는 qname 매개 변수를 `None`으로 설정할 수 있습니다.

`ContentHandler.``endElementNS`(name, qname)

  이름 공간 모드에서 엘리먼트의 끝을 알립니다.

  name 매개 변수는 `startElementNS()` 메서드와 마찬가지로 qname 매개 변수처럼 엘리먼트 유형의 이름을 포함합니다.

`ContentHandler.``characters`(content)

  문자 데이터의 알림을 받습니다.

  구문 분석기는 이 메서드를 호출하여 각 문자 데이터 청크를 보고합니다. SAX 구문 분석기는 연속된 모든 문자 데이터를 단일 청크로 반환하거나 여러 청크로 분할할 수 있습니다; 그러나, 로케이터가 유용한 정보를 제공할 수 있도록, 단일 이벤트의 모든 문자는 같은 외부 엔티티에서 온 것이어야 합니다.

  content는 문자열이나 바이트열 인스턴스일 수 있습니다; `expat` 판독기 모듈은 항상 문자열을 생성합니다.

  참고

  Python XML Special Interest Group에서 제공된 이전 SAX 1 인터페이스는 이 메서드에 더 Java와 유사한 인터페이스를 사용했습니다. 파이썬에서 사용되는 대부분의 구문 분석기가 구식 인터페이스의 장점을 취하지 않았기 때문에, 더 간단한 서명으로 변경했습니다. 이전 코드를 새 인터페이스로 변환하려면, 이전 offset과 length 매개 변수로 콘텐츠를 슬라이싱하는 대신 content를 사용하십시오.

`ContentHandler.``ignorableWhitespace`(whitespace)

  엘리먼트 내용에서 무시할 수 있는 공백에 대한 알림을 받습니다.

  유효성 검사 구문 분석기는 무시할 수 있는 공백의 각 청크를 보고하기 위해 이 메서드를 사용해야 합니다 (W3C XML 1.0 권장 사항, 섹션 2.10을 참조하십시오).

  SAX 구문 분석기는 모든 연속적인 공백을 단일 청크로 반환하거나 여러 청크로 나눌 수 있습니다; 그러나 로케이터가 유용한 정보를 제공할 수 있도록, 단일 이벤트의 모든 문자는 같은 외부 엔티티에서 온 것이어야 합니다.

`ContentHandler.``processingInstruction`(target, data)

  처리 명령의 알림을 받습니다.

  구문 분석기는 발견된 각 처리 명령에 대해 이 메서드를 한 번 호출합니다: 처리 명령은 메인 문서 엘리먼트 전후에 발생할 수 있음에 유의하십시오.

  SAX 구문 분석기는 이 메서드를 사용하여 XML 선언(XML 1.0, 섹션 2.8)이나 텍스트 선언(XML 1.0, 섹션 4.3.1)을 보고해서는 안 됩니다.

`ContentHandler.``skippedEntity`(name)

  건너뛴 엔티티의 알림을 받습니다.

  구문 분석기는 각 엔티티를 건너뛸 때마다 이 메서드를 한 번 호출합니다. 유효성을 검사하지 않는 프로세서는 선언을 보지 않으면 엔티티를 건너뛸 수 있습니다 (예를 들어 엔티티가 외부 DTD 서브 세트에서 선언되었기 때문에). `feature_external_ges`와 `feature_external_pes` 속성의 값에 따라, 모든 프로세서가 외부 엔티티를 건너뛸 수 있습니다.

## DTDHandler 객체

`DTDHandler` 인스턴스는 다음 메서드를 제공합니다:

`DTDHandler.``notationDecl`(name, publicId, systemId)

  표기법 선언 이벤트를 처리합니다.

`DTDHandler.``unparsedEntityDecl`(name, publicId, systemId, ndata)

  구문 분석되지 않은 엔티티 선언 이벤트를 처리합니다.

## EntityResolver 객체

`EntityResolver.``resolveEntity`(publicId, systemId)

  엔티티의 시스템 식별자를 해석하고 읽을 시스템 식별자를 문자열로 반환하거나, 읽을 InputSource를 반환합니다. 기본 구현은 systemId를 반환합니다.

## ErrorHandler 객체

이 인터페이스를 갖는 객체는 `XMLReader`에서 에러와 경고 정보를 받는 데 사용됩니다. 이 인터페이스를 구현하는 객체를 만든 다음 `XMLReader`에 객체를 등록하면, 구문 분석기는 객체의 메서드를 호출하여 모든 경고와 에러를 보고합니다. 세 가지 수준의 에러가 있습니다: 경고, (어쩌면) 복구 가능한 에러 및 복구 불가능한 에러. 모든 메서드는 `SAXParseException`를 유일한 매개 변수로 취합니다. 전달된 예외 객체를 발생 시켜 에러와 경고를 예외로 변환할 수 있습니다.

`ErrorHandler.``error`(exception)

  구문 분석기가 복구 가능한 에러를 만나면 호출됩니다. 이 메서드가 예외를 발생시키지 않으면, 구문 분석이 계속될 수 있지만, 응용 프로그램에서 추가 문서 정보를 기대하지 않아야 합니다. 구문 분석기가 계속되도록 허용하면 입력 문서에서 추가 에러가 발견될 수 있습니다.

`ErrorHandler.``fatalError`(exception)

  구문 분석기가 복구 불가능한 에러를 만나면 호출됩니다; 이 메서드가 반환될 때 구문 분석이 종료될 것으로 기대합니다.

`ErrorHandler.``warning`(exception)

  구문 분석기가 응용 프로그램에 경미한 경고 정보를 제공할 때 호출됩니다. 이 메서드가 반환될 때 구문 분석이 계속될 것으로 기대되며, 문서 정보는 계속 응용 프로그램에 전달됩니다. 이 메서드에서 예외를 발생시키면 구문 분석이 종료됩니다.