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/.
Выпуск версии
- Версия поднята в
pyproject.toml,geas.__version__, README,docs/migration.mdиuv.lock; секция CHANGELOG названа версией и датой; артефактыexamples/consumerперегенерированы (geas update). - На
mainсоздаётся GitHub Release с тегомvX.Y.Z. - Публикация релиза запускает
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.