"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""
      데이터형: 문자열
      설명: 현재 이벤트의 소스인 리터럴 문자열.
      액세스: 읽기 전용

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)

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