xml.sax.xmlreader — Interface for XML parsers

Вихідний код: Lib/xml/sax/xmlreader.py

Парсери SAX реалізують інтерфейс XMLReader. Вони реалізовані в модулі Python, який повинен надавати функцію create_parser(). Ця функція викликається xml.sax.make_parser() без аргументів для створення нового об’єкта аналізатора.

class xml.sax.xmlreader.XMLReader

Базовий клас, який може бути успадкований аналізаторами SAX.

class xml.sax.xmlreader.IncrementalParser

У деяких випадках бажано не аналізувати джерело введення відразу, а подавати фрагменти документа, коли вони стають доступними. Зауважте, що читач зазвичай читатиме не весь файл, а також його частини; все одно parse() не повернеться, доки не буде оброблено весь документ. Тому ці інтерфейси слід використовувати, якщо блокуюча поведінка parse() є небажаною.

Коли аналізатор створено, він готовий негайно почати приймати дані з методу каналу. Після завершення синтаксичного аналізу з викликом для закриття потрібно викликати метод reset, щоб зробити аналізатор готовим приймати нові дані, або з каналу, або за допомогою методу аналізу.

Зауважте, що ці методи не можна викликати під час синтаксичного аналізу, тобто після виклику аналізу та до його повернення.

За замовчуванням клас також реалізує метод синтаксичного аналізу інтерфейсу XMLReader за допомогою методів feed, close і reset інтерфейсу IncrementalParser для зручності авторів драйверів SAX 2.0.

class xml.sax.xmlreader.Locator

Інтерфейс для зв’язування події SAX із розташуванням документа. Об’єкт локатора поверне дійсні результати лише під час викликів методів DocumentHandler; в будь-який інший час результати непередбачувані. Якщо інформація недоступна, методи можуть повернути None.

class xml.sax.xmlreader.InputSource(system_id=None)

Інкапсуляція інформації, необхідної XMLReader для читання сутностей.

Цей клас може містити інформацію про загальнодоступний ідентифікатор, ідентифікатор системи, потік байтів (можливо, з інформацією про кодування символів) та/або потік символів сутності.

Програми створюватимуть об’єкти цього класу для використання в методі XMLReader.parse() і для повернення з EntityResolver.resolveEntity.

InputSource належить програмі, XMLReader не дозволяється змінювати об’єкти InputSource, передані йому з програми, хоча він може робити копії та змінювати їх.

class xml.sax.xmlreader.AttributesImpl(attrs)

Це реалізація інтерфейсу Attributes (див. розділ Інтерфейс Attributes). Це об’єкт, схожий на словник, який представляє атрибути елемента у виклику startElement(). Окрім найкорисніших операцій зі словником, він підтримує низку інших методів, як описано в інтерфейсі. Об’єкти цього класу повинні створюватися читачами; attrs має бути об’єктом, подібним до словника, який містить відображення імен атрибутів у значення атрибутів.

class xml.sax.xmlreader.AttributesNSImpl(attrs, qnames)

Варіант AttributesImpl з урахуванням простору імен, який буде передано в startElementNS(). Він походить від AttributesImpl, але розуміє імена атрибутів як два кортежі namespaceURI і localname. Крім того, він надає низку методів очікування кваліфікованих імен, як вони з’являються в оригінальному документі. Цей клас реалізує інтерфейс AttributesNS (див. розділ Інтерфейс AttributesNS).

Об’єкти XMLReader

Інтерфейс XMLReader підтримує такі методи:

XMLReader.parse(source)

Обробляти джерело вхідних даних, створюючи події SAX. Об’єкт джерело може бути системним ідентифікатором (рядок, що ідентифікує джерело вхідних даних – зазвичай це ім’я файлу або URL-адреса), об’єктом pathlib.Path або path-like або об’єкт InputSource. Коли parse() повертається, введення повністю оброблено, а об’єкт парсера можна відкинути або скинути.

Змінено в версії 3.5: Додано підтримку потоків символів.

Змінено в версії 3.8: Додано підтримку шляхоподібних об’єктів.

XMLReader.getContentHandler()

Повертає поточний ContentHandler.

XMLReader.setContentHandler(handler)

Установіть поточний ContentHandler. Якщо ContentHandler не встановлено, події вмісту буде відхилено.

XMLReader.getDTDHandler()

Повертає поточний DTDHandler.

XMLReader.setDTDHandler(handler)

Установіть поточний DTDHandler. Якщо DTDHandler не встановлено, події DTD будуть відхилені.

XMLReader.getEntityResolver()

Повертає поточний EntityResolver.

XMLReader.setEntityResolver(handler)

Установіть поточний EntityResolver. Якщо EntityResolver не встановлено, спроби розпізнати зовнішню сутність призведуть до відкриття системного ідентифікатора для цієї сутності та завершаться помилкою, якщо він недоступний.

XMLReader.getErrorHandler()

Повертає поточний ErrorHandler.

XMLReader.setErrorHandler(handler)

Встановити поточний обробник помилок. Якщо ErrorHandler не встановлено, помилки будуть викликані як винятки, а попередження будуть надруковані.

XMLReader.setLocale(locale)

Дозволити програмі встановлювати мову для помилок і попереджень.

Синтаксичним аналізаторам SAX не потрібно забезпечувати локалізацію помилок і попереджень; однак, якщо вони не можуть підтримувати запитану локаль, вони повинні викликати виняток SAX. Програми можуть запитувати зміну локалі в середині аналізу.

XMLReader.getFeature(featurename)

Повернути поточне налаштування для функції назва функції. Якщо функція не розпізнається, виникає SAXNotRecognizedException. Добре відомі назви функцій перераховані в модулі xml.sax.handler.

XMLReader.setFeature(featurename, value)

Встановіть назва функції на значення. Якщо функція не розпізнається, виникає SAXNotRecognizedException. Якщо функція або її параметри не підтримуються аналізатором, виникає SAXNotSupportedException.

XMLReader.getProperty(propertyname)

Повернути поточне налаштування властивості propertyname. Якщо властивість не розпізнається, виникає SAXNotRecognizedException. Добре відомі назви властивостей перераховані в модулі xml.sax.handler.

XMLReader.setProperty(propertyname, value)

Установіть propertyname на value. Якщо властивість не розпізнається, виникає SAXNotRecognizedException. Якщо властивість або її налаштування не підтримується аналізатором, виникає SAXNotSupportedException.

Інкрементальний аналізатор об’єктів

Екземпляри IncrementalParser пропонують такі додаткові методи:

IncrementalParser.feed(data)

Обробити фрагмент даних.

IncrementalParser.close()

Припустимо кінець документа. Це перевірить правильно сформовані умови, які можна перевірити лише в кінці, викличе обробники та може очистити ресурси, виділені під час аналізу.

IncrementalParser.reset()

Цей метод викликається після виклику close, щоб скинути синтаксичний аналізатор, щоб він був готовий аналізувати нові документи. Результати виклику parse або feed після закриття без виклику reset не визначені.

Локатор об’єктів

Екземпляри Locator надають ці методи:

Locator.getColumnNumber()

Повертає номер стовпця, де починається поточна подія.

Locator.getLineNumber()

Повертає номер рядка, де починається поточна подія.

Locator.getPublicId()

Повернути публічний ідентифікатор для поточної події.

Locator.getSystemId()

Повертає ідентифікатор системи для поточної події.

Об’єкти InputSource

InputSource.setPublicId(id)

Встановлює публічний ідентифікатор цього InputSource.

InputSource.getPublicId()

Повертає публічний ідентифікатор цього InputSource.

InputSource.setSystemId(id)

Встановлює системний ідентифікатор цього InputSource.

InputSource.getSystemId()

Повертає системний ідентифікатор цього InputSource.

InputSource.setEncoding(encoding)

Встановлює кодування символів цього InputSource.

Кодування має бути рядком, прийнятним для декларації кодування XML (див. розділ 4.3.3 рекомендації XML).

Атрибут кодування InputSource ігнорується, якщо InputSource також містить потік символів.

InputSource.getEncoding()

Отримайте кодування символів цього InputSource.

InputSource.setByteStream(bytefile)

Установіть потік байтів (binary file) для цього джерела вхідних даних.

Синтаксичний аналізатор SAX ігноруватиме це, якщо також буде вказано потік символів, але він використовуватиме потік байтів замість відкриття самого URI-з’єднання.

Якщо програма знає кодування символів потоку байтів, вона повинна встановити її за допомогою методу setEncoding.

InputSource.getByteStream()

Отримайте потік байтів для цього джерела вхідних даних.

Метод getEncoding поверне кодування символів для цього потоку байтів або None, якщо невідомо.

InputSource.setCharacterStream(charfile)

Установіть потік символів (text file) для цього джерела введення.

Якщо вказано потік символів, аналізатор SAX ігноруватиме будь-який потік байтів і не намагатиметься відкрити з’єднання URI із системним ідентифікатором.

InputSource.getCharacterStream()

Отримайте потік символів для цього джерела введення.

Інтерфейс Attributes

Об’єкти Attributes реалізують частину протоколу відображення, включаючи методи copy(), get(), __contains__(), items(), keys() і values(). Також передбачені такі методи:

Attributes.getLength()

Повертає кількість атрибутів.

Attributes.getNames()

Повернути назви атрибутів.

Attributes.getType(name)

Повертає тип атрибута name, який зазвичай є 'CDATA'.

Attributes.getValue(name)

Повертає значення атрибута name.

Інтерфейс AttributesNS

Цей інтерфейс є підтипом інтерфейсу Attributes (див. розділ Інтерфейс Attributes). Усі методи, які підтримує цей інтерфейс, також доступні в об’єктах AttributesNS.

Також доступні такі методи:

AttributesNS.getValueByQName(name)

Повертає значення для кваліфікованого імені.

AttributesNS.getNameByQName(name)

Повертає пару (простір імен, локальне ім’я) для кваліфікованого назви.

AttributesNS.getQNameByName(name)

Повертає кваліфіковане ім’я для пари (простір імен, локальне ім’я).

AttributesNS.getQNames()

Повертає кваліфіковані імена всіх атрибутів.