Pydantic 2.13.5 виправив GC у Rust-ядрі та вибір smart unions

Pydantic 2.13.5 виправляє дві помилки обходу garbage collector у Rust-ядрі pydantic-core, повторне використання validators за активних plugins і некоректний підрахунок перевірених полів у smart unions. Це невеликий patch-реліз без нового API, але його зміни важливі для довгоживучих Python-процесів та моделей, де кілька union-гілок можуть прийняти той самий вхід.

Що означає «missing GC traversal»

CPython збирає циклічні посилання не лише за reference counting. Для container-об’єктів розширення повинно повідомити garbage collector, які Python-об’єкти воно утримує. У двох структурах pydantic-core цей обхід був неповним: окремі поля Rust-об’єктів не потрапляли до traversal, зокрема виправлення окремо називає GeneralFieldsSerializer.

Це не означає, що кожна модель у Pydantic 2.13.4 гарантовано витікала. Проблема проявляється за конкретної форми графа посилань, особливо коли Python callback, serializer, schema або інший об’єкт через ланцюжок знову посилається на власника. Якщо GC не бачить повного циклу, звільнити його автоматично він не може.

Найпомітніші наслідки можливі не в короткому CLI-скрипті, а у FastAPI/Starlette workers, consumers черг, agent runtimes, notebook kernels і фонових сервісах, які живуть годинами. Навіть невеликий обсяг утриманої пам’яті на кожній перебудові schema з часом перетворюється на зростання RSS і частіші рестарти контейнера.

Smart unions мають рахувати поле один раз

Smart union mode порівнює успішні гілки й обирає найкращий match, враховуючи, наскільки точно тип відповідає входу та скільки полів моделі було перевірено. У 2.13.5 validated model fields більше не рахуються повторно. Це важливо, коли гілки схожі: помилково завищений score міг схилити вибір до іншої моделі, хоча обидві формально проходять validation.

Ризик найбільший у API payloads із union кількох моделей, що мають спільні optional fields, defaults або сумісні типи. Зміна може зробити результат правильнішим, але водночас відкрити залежність application code від попереднього випадкового вибору. Тому після patch-оновлення варто тестувати не лише факт успішної validation, а й конкретний клас отриманої моделі.

Validators і plugins

Ще одне виправлення дозволяє повторно використовувати validators, коли налаштовані plugins. Плагінна instrumentation може додавати hooks навколо validation; через це cache/reuse path не завжди поводився так, як без plugins. Реліз усуває цю розбіжність, але командам з observability або custom Pydantic plugins потрібно прогнати тести з реальною plugin-конфігурацією, а не лише у чистому середовищі.

Практичний висновок: якщо процес довго живе або активно створює schemas/serializers, оновлення варто поставити вище звичайного косметичного patch. Для union-моделей додайте assertion на фактичний тип результату.

Як перевірити оновлення

• Зафіксувати один production-like worker на 2.13.4 і 2.13.5 та порівняти RSS після однакової серії запитів.
• Кілька разів викликати gc.collect() у контрольному тесті й перевірити, чи зникають weak references на тимчасові serializers/schemas.
• Зібрати fixtures для всіх Union і discriminator-less unions, де гілки мають спільні поля.
• Перевірити результат model_validate(), serialization і JSON Schema, а не лише відсутність exception.
• Увімкнути ті самі Pydantic plugins та instrumentation, що працюють у production.

Оновлення без зайвого ризику

Оскільки це patch у межах 2.13, очікується сумісність API. Проте pydantic-core — окремий compiled package, тому lock-файл і container rebuild мають підтягнути узгоджену версію колеса для конкретної Python та CPU-платформи. Не копіюйте старий virtualenv між образами й не змішуйте wheels із різних architectures.

Після canary deployment слід дивитися не лише на 5xx, а й на validation error rate, distribution обраних union types, worker RSS, GC pauses та restart count. Якщо різниця з’являється лише на частині payloads, збережіть знеособлений мінімальний приклад і перевірте його окремим unit test.

Обмеження

Release notes не стверджують, що версія усуває всі можливі витоки пам’яті в Python-застосунку. RSS може рости через allocator, caches, native libraries або application references. Так само виправлення smart union не замінює discriminator: для публічних API явне поле типу часто дає стабільніший і зрозуміліший контракт, ніж евристичний вибір.

Джерело та права

Матеріал є самостійним українським перекладом-переказом release notes Pydantic 2.13.5, опублікованих 28 серпня 2026 року Viicos за участі tamird. Код, документація та release notes офіційного репозиторію поширюються за MIT License. Перекладено, адаптовано й доповнено редакцією «Бібліотеки програміста». Обкладинка створена редакцією за допомогою AI і не входить до першоджерела.