"xml.sax.handler" --- Base classes for SAX handlers
***************************************************

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

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

The SAX API defines five kinds of handlers: content handlers, DTD
handlers, error handlers, entity resolvers and lexical handlers.
Applications normally only need to implement those interfaces whose
events they are interested in; they can implement the interfaces in a
single object or in multiple objects. Handler implementations should
inherit from the base classes provided in the module
"xml.sax.handler", so that all methods get default implementations.

class xml.sax.handler.ContentHandler

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

class xml.sax.handler.DTDHandler

   DTD 이벤트를 처리합니다.

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

class xml.sax.handler.EntityResolver

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

class xml.sax.handler.ErrorHandler

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

class xml.sax.handler.LexicalHandler

   Interface used by the parser to represent low frequency events
   which may not be of interest to many applications.

이러한 클래스 외에도, "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""
      data type: xml.sax.handler.LexicalHandler (not supported in Python 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 객체
=================

Objects with this interface are used to receive error and warning
information from the "XMLReader".  If you create an object that
implements this interface, then register the object with your
"XMLReader", the parser will call the methods in your object to report
all warnings and errors. There are three levels of errors available:
warnings, (possibly) recoverable errors, and unrecoverable errors.
All methods take a "SAXParseException" as the only parameter.  Errors
and warnings may be converted to an exception by raising the passed-in
exception object.

ErrorHandler.error(exception)

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

ErrorHandler.fatalError(exception)

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

ErrorHandler.warning(exception)

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


LexicalHandler Objects
======================

Optional SAX2 handler for lexical events.

This handler is used to obtain lexical information about an XML
document. Lexical information includes information describing the
document encoding used and XML comments embedded in the document, as
well as section boundaries for the DTD and for any CDATA sections. The
lexical handlers are used in the same manner as content handlers.

Set the LexicalHandler of an XMLReader by using the setProperty method
with the property identifier "'http://xml.org/sax/properties/lexical-
handler'".

LexicalHandler.comment(content)

   Reports a comment anywhere in the document (including the DTD and
   outside the document element).

LexicalHandler.startDTD(name, public_id, system_id)

   Reports the start of the DTD declarations if the document has an
   associated DTD.

LexicalHandler.endDTD()

   Reports the end of DTD declaration.

LexicalHandler.startCDATA()

   Reports the start of a CDATA marked section.

   The contents of the CDATA marked section will be reported through
   the characters handler.

LexicalHandler.endCDATA()

   Reports the end of a CDATA marked section.
