---
title: Извлечь типизированные данные из HTML
description: Свяжите поля модели с CSS- или XPath-селекторами и разберите HTML-ответ операции.
sources:
  - eazy_sdk_html.parse_html
  - eazy_sdk_html.CSS
  - eazy_sdk_html.XPath
  - eazy_sdk_html.Scope
  - eazy_sdk_html.Regex
  - eazy_sdk.response.Html
api_fingerprint: "sha256:76c3c0140f33c692c11d72331eedf47ebcb48bf7e73bfe35ccefb5176632bd5d"
---

Поля документной модели несут CSS- или XPath-селекторы. SDK сначала строит дерево HTML, затем
извлекает простые значения и передаёт их настроенному адаптеру моделей.

Модель остаётся обычным `dataclass`.

:::::{grid} 1 1 2 2
:class-container: http-exchange
:gutter: 2
::::{grid-item}
:class: http-panel http-panel--request
**→ Request** · ``GET /catalogue/page-1.html``
::::
::::{grid-item}
:class: http-panel http-panel--response
**← Response** · ``200 OK``
```html
<h1>Mailbox library</h1>
<article class="book">
  <a href="sdk-patterns.html">SDK Patterns</a><span>12.50</span>
</article>
```
::::
:::::

```{literalinclude} ../../../../../../examples/docs/response_html.py
:language: python
:start-after: "# docs:models:start"
:end-before: "# docs:models:end"
```

`CSS("a::text")` читает текст одного узла. `Scope(CSS("article.book"))` создаёт отдельный
контекст для каждой карточки и строит список `Book`. Необязательное поле получает `None`, если
селектор ничего не нашёл; обязательное поле приводит к `ExtractionError` с путём модели.

```{literalinclude} ../../../../../../examples/docs/response_html.py
:language: python
:start-after: "# docs:operation:start"
:end-before: "# docs:operation:end"
```

Селекторы в `Catalogue` сообщают компилятору, что ответ нужно читать как документ. Модель без
селекторов на том же месте читалась бы как JSON. Явное представление `Html(Model)` нужно для
особого статуса, типа содержимого или условия.

:::{dropdown} Файл примера целиком
```{literalinclude} ../../../../../../examples/docs/response_html.py
:language: python
```
:::

Запуск: `uv run python examples/docs/response_html.py`.

<!-- example-output: examples.docs.response_html -->
```text
Mailbox library: 2 books
first: SDK Patterns 12.50
next: page-2.html
```

По умолчанию HTML читает Parsel с поддержкой CSS и XPath. Другой документный бэкенд задаётся в
`Serialization(documents=(...))` на корне. Компилятор заранее проверяет, что бэкенд понимает язык
каждого селектора.
Для отдельного HTML-фрагмента без HTTP используйте `parse_html(data, Model)`. Он применяет ту же
модель, селекторы и адаптеры.

## Достать значение из встроенного скрипта

Токен страницы часто лежит внутри `<script>`, и разметкой к нему не подойти. Селектор `Regex`
ищет по тексту документа и стоит на поле рядом с `CSS` и `XPath`.

```{literalinclude} ../../../../../../examples/docs/response_regex.py
:language: python
:start-after: "# docs:example:start"
:end-before: "# docs:example:end"
```

Шаблон с одной группой отдаёт в поле эту группу, шаблон без групп отдаёт всё совпадение. Две
группы и больше считаются ошибкой объявления. Поле с одним значением получает первое совпадение,
поле-список получает все.

На странице примера ключ `token` встречается дважды, и первым идёт чужой. Поле `token` привязано
к ключу `account`, поэтому получает нужное значение, а `every_token` показывает оба.

Поиск идёт по тексту в том виде, в каком его прислал сервис. Сущности вида `&amp;` не
раскрываются, содержимое скрипта не разбирается. Второй аргумент принимает флаги модуля `re`.

`title` с `Const("Mail")` отличает страницу почты от страницы входа, которую сайт отдаёт с тем же
статусом `200`. Поле из куки или заголовка того же ответа добавляется в эту же модель маркерами
`FromCookie` и `FromHeader`.

:::{dropdown} Файл примера целиком
```{literalinclude} ../../../../../../examples/docs/response_regex.py
:language: python
```
:::

Запуск: `uv run python examples/docs/response_regex.py`.

<!-- example-output: examples.docs.response_regex -->
```text
title: Mail
token: page-token-42
email: ada@mail.example
every token: ads-token, page-token-42
```

## Значение, которое лежит то в странице, то в куке

Сайт не всегда держит значение в одном месте: токен формы у одного клиента стоит в странице, у
другого в куке. Поле называет оба источника через `|`, в том порядке, в каком их пробовать.

```{literalinclude} ../../../../../../examples/docs/response_first_of.py
:language: python
:start-after: "# region docs: response-first-of"
:end-before: "# endregion docs: response-first-of"
```

Поле получает первое найденное значение. В цепочку входят селекторы `CSS`, `XPath`, `Regex` и
источники вне тела: `FromHeader`, `FromCookie`, `Location.query(...)`. Обязательное поле, которого
нет ни в одном источнике, даёт `MalformedResponseError`. Такое поле делает модель различимой:
страница без токена под неё не подходит, и условие `when=` для этого не нужно.

Запуск: `uv run python -m examples.docs.response_first_of`.

<!-- example-output: examples.docs.response_first_of -->
```text
page has it: from-page
only the cookie has it: from-cookie
nowhere: MalformedResponseError
```

## Дальше

- {doc}`Проверьте контракт документного ответа </reference/api/response>`.
- {doc}`Настройте модели и адаптеры </integrations/models/index>`.
- {doc}`Разберите неизвестный ответ </guide/responses/errors>`.