Skip to main content

geas

Тестовые контракты, JSON Schema, d42-схемы и operation-aware моки, сгенерированные из checked-in OpenAPI.

Geas — в ирландской и шотландской традиции обязательное условие, нарушение которого неизбежно имеет последствия. Здесь такое условие — OpenAPI-контракт: geas превращает его в исполняемые схемы и показывает место, где fixture, мок или настоящий запрос перестал ему соответствовать.

  • Версия: 0.8.0
  • Python: 3.10+
  • Ядро зависит только от jsonschema[format-nongpl] и PyYAML. d42 и JJ — опциональные extras.

Что делает geas

Мок в тесте отдаёт тело, написанное вручную. Когда бэкенд меняет схему, мок продолжает отдавать старое тело, и тест остаётся зелёным, хотя проверяет уже устаревшую фикстуру. geas связывает тесты со спецификацией:

  • генерирует из OpenAPI (Swagger 2.0 или OpenAPI 3.0.x) контракт каждой выбранной операции: JSON Schema тел, параметров и заголовков, d42-схемы тел запроса и ответа и d42-схемы параметров запроса в том виде, в каком значения уходят в запрос;
  • даёт типизированный доступ к операциям: operations.api.create_document;
  • проверяет моки: тело ответа — до регистрации мока, каждый перехваченный запрос — при выходе из блока;
  • генерирует фикстуры по контракту и позволяет подменить генераторы отдельных полей;
  • ловит drift в CI: geas check падает, если закоммиченные артефакты разошлись со спецификацией.

Неподдержанная конструкция спецификации ломает генерацию и никогда не превращается молча в «любое значение». Осознанное исключение оформляется waiver'ом с владельцем и сроком.

Установка

pip install geas            # контракты, JSON Schema, CLI, geas check
pip install 'geas[d42]'     # + d42-схемы, фикстуры, overlay'и
pip install 'geas[jj]'      # + operation-aware моки
pip install 'geas[all]'     # всё сразу
Extra Зависимость Что без него не работает
— — всё остальное работает: manifest, генерация, JSON Schema, CLI, validate_*
[d42] d42>=2.3,<3 d42-схемы, build_fixture, overlay_generators; update/check/diff, если d42 включён хотя бы у одной операции
[jj] jj>=2.9,<3 operation.mock()

Без нужного extra вы получите MissingExtraError с командой установки, например:

MissingExtraError: operation-aware моки требует опциональной зависимости. Установите: pip install 'geas[jj]'

MissingExtraError наследуется и от ContractError, и от ImportError.

В тестовом проекте фиксируйте точную версию geas. Версия генератора записывается в артефакты, и после её смены нужно выполнить geas update.

Быстрый старт

# 1. manifest и waivers
geas -m contracts/manifest.yaml init \
    --source ../api/openapi.yaml \
    --package app.contracts.generated \
    --directory ../app/contracts/generated

# 2. какие операции есть в спецификации
geas -m contracts/manifest.yaml list

# 3. добавить нужную операцию
geas -m contracts/manifest.yaml add api.createDocument --source main --operation-id createDocument

# 4. сгенерировать артефакты
geas -m contracts/manifest.yaml update

# 5. проверить, что артефакты совпадают со спецификацией (это же ставится в CI)
geas -m contracts/manifest.yaml check

Закоммитьте спецификацию, manifest, waivers.yaml и generated-каталог. Исключите generated-каталог из автоформатирования, иначе check будет падать:

[tool.ruff]
extend-exclude = ["**/generated/**"]

Все команды и флаги описаны в docs/cli.md. Если в проекте уже есть моки, написанные вручную, воспользуйтесь docs/migration.md. Полный рабочий пример лежит в examples/consumer.

Manifest

Manifest описывает, что генерировать и к какой операции спецификации привязан каждый ключ. Все пути в нём отсчитываются от каталога самого manifest.

version: 1

output:
  directory: app_contracts/generated     # generated-каталог
  package: app_contracts.generated       # имя, под которым его импортируют тесты

waivers: waivers.yaml                    # по умолчанию waivers.yaml рядом с manifest

policies:                                # необязательно; здесь значения по умолчанию
  waiver_max_days: 90
  waiver_warn_days: 14
  unknown_formats: reject

sources:
  main:
    path: api/openapi.yaml
    selection: explicit                  # explicit (по умолчанию) или all
    # root: api                          # корень для межфайловых $ref; по умолчанию каталог спецификации
    # base_path: /api/v1                 # префикс маршрутов
    # strip_prefix: /api/search          # снять префикс спецификации (см. ниже)
    # accept_trailing_slash: true        # сервер принимает /path и /path/ как один маршрут

operations:
  api.createDocument:                    # стабильный ключ операции
    source: main
    operation_id: createDocument
    method: POST
    path: /api/v1/workspaces/{workspaceId}/documents
    request: {content_type: application/json}
    responses:
      - {status: 201, content_type: application/json}
    python_path: [api, create_document]
    # non_waivable: [...]                # поля, которые нельзя ослабить, см. docs/waivers.md
    # d42: false                         # не генерировать d42-схемы для операции
    # accept_trailing_slash: true        # переопределяет настройку источника для этой операции

Записи операций обычно создаёт geas add, но их можно писать и вручную.

Ключ операции Значение
source имя источника; обязательно
operation_id operationId в спецификации
method, path маршрут; path указывается полностью, с префиксом источника
request.content_type закрепить одно тело запроса; остальные в контракт не попадут
responses закрепить варианты ответа (status — число или default, content_type необязателен); без списка берутся все
python_path путь в generated namespace, минимум два сегмента; по умолчанию каждый сегмент ключа переводится в snake_case (api.createDocument → api.create_document)
non_waivable поля, которые нельзя ослабить waiver'ом, см. docs/waivers.md
d42 false — не генерировать d42-схемы для операции
accept_trailing_slash true / false — переопределить настройку источника для операции; объект issue + reason + expires_at — включить временно, в обход дефекта спецификации. См. Слэш на конце маршрута

Операция связывается со спецификацией по operation_id, по паре method + path или по всем трём. Если один operationId встречается у нескольких ручек, укажите method и path.

Ключ операции — её стабильное имя в вашем проекте. Имя в тестах строится из ключа, а не из operationId, поэтому переименование operationId на бэкенде ломает привязку, но не меняет имя в тестах.

Префикс маршрута: в Swagger 2.0 basePath входит в маршрут автоматически, в OpenAPI 3.0 servers игнорируется. Чтобы задать или переопределить префикс, используйте base_path у источника.

Сервис за шлюзом: если спецификация описывает маршруты сервиса (/api/search/searchTicket), а клиент ходит через шлюз (/api/search-fulltext/search/searchTicket), задайте strip_prefix вместе с base_path:

sources:
  global_search:
    path: api/global-search/openapi-front.yaml
    strip_prefix: /api/search            # снимается с маршрута спецификации
    base_path: /api/search-fulltext/search   # добавляется вместо него

Маршрут операции становится base_path + маршрут спецификации без strip_prefix; в Swagger 2.0 маршрут спецификации включает basePath, а base_path при заданном strip_prefix только добавляется (не заменяет). Префикс снимается по границе сегмента. Если выбранная операция не лежит под strip_prefix, генерация падает с ошибкой привязки. В режиме explicit невыбранные операции вне префикса не мешают (geas list помечает их !); в режиме all выбраны все операции, поэтому любая из них вне префикса — ошибка. Во всех командах, в path операций manifest, drift-guard и матчере запросов используется итоговый маршрут. Если исходный путь операции вне префикса совпал с итоговым маршрутом другой, маршрут принадлежит отображённой операции. Если после снятия префикса разные маршруты спецификации совпали (/api/v1 и /api/v1/ без base_path), ни одну из этих операций выбрать нельзя. Без strip_prefix поведение прежнее.

base_path и strip_prefix должны начинаться с /. Пустой base_path без strip_prefix убирает префикс, который диктует документ; strip_prefix: / не принимается.

Слэш на конце маршрута

Маршрут сопоставляется строго: /path/ не совпадает с /path. ContractMock не перехватит запрос со слэшем, а validate_recorded_request отклонит его с «маршрут запроса не соответствует шаблону операции».

Если сервер обслуживает оба варианта, объявите это явно:

sources:
  ws2:
    path: api/ws2.yaml
    accept_trailing_slash: true          # для всех операций источника

operations:
  ws2.loadTree:
    source: ws2
    accept_trailing_slash: true          # или для одной операции; значение операции важнее

С настройкой операция принимает ровно один необязательный завершающий слэш: /path и /path/ для шаблона /path, /path и /path/ для шаблона /path/. //, /pat/ и остальные маршруты по-прежнему не подходят. ContractMock перехватывает обе формы, validate_recorded_request принимает обе, path-параметры разбираются одинаково, а в mock.requests виден фактический путь. operation.path, path в manifest и проверка «маршрут изменился» остаются в форме спецификации.

Чем считать настройку, зависит от причины:

  • сервер принимает оба варианта, спецификация описывает один — это свойство сервера. Настройка источника (или операции) со значением true и есть его фиксация, срок ей не нужен;

  • спецификация потеряла слэш, который объявлен в самом бэкенде — это дефект спецификации. Заведите задачу на исправление и включите настройку временно, только у затронутых операций:

    operations:
      ws2.loadTree:
        source: ws2
        accept_trailing_slash:
          issue: SAMSARA-24848               # задача на исправление спецификации
          reason: спека потеряла слэш из @Path("/search/tree/")
          expires_at: 2026-12-31
    

    Срок подчиняется тем же политикам, что и waiver: expires_at не дальше policies.waiver_max_days дней от сегодня, за policies.waiver_warn_days дней check и update начинают предупреждать, а после expires_at генерация падает. Продление срока меняет только manifest: артефакты от него не зависят. Временная форма допустима только у операции. Waiver здесь не подходит: он описывает расхождение схем и не имеет отношения к форме маршрута.

Настройка не должна склеивать операции. Если с ней один путь подходит под маршруты двух операций с одним методом, а без неё не подходил, мок одной перехватывал бы запросы другой. Так бывает с маршрутами, которые различаются только слэшем на конце (GET /items и GET /items/, в том числе с разными именами path-параметров), и с шаблоном против литерала (GET /items/{id} с настройкой принял бы /items/new/ у GET /items/new/). Генерация такое отклоняет и называет операции, у которых нужно задать accept_trailing_slash: false. Источники проверяются вместе: все моки регистрируются на одном JJ-сервере. Пересечения, которые есть и без настройки (/items/{id} и /items/new), остаются делом спецификации.

Решение и альтернативы — ADR 0006.

Режимы выбора: explicit и all

explicit (по умолчанию) генерирует только операции из operations. На каждом прогоне каждая запись сверяется со спецификацией: operationId, метод, маршрут, content type запроса и закреплённые варианты ответа. Любое расхождение — ошибка привязки, и генерация падает. Подходит для большой спецификации, из которой нужна малая часть.

Если в manifest уже есть операции, каждый explicit-источник должен использоваться хотя бы одной из них. Иначе это ошибка manifest: скорее всего, опечатка в имени источника.

all генерирует все операции источника под ключами <источник>.<operationId>. Каждой операции нужен уникальный operationId. Запись в operations необязательна: она нужна, только чтобы задать python_path, сузить варианты ответа, объявить non_waivable или отключить d42. Подходит для небольшой спецификации, которую ведёт та же команда.

Использование в тестах

Операции

from app_contracts.generated import operations

op = operations.api.create_document

op.key  # 'api.createDocument'
op.method  # 'POST'
op.path  # '/api/v1/workspaces/{workspaceId}/documents'
op.request.path  # path-параметры: (ParameterView(name='workspaceId', ...),)
op.request.query  # query-параметры; есть также header и cookie
op.request.body()  # RequestBodyView: content_type, required, json_schema, d42_export
op.responses  # все варианты ответа
op.response(status=201)  # один вариант; если вариант один, аргументы можно опустить
op.unchecked  # тела, которые спецификация объявила, а контракт не проверяет, с причинами
op.unsupported  # то же строками, плюс причины, по которым не сгенерированы d42-схемы

response() и request.body() выбирают вариант сами, если он единственный. Если вариантов несколько, передайте status/content_type, иначе будет ResponseVariantError.

operations — статический модуль: IDE и mypy видят все операции. Для инструментов есть строковый доступ: operations.by_key("api.createDocument") и operations.keys().

Моки

Нужен extra [jj].

async with operations.api.create_document.mock(
    response=response_body,
    status=201,
    path_params={"workspaceId": workspace_id},
    wait_for_requests=1,
) as mock:
    await page.submit()

assert len(mock.history) == 1
request = mock.requests[0]
Аргумент Значение
response тело ответа; проверяется по контракту до регистрации мока
status HTTP-статус; он же выбирает вариант ответа
content_type выбирает вариант ответа, если по статусу их несколько
path_params значения сегментов маршрута; переводятся в строку и проверяются по схемам параметров
query_params сузить matcher по query-параметрам; значение переводится в строку и проверяется по контракту (см. ниже). У массива повторами ключа строка закрепляет один повтор, массив одной строкой можно передать списком
headers сузить matcher по заголовкам запроса; описанные контрактом проверяются так же, как query_params
response_headers заголовки ответа; Content-Type подставляется из контракта, если не задан
wait_for_requests сколько запросов дождаться перед выходом из блока
timeout сколько ждать запросы, секунд; по умолчанию 5.0
history_callback функция, которая получит историю после снятия мока, например для вложения в Allure

До входа в блок мок проверяет версию JJ (>=2.9,<3), path_params и query_params, выбор варианта ответа, тело ответа (по JSON Schema, а при установленном [d42] — ещё и по d42-схеме), статус (100..599) и Content-Type из response_headers. Неверный мок не доходит до приложения:

ResponseContractError: тело ответа 201:application/json: 'id' is a required property
  ожидалось: ['id', 'title', 'visibility']
  фактически: {'nope': 1} [operation=api.createDocument, direction=response, pointer=/, schema_pointer=/required]

При выходе из блока мок дожидается wait_for_requests запросов, снимается (всегда, даже если тест упал), сохраняет историю в mock.history и mock.requests и проверяет каждый перехваченный запрос: метод, маршрут, параметры с их сериализацией и обязательностью, тело и его Content-Type.

RequestContractError: тело запроса application/json: 'title' is a required property
  ожидалось: ['title']
  фактически: {} [operation=api.createDocument, direction=request, pointer=/, schema_pointer=/required]

Если тело блока бросило исключение, оно остаётся главным. Ошибки мока прикладываются к нему заметками (add_note, Python 3.11+) и доступны в mock.diagnostics.

wait_for_requests не проверяет количество вызовов. Он только ждёт, пока приложение отправит запросы, и падает, если их пришло меньше N:

ContractMockError: ожидалось минимум 1 запрос(ов), перехвачено 0 [operation=api.createDocument]

Три запроса вместо одного он пропустит. Точное количество проверяйте сами: assert len(mock.history) == 1.

Значения path_params, query_params и headers переводятся в строку по одному правилу: True → "true", None → "" (так null записывается в запросе; допустимо только у nullable-строки), UUID и date — через str(). Получившаяся строка проверяется по контракту так же, как перехваченный запрос. Заголовки, которых нет в контракте (Authorization), закрепляются как есть.

Параметр, которого нет в спецификации, в query_params закрепить нельзя, и waiver'а, добавляющего параметр, тоже нет: расхождение спецификации с API чинится в спецификации. До исправления проверяйте такой параметр по истории мока: mock.requests[0].params.getall("name").

Ограничения:

  • мок создаётся только из generated-операции; готовый jj.Mocked передать нельзя;
  • в один мок нельзя войти дважды, для повторного использования создайте новый;
  • значение path_params не может содержать /;
  • для варианта ответа default передайте конкретный числовой status.

Текстовые тела и тела без контракта

Тело text/plain (и другие конкретные text/*) со схемой type: string проверяется и мокается как строка: minLength, maxLength, pattern и enum работают.

async with operations.ws2.text_preview.mock(response="<b>bold</b>", status=200) as mock:
    await page.preview_message()

response — строка; она уходит как есть, без кавычек JSON, с Content-Type: text/plain (JJ дописывает charset=utf-8; другой charset задайте в response_headers). Тело запроса декодируется по charset из Content-Type запроса, по умолчанию UTF-8. Схема не строки (объект, массив, nullable) под закреплённым в manifest text/* — ошибка генерации с причиной; незакреплённый такой вариант (обычно его порождает генератор: общий produces Swagger 2.0, Swashbuckle, springdoc для text/csv) не проверяется и назван в geas update с причиной. text/json — это JSON; text/xml, text/yaml и text/event-stream не проверяются.

multipart/*, application/octet-stream, XML и прочие media type без контракта объявлены спецификацией, но не проверяются. Они доступны как op.unchecked, названы в geas list/geas update, а попытка выбрать такой вариант падает с причиной, а не с «тела нет». Запрос с объявленным непроверяемым Content-Type не считается ошибкой; Content-Type запроса сопоставляется с объявленными по media range (image/* покрывает image/png, */* — любой тип). Подробности — docs/support-matrix.md.

Проверка без мока

op.validate_response(body, status=201)  # ResponseContractError, если тело не подходит
op.validate_request_body(payload)  # RequestContractError, если тело не подходит

Без extras проверка идёт по JSON Schema. При установленном [d42] добавляется проверка по d42-схеме.

d42-схемы и фикстуры

Нужен extra [d42].

from geas import Direction
from geas.integrations.d42 import build_fixture

DocumentSchema = operations.api.create_document.d42_schema(Direction.RESPONSE)
body = build_fixture(DocumentSchema)

Если в направлении несколько d42-схем (например, у ответов 200 и 400 разные тела), без export будет ошибка со списком схем. Передайте имя нужной:

ErrorSchema = op.d42_schema(Direction.RESPONSE, export=op.response(status=400).d42_export)

build_fixture детерминирован: одна и та же схема с тем же seed (аргумент необязателен) всегда даёт одно и то же значение. Необязательные поля в фикстуру не попадают, поэтому добавление необязательного поля в спецификацию фикстуру не меняет.

Для некоторых направлений d42-схемы не создаются. Это бывает с конструкциями, которые d42 не умеет выражать: multipleOf, pattern вместе с границами длины, allOf с недоказуемым или пустым пересечением. Запрос и ответ независимы: если невыразим ответ, d42-схемы запроса остаются. Причину печатает geas update, и её же называет ошибка d42_schema(). Моки и validate_* для таких операций работают по JSON Schema.

d42-схемы параметров запроса

Нужен extra [d42]. У каждого места запроса с параметрами (path, query, header, cookie) есть своя d42-схема: словарь «имя параметра → значение в том виде, в каком оно уходит в запрос».

from geas import Direction

QueryParamsSchema = operations.main.get_folder_role_idm_link.d42_schema(
    Direction.REQUEST, part="query"
)
GeneratedMainGetFolderRoleIdmLinkQueryParamsSchema = schema.dict({
    "action": schema.any(schema.str("ADMIN"), schema.str("READ"), ...),
    "folderId": serialized(schema.int.min(-9223372036854775808).max(9223372036854775807)),
    ...: ...,
})
  • Строковый query-параметр — обычная schema.str с enum, pattern и границами.
  • integer, number и boolean — serialized(<типизированная схема>): строка, которая разбирается тем же правилом, что и перехваченный запрос ("42", "true"), а границы и enum берутся из контракта. fake() не выходит за границы: для int64 он не выдаст ни 30-значное число, ни отрицательное там, где minimum: 1.
  • Строку в path, header и cookie ограничивает сам транспорт, поэтому она обёрнута в serialized(schema.str..., location="path"): сегмент path не бывает пустым и не содержит / (записанный путь уже раскодирован, %2F в нём — разделитель), у заголовка и cookie нет пробелов по краям, в cookie нет ;. Разобранный запрос таких значений не содержит, а fake() не выдаёт то, что транспорт изменил бы по дороге.
  • Необязательный параметр — optional(...). Словари query, header и cookie открыты (...: ...): контракт не запрещает лишние параметры. Словарь path закрыт.
  • Массив повторами ключа (query, explode: true, по умолчанию) — список строк: {"status": ["draft", "review"]}. Массив одной строкой (explode: false, spaceDelimited, pipeDelimited, массивы в path и header) — serialized(schema.list(...), delimiter=",").

% принимает и значение, и его строковый вид:

Подстановка Что закрепляет "42" "042"
Schema % {"folderId": 42} значение подходит подходит
Schema % {"folderId": "42"} точную строку подходит не подходит
expected = QueryParamsSchema % {"folderId": folder_id, "action": "MANAGE_INTEGRATIONS"}
assert dict(mock.requests[0].params) == expected

Для массива повторами ключа соберите значения списком (request.params.getall(name)): dict() оставит только первое. Ключи схемы заголовков — имена из контракта, а имена заголовков в HTTP регистронезависимы и могут прийти в другом регистре (HTTP/2, клиенты на Node.js пишут их строчными). Перед сравнением приведите имена перехваченного запроса к именам контракта.

fake() даёт значения, которые проходят проверку запроса по контракту. Исключение — format (date-time, uuid): как и в схемах тел, d42 его не проверяет и не генерирует. Overlay'и работают сквозь serialized: overlay_generators(QueryParamsSchema, {("folderId",): ValidIDSchema}).

Место, у которого нет однозначного строкового вида, d42-схему не получает, остальные места той же операции — получают. Это сериализация, пропущенная waiver'ом (deepObject, label, matrix), и заголовки, различающиеся только регистром. Причину печатает geas update, и её же называет d42_schema(part=...):

  main.searchDocuments (параметры query): d42-схема не сгенерирована — параметр 'filter': сериализацию style=deepObject, explode=true для scalar разрешил waiver, но строкового вида значения у неё нет — библиотека такие значения не разбирает [contract path /param/query/filter]

Устройство и альтернативы — ADR 0005.

Полиморфные DTO (allOf)

Схема, у которой одновременно properties, oneOf и discriminator (так springdoc описывает наследование), в контракте — allOf базы и объединения. d42 получает то же пересечение, распределённое по вариантам:

GeneratedEdgePredicateV2DtoSchema = schema.any(
    GeneratedConstantSchema,
    GeneratedOperationSchema,
    GeneratedOrSchema,
    GeneratedAndSchema,
)

Ветка, равная своему варианту, остаётся ссылкой на него; если база добавляет свойство, которого у варианта нет, ветка печатается словарём со свойствами обоих. Ветку, которая по контракту не допускает ни одного значения (enum варианта вне enum базы), geas update называет отдельной строкой — это ошибка спецификации. Правила пересечения — в docs/support-matrix.md.

Рекурсивные контракты

Схема, которая ссылается сама на себя (дерево папок, правило из правил), d42 не отключает. Цикл отсекается там, где он замыкается при обходе от тела запроса или ответа. Всё до этого места — обычная generated-схема, а ссылка, которая возвращает в уже пройденное определение, становится отсечённым узлом:

GeneratedFolderTreeSchema = schema.dict({
    "children": schema.list(_RECURSION.ref("FolderTree")),
    "folder": GeneratedFolderSchema,
    ...: ...,
})

Где отсечён цикл, печатает geas update:

  main.createFolderTree (response): цикл отсечён на ссылке FolderTree -> FolderTree; этот узел d42 проверяет по JSON Schema

Отсечённый узел работает так:

  • проверка — по JSON Schema определения из контракта на любой глубине: типы, обязательность, enum, pattern, oneOf, discriminator. Ошибка называет точный путь. format не проверяется, как и везде в d42-схемах: его проверяют validate_* и моки;

  • % — частичная подстановка уходит внутрь рекурсивной части, закрепляется только переданное:

    TreeSchema = op.d42_schema(Direction.RESPONSE)
    TwoLevels = TreeSchema % {"folder": {"name": "Отчёты"}, "children": [{"folder": {"name": "Архив"}}]}
    
  • fake() и build_fixture — минимальный экземпляр определения: обязательные поля, массивы минимальной длины, в объединении — первый вариант, из которого есть выход из цикла. Если у определения нет конечного значения (цикл только через обязательные поля), падает RecursiveSchemaError; если минимальный экземпляр не проходит JSON Schema (неоднозначный oneOf), — ValidationFailedError. В обоих случаях задайте значение узла через %;

  • make_required() работает на верхнем словаре, как у любой схемы d42;

  • overlay'и подменяют генераторы только в типизированной части. Путь внутрь рекурсивной части — ContractOverlayError с подсказкой использовать %.

Место отсечки зависит от корня: одно и то же определение в разных операциях может быть типизировано на разную глубину. Внутри одного модуля оно всегда одно.

Overlay'и: осмысленные значения в фикстурах

Сгенерированная схема даёт для строкового поля случайную строку. Чтобы фикстура выглядела осмысленно, подмените генератор отдельного поля. Остальной контракт при этом не меняется:

from d42 import schema

from geas import Direction
from geas.integrations.d42 import EACH, build_fixture, overlay_generators

DocumentPageSchema = overlay_generators(
    operations.api.list_documents.d42_schema(Direction.RESPONSE),
    {
        ("items", EACH, "title"): schema.str("Отчёт за квартал"),
    },
)

build_fixture(DocumentPageSchema)
# {'items': [{'id': '5x PCZJr_…', 'title': 'Отчёт за квартал', 'visibility': 'private'}, …], 'total': …}
  • Путь — кортеж имён полей; EACH означает «каждый элемент массива». Вложенные массивы поддерживаются: ("a", EACH, "b", EACH, "c").
  • Подменить можно только лист. Структура, обязательность полей и nullable остаются сгенерированными.
  • Путь и тип проверяются при вызове overlay_generators, то есть при импорте модуля с overlay'ями. Если поле переименовали в спецификации, упадёт импорт, а не тест через неделю. Для enum подменённые значения должны входить в список допустимых.
  • Границы и pattern проверяются в build_fixture: значение сверяется с исходным контрактом.
  • Результат — обычная d42-схема, с ним работают fake(), % и make_required(). Применяйте % и make_required() до overlay_generators: они создают новую схему, и проверка по исходному контракту на ней пропадёт.

Ошибки, которые вы можете увидеть:

ContractOverlayError: overlay /nope: ключа 'nope' нет в сгенерированной схеме. Доступны: 'items', 'total'
ContractOverlayError: overlay /items: подменить можно только генератор листа, а здесь ListSchema — структура всегда остаётся сгенерированной
ContractOverlayError: overlay /items/-/title: тип ручной схемы не совпадает с контрактом. Ожидалось: StrSchema; получено: IntSchema
ContractOverlayError: значение, выданное ручным генератором overlay'я, нарушает сгенерированный контракт: - Value <class 'str'> at _['items'][0]['title'] must have at least 1 element, but it has 0 elements

Как посмотреть контракт

Чтобы увидеть, какие поля разрешает контракт, не открывая generated-файлы:

print(operations.api.create_document.describe_response(status=201))
print(operations.api.create_document.describe_request_body())
api.createDocument
Response 201 application/json

$ref #/$defs/Document; object; дополнительные свойства разрешены
├── id — required; string; minLength 1
├── title — required; string; minLength 1; maxLength 120
└── visibility — required; string; enum["private", "workspace", "public"]

JSON Schema:
  /…/app_contracts/generated/contracts/api__create_document.json#/responses/0/schema

d42:
  app_contracts.generated._d42.api__create_document_response:GeneratedDocumentSchema

d42 source:
  /…/app_contracts/generated/_d42/api__create_document_response.py

Параметры одного места — op.request.parameter_set("query").describe() или geas show api.listDocuments --part query. То же для тел из терминала: geas show api.createDocument --status 201, см. docs/cli.md. Координаты доступны и программно — у op.response(...) и op.request.body() есть contract_file, json_pointer, contract_path, d42_module, d42_export, d42_reference и d42_source_path. Если d42-схемы у варианта нет, d42-координаты равны None. Не разбирайте текст describe() в тестах: для программного доступа есть json_schema и geas show --json.

Generated-артефакты

geas update пишет в output.directory:

Файл Что это
__init__.py экспорт operations, Operations и REGISTRY
operations.py типизированный namespace операций
_registry.py индекс «ключ операции → файл контракта»
contracts/<slug>.json контракт операции: JSON Schema тел, параметров и заголовков, закреплённые варианты, статус d42
_d42/<slug>_request.py, _d42/<slug>_response.py d42-схемы; создаются, только если d42 включён и в направлении есть тело
_d42/<slug>_request_parameters.py d42-схемы параметров запроса, по одной на место; создаются, если d42 включён и у операции есть параметры
_generated.json индекс набора: версия формата и генератора, отпечатки, список файлов, которыми владеет geas

Артефакты детерминированы: повторный update без изменения входов даёт те же байты. update удаляет только файлы, которые сам создал раньше. Руками артефакты не правят: check уронит CI на любом расхождении.

CI

- name: Контракты соответствуют спецификации
  run: geas -m contracts/manifest.yaml check

check ничего не меняет и возвращает 1, если артефакты разошлись со спецификацией или генерация не проходит: waiver просрочен, привязка операции сломалась, в спецификации появилась неподдержанная конструкция. Если d42 включён хотя бы у одной операции, в CI нужен extra [d42]. Что делать при падении, описано в docs/cli.md.

geas diff показывает, что именно изменилось в контракте, и отделяет смысловые изменения от косметики.

Waivers и non_waivable

Если спецификация ошибается и исправить её сейчас нельзя, выпишите waiver: точечное послабление с владельцем, задачей и сроком. Генерация сама печатает готовую заготовку:

ошибка: format 'my-custom-tag' неизвестен для type='string'. ... (contract path /body/tag)
Если это осознанное исключение, добавьте в waivers.yaml:
  - operation: api.getDocumentTag
    direction: response
    json_pointer: /body/tag
    rule: allow_unknown_format
    expected_source: 77111c9dbf349c0c707b300581710f165b8d3a011a3764b9fd94e518f3a429a2
    reason: <зачем>
    owner: <кто отвечает>
    issue: <ссылка>
    expires_at: <YYYY-MM-DD>

Просроченный, ненужный или устаревший waiver ломает генерацию. non_waivable в manifest закрепляет поля, которые ослабить нельзя. Как выписывать waiver'ы, какие есть правила и что делать с ошибками — в docs/waivers.md.

Что поддерживается

Swagger 2.0 и OpenAPI 3.0.x: $ref (локальные и межфайловые внутри корня источника), allOf, oneOf, anyOf, discriminator, nullable/x-nullable, readOnly/writeOnly, enum, format, pattern, границы длины и чисел, additionalProperties, параметры в path/query/header/cookie, collectionFormat.

Отклоняются с диагностикой: OpenAPI 3.1, not, if/then/else, const, булевы схемы, type списком, deepObject/label/matrix, in: formData, диапазоны статусов 2XX, внешние HTTP-$ref и $ref за пределы корня источника.

Полная таблица — docs/support-matrix.md.

Ограничения

  • Мок подключается только через async with …mock(…). Декоратора и persistent-моков нет.
  • OpenAPI 3.1 не поддерживается.
  • Параметры — только скаляры и массивы скаляров.
  • Тело — JSON (application/json, …+json, text/json, */*) или текст (text/*, строка). Остальные media type (multipart/*, application/octet-stream, XML) объявлены, но не проверяются; операция генерируется.
  • geas не обращается к сети: внешние $ref запрещены, спецификация читается только с диска.

Документация

  • docs/cli.md — команды, флаги, коды возврата, типовые сценарии
  • docs/waivers.md — waiver'ы, non_waivable, политики
  • docs/migration.md — подключение к проекту с существующими моками
  • docs/support-matrix.md — матрица поддержки OpenAPI 3.0 / Swagger 2.0
  • examples/consumer — рабочий пример проекта-потребителя
  • CHANGELOG.md — история изменений

Разработка

make install     # venv + editable-установка с dev-зависимостями
make lint        # ruff check + ruff format --check
make typecheck   # mypy strict
make test        # pytest
make check       # всё сразу

Устройство пакета:

geas/                  ядро: manifest, нормализация, JSON Schema, артефакты, CLI
geas/dialects/         адаптеры Swagger 2.0 и OpenAPI 3.0
geas/integrations/d42/ d42-схемы, overlay'и, фикстуры (extra [d42])
geas/integrations/jj/  моки (extra [jj])

Ядро не импортирует d42 и jj: тесты проверяют это в подпроцессе, где оба модуля заблокированы. Тесты не ходят в сеть — фикстура no_outbound_network разрешает только loopback для локального сервера моков. Синтетические спецификации для тестов лежат в tests/fixtures/specs/.

Архитектурные решения и их обоснования — docs/adr/.

Выпуск версии

  1. Версия поднята в pyproject.toml, geas.__version__, README, docs/migration.md и uv.lock; секция CHANGELOG названа версией и датой; артефакты examples/consumer перегенерированы (geas update).
  2. На main создаётся GitHub Release с тегом vX.Y.Z.
  3. Публикация релиза запускает release.yml: он сверяет версию в pyproject.toml с тегом, собирает sdist и wheel, проверяет их twine check и публикует в PyPI через Trusted Publishing в окружении pypi.

Повторно опубликовать релиз (например, после того как тег перевешен на новый коммит) можно, переведя его в черновик и обратно: gh release edit vX.Y.Z --draft=true, затем --draft=false.

Metadata

Release files for geas 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for geas 0.8.0
File Size Uploaded Provenance Actions
geas-0.8.0.tar.gz 549.5 kB With provenance Details for geas-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for geas 0.8.0
File Interpreter ABI Platform Actions
geas-0.8.0-py3-none-any.whl Python 3 none any Details for geas-0.8.0-py3-none-any.whl

Total release size: 812.8 kB

Release files / geas-0.8.0.tar.gz

Download URL geas-0.8.0.tar.gz
Size 549.5 kB
Tags Source
SHA-256 checksum
How to use checksums
0d269bca19391010aec74a4ef67173399492e7b228941d7aa0d836db49035ce5
BLAKE2b-256 checksum
How to use checksums
10257a28c0cbf1b6d0c144e178471507e25e77593ad73f9570c40b0a01637cda
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / geas-0.8.0-py3-none-any.whl

Download URL geas-0.8.0-py3-none-any.whl
Size 263.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7689c35b80af5e0fc40571b1222ded466e42e35548893c6ace429e7f3e24107c
BLAKE2b-256 checksum
How to use checksums
0148f1d2dc8fb326bca4230fb441a25c7daa5e7338dbde3579325e767faecfc2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for geas 0.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for geas-0.8.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page