Розуміння методу get_description() в Odoo 18.0
Розташування та контекст
Метод get_description() знаходиться в класі Field всередині модуля fields.py на рядку 862 фреймворку Odoo 18.0. Повний шлях: fields.py
Цей метод є основним компонентом системи дескрипторів полів Odoo, належить до базового класу Field, від якого наслідуються всі типи полів (Char, Integer, Boolean, Many2one, Binary, Json, Properties тощо). Клас Field визначений за допомогою метакласу MetaField, який автоматично збирає всі атрибути, що починаються з '_description_', в атрибут класу під назвою description_attrs.
Призначення та функціональність
Метод get_description() служить основним інтерфейсом для отримання метаданих про поле у форматі структурованого словника. Його основне призначення полягає в генерації комплексного опису атрибутів поля, що є важливим для:
1. Інтроспекції полів - Дозволяє Odoo розуміти властивості полів під час виконання
2. Документації API - Надання визначень полів зовнішнім клієнтам
3. Рендерингу UI - Інформування веб-клієнта про характеристики полів для правильної генерації форм
4. Валідації даних - Розуміння обмежень та вимог полів
5. Підтримки перекладів - Отримання локалізованих рядків та текстів підказок полів
6. Контролю доступу - Визначення видимості та прав доступу до полів
Сигнатура методу та параметри
Метод визначений наступним чином:
def get_description(self, env, attributes=None):
Повертає словник, що описує поле self.
Параметри:
- env: Об'єкт середовища Odoo, який надає контекст, включаючи користувача, курсор бази даних, налаштування мови та доступ до реєстру
- attributes (опціонально): Список, що визначає які атрибути включити в опис. Якщо None, повертаються всі доступні атрибути
Як це працює
Метод працює через розумний механізм інтроспекції:
1. Метаклас MetaField сканує клас Field на наявність всіх атрибутів, що починаються з '_description_', і зберігає їх в атрибуті класу description_attrs у вигляді кортежів (назва_атрибута, назва_властивості).
2. Коли викликається get_description(), він ітерується через ці кортежі description_attrs.
3. Для кожного атрибута:
- Якщо надано фільтр attributes і атрибута немає у фільтрі, він пропускається
- Відповідне значення властивості отримується за допомогою getattr()
- Якщо значення є викликуваним (callable) (як _description_depends або _description_sortable), воно викликається з параметром env для динамічного обчислення значення
- Якщо значення не є None, воно додається до результуючого словника
4. Метод повертає словник, що відображає назви атрибутів на їх значення.
Атрибути опису
Клас Field визначає численні властивості _description_*, які передаються в get_description():
Статичні властивості:
- _description_name: Назва поля
- _description_type: Тип поля (char, integer, many2one тощо)
- _description_store: Чи зберігається поле в базі даних
- _description_manual: Чи є поле користувацьким
- _description_related: Шлях пов'язаного поля, якщо застосовно
- _description_company_dependent: Значення, специфічні для компанії
- _description_readonly: Прапорець тільки для читання
- _description_required: Прапорець обов'язковості
- _description_groups: Групи доступу
- _description_change_default: Поведінка зміни за замовчуванням
- _description_default_export_compatible: Сумісність з експортом
- _description_exportable: Чи може поле бути експортоване
Динамічні властивості (обчислюються на основі середовища):
- _description_depends: Залежності поля
- _description_searchable: Чи можна шукати по полю
- _description_sortable: Чи можна сортувати по полю
- _description_groupable: Чи можна групувати по полю
- _description_aggregator: Функція агрегації, якщо застосовно
- _description_string: Перекладена мітка поля
- _description_help: Перекладений текст підказки
Приклади реального використання з кодової бази odoo 18.0
Приклад 1: Метод fields_get() на рівні моделі
Розташування: odoo/odoo/models.py:3744-3768
Найбільш помітне використання get_description() знаходиться в методі Model.fields_get(), який є публічним API для отримання визначень полів:
@api.model
def fields_get(self, allfields=None, attributes=None):res = {}
for fname, field in self._fields.items():
if allfields and fname not in allfields:continue
if not field.is_accessible(self.env):
continue
description = field.get_description(self.env, attributes=attributes)
res[fname] = description
return res
Цей метод викликається веб-клієнтом Odoo кожного разу, коли потрібно відрендерити представлення. Веб-клієнт надсилає RPC-виклик fields_get(), щоб зрозуміти які поля існують на моделі, їх типи, обмеження та властивості відображення. Метод get_description() надає всі ці метадані.
Приклад 2: Конвертація значень поля вибору
Розташування: odoo/odoo/addons/base/models/ir_fields.py:462-465
При імпорті даних або конвертації рядків у значення вибору, Odoo потрібно отримати доступ до опцій вибору:
def _str_to_selection(self, model, field, value):
# отримуємо неперекладені значення
env = self.with_context(lang=None).env
selection = field.get_description(env)['selection']
for item, label in selection:
# Співставлення рядкового значення з елементом вибору
Тут get_description() отримує конкретно атрибут 'selection', який містить список доступних опцій для поля вибору. Використовуючи контекст без мови, метод отримує неперекладені значення для точного співставлення.
Приклад 3: Отримання міток полів для валідаційних повідомлень
Розташування: odoo/addons/account/models/account_tax.py:71-75
При відображенні помилок валідації, Odoo використовує get_description() для отримання зрозумілих користувачеві міток полів:
def _check_accounts_configuration(self):
account_fields = self.env['account.account']._fields
reconcile_field_name = account_fields['reconcile'].get_description(self.env)['string']
non_trade_field_name = account_fields['non_trade'].get_description(self.env)['string']# Використання цих назв в повідомленнях про помилки валідації
Це гарантує, що валідаційні повідомлення відображають перекладену, зрозумілу користувачеві назву поля, а не технічну назву. Наприклад, замість відображення "reconcile must be enabled", може показуватися "Дозволити звірку має бути увімкнено" мовою користувача.
Приклад 4: Мітка поля в складній валідації
Розташування: odoo/addons/account/models/account_tax.py:87
raise ValidationError(
self.env._(
'%(tax_account)s має бути рахунком типу...',
tax_account=self._fields[field_name].get_description(self.env)['string'],
# ...
)
)
Метод get_description() витягує атрибут 'string' (мітку поля) для створення осмислених валідаційних повідомлень, які посилаються на поля за їх відображуваними назвами, а не технічними ідентифікаторами.
Приклад 5: Динамічна перевірка вибору
Розташування: odoo/addons/mail/models/mail_mail.py:130
message_type_field = self.env['mail.message']._fields['message_type']
if 'auto_comment' not in {value for value, name in message_type_field.get_description(self.env)['selection']}:
self._fields_get_message_type_update_selection(message_type_field.selection)Це перевіряє чи існує конкретне значення вибору в опціях поля, викликаючи get_description() для отримання списку вибору. Це корисно при розширенні полів вибору через різні модулі.
Типові випадки використання
1. Комунікація з веб-клієнтом
Коли веб-інтерфейс Odoo потрібно відрендерити форму, список або будь-яке представлення, він викликає fields_get(), який внутрішньо використовує get_description() для розуміння властивостей полів, таких як тип, обов'язковість, тільки для читання, рядкові мітки та підказки.
2. Операції імпорту/експорту
Під час імпорту/експорту даних, Odoo потрібно розуміти типи полів та обмеження. Метод get_description() надає ці метадані для забезпечення правильної конвертації та валідації даних.
3. Динамічна інтроспекція полів
Модулі, яким потрібно динамічно інспектувати структури моделей (як Studio, конструктори звітів або інструменти міграції даних), використовують get_description() для розуміння доступних полів та їх характеристик.
4. Валідація та повідомлення про помилки
При побудові повідомлень про помилки для користувачів, модулі викликають get_description() для отримання перекладених міток полів, що робить повідомлення більш читабельними.
5. Документація API
Зовнішні API-клієнти та генератори документації використовують fields_get() (який використовує get_description()) для розуміння доступних полів та їх властивостей.
6. Умовна логіка
Код, який потрібно приймати рішення на основі властивостей полів (Чи зберігається воно? Чи можна по ньому шукати? Чи є воно обов'язковим?), використовує get_description() для динамічного доступу до цих атрибутів.
Міркування щодо продуктивності
Метод get_description() розроблений для ефективності:
- Він використовує accessor властивостей замість пошуку в словниках
- Викликувані властивості обчислюються тільки при необхідності
- Параметр attributes дозволяє фільтрувати та повертати тільки необхідну інформацію, зменшуючи обчислення
- Результати зазвичай кешуються на рівні fields_get() для уникнення повторних викликів
Для дорогих обчислень, таких як _description_sortable і _description_groupable, метод включає скорочення: якщо поле має column_type і зберігається, він негайно повертає True без виконання складного аналізу запитів.
Ключові висновки
1. Метод залежить від середовища, що дозволяє йому повертати різні значення на основі мови користувача, контексту компанії та прав доступу.
2. Він відділяє статичні метадані (визначені при створенні поля) від динамічних метаданих (обчислених на основі середовища та стану бази даних).
3. Дизайн дозволяє підкласам полів перевизначати конкретні властивості _description_* для надання користувацької поведінки, успадковуючи базовий механізм.
4. Метод підтримує вибіркове отримання атрибутів через параметр attributes, що критично важливо для продуктивності, коли потрібна тільки конкретна інформація про поле.
Висновок
Метод get_description() є фундаментальним будівельним блоком системи полів Odoo, надаючи чистий, розширюваний інтерфейс для інтроспекції полів. Він з'єднує визначення полів в Python коді з метаданими часу виконання, необхідними для фреймворку, UI та зовнішніх систем. Розуміння цього методу є важливим для будь-кого, хто працює над кастомізаціями Odoo, особливо при роботі з динамічною обробкою полів, користувацькими типами полів або інтеграцією із зовнішніми системами.
