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)

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