Кодогенератор (Codegen) — документация amocrm-sdk 0.1.0

# Кодогенератор (Codegen)

## Обзор

Кастомные поля AmoCRM имеют числовые ID и произвольные названия, часто на русском языке. Кодогенератор автоматически создаёт типизированные подклассы DTO (`MyLead`, `MyContact`, `MyCompany`) с named-свойствами для каждого кастомного поля, что позволяет обращаться к ним как к обычным атрибутам Python вместо `get_cf_value(123)`.

Имена свойств автоматически транслитерируются из кириллицы в латиницу и приводятся к snake_case: `Источник трафика` → `istochnik_trafika`.

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

    from amocrm import OAuthConfig, DjangoTokenStorage
    from amocrm.codegen import generate_custom_fields_dto

    oauth = OAuthConfig(
        client_id="...",
        client_secret="...",
        redirect_uri="https://yourapp.com/oauth/callback",
        storage=DjangoTokenStorage(my_settings_obj),
    )
    generate_custom_fields_dto("mycompany", oauth, output_file="my_models.py")

Функция подключится к AmoCRM, загрузит определения кастомных полей и запишет готовый Python-код в файл `my_models.py`.

## Пример сгенерированного файла

Для каждого кастомного поля генерируются и геттер, и сеттер — можно читать и записывать значение через стандартный property-синтаксис:

    # Generated by amocrm-sdk codegen. DO NOT EDIT.
    # Regenerate: from amocrm.codegen import generate_custom_fields_dto

    from __future__ import annotations

    from amocrm import Lead, Contact, Company

    class MyLead(Lead):
        """Типизированные кастомные поля для сделок."""

        @property
        def istochnik_trafika(self) -> str | None:
            """Источник трафика (text, id=101)"""
            return self.get_cf_value(101)

        @istochnik_trafika.setter
        def istochnik_trafika(self, value: str | None) -> None:
            self.set_cf_value(101, value)

        @property
        def byudzhet(self) -> float | None:
            """Бюджет (numeric, id=102)"""
            return self.get_cf_value(102)

        @byudzhet.setter
        def byudzhet(self, value: float | None) -> None:
            self.set_cf_value(102, value)

    ...

## Подключение к клиенту через `configure_dto`

После генерации подключите классы к клиенту. Все методы `get`, `list`, `create`, `update` начнут возвращать экземпляры вашего подкласса:

    from amocrm.manager import get_client
    from my_models import MyLead, MyContact, MyCompany

    client = get_client(subdomain="mycompany", oauth=oauth)
    client.configure_dto(leads=MyLead, contacts=MyContact, companies=MyCompany)

    lead = client.leads.get(123)          # → MyLead
    print(lead.istochnik_trafika)         # → str | None  (геттер)
    lead.istochnik_trafika = "SEO"        # сеттер — записывает в custom_fields_values
    client.leads.update([lead])           # сохраняет изменения в AmoCRM

    for lead in client.leads.list():      # → Iterator[MyLead]
        print(lead.byudzhet)

Параметры `configure_dto` — все необязательны, можно подменить только часть ресурсов:

    client.configure_dto(leads=MyLead)    # contacts и companies остаются стандартными

Примечание

Вложенные объекты внутри `Lead` (`lead.contacts`, `lead.company`) остаются стандартными классами `Contact` / `Company`. Чтобы и они были вашими подклассами, переопределите `from_dict` в `MyLead`.

## Транслитерация имён

Названия кастомных полей на кириллице автоматически транслитерируются перед преобразованием в snake_case. Это позволяет использовать имена свойств как стандартные Python-атрибуты.

Примеры транслитерации:

Оригинал | Результат
--- | ---
`Источник` | `istochnik`
`Источник трафика` | `istochnik_trafika`
`пользовательское_соглашение` | `polzovatelskoe_soglashenie`
`предыдущая_сделка_1` | `predydushchaya_sdelka_1`

Таблица транслитерации (кириллица → латиница):

Символ | Транслит
--- | ---
а, б, в, г, д | a, b, v, g, d
е, ё, ж, з, и | e, yo, zh, z, i
й, к, л, м, н | j, k, l, m, n
о, п, р, с, т | o, p, r, s, t
у, ф, х, ц, ч | u, f, kh, ts, ch
ш, щ, ъ, ы, ь | sh, shch, (пусто), y, (пусто)
э, ю, я | e, yu, ya

## Запись значений через сеттеры

Каждое сгенерированное property имеет сеттер. Тип аргумента совпадает с типом геттера:

    lead = client.leads.get(123)

    # Обычные скалярные поля (text, numeric, integer, …)
    lead.email = "new@example.com"
    lead.byudzhet = 150000.0

    # Multiselect — передаётся список значений
    lead.uslugi = ["SEO", "Контекст"]

    # Сброс значения поля
    lead.email = None

    client.leads.update([lead])

Под капотом сеттер вызывает методы `CustomFieldsMixin`:

Тип поля AmoCRM | Сеттер в миксине
--- | ---
text, numeric, integer, select, phone, email, url, checkbox, bool, date, … | `set_cf_value(field_id, value)`
multiselect | `set_cf_values(field_id, values)`
smart_address | `set_cf_raw(field_id, values)`

## Конфигурация

`generate_custom_fields_dto` принимает следующие параметры:

Параметр | По умолчанию | Описание
--- | --- | ---
`subdomain` | — | Поддомен аккаунта AmoCRM (например, `"mycompany"`)
`oauth` | — | Объект `OAuthConfig` с реквизитами и хранилищем токенов
`entities` | `["leads", "contacts", "companies"]` | Список сущностей для генерации
`base_module` | `"amocrm"` | Модуль, из которого импортируются базовые классы
`output_file` | `None` | Путь к выходному файлу; если `None` — вывод в stdout

## Использование без записи в файл

Если `output_file` не передан, код выводится в stdout:

    generate_custom_fields_dto("mycompany", oauth)

Это удобно для просмотра результата перед сохранением или для использования вывода в пайплайне.

Генерация только для части сущностей:

    generate_custom_fields_dto(
        "mycompany", oauth,
        entities=["leads"],
        output_file="lead_models.py",
    )

## API-справочник

amocrm.codegen.generate_custom_fields_dto(subdomain, oauth, entities=None, base_module='amocrm', output_file=None)

  Подключиться к AmoCRM, получить кастомные поля и записать Python-код.

  Создаёт клиент, загружает определения кастомных полей и генерирует типизированные подклассы DTO для использования в проекте.

  Параметры:

    - subdomain (str) – Поддомен аккаунта AmoCRM (например, `"mycompany"`).

    - oauth (OAuthConfig) – Конфигурация OAuth с реквизитами и хранилищем токенов.

    - entities (list[str] | None) – Список сущностей для обработки. По умолчанию `["leads", "contacts", "companies"]`.

    - base_module (str) – Имя модуля для импорта базовых классов. По умолчанию `"amocrm"`.

    - output_file (str | None) – Путь к файлу для записи. Если `None` — вывод в stdout.

  Тип результата:

    None

  Example:

      from amocrm import OAuthConfig, DjangoTokenStorage
      from amocrm.codegen import generate_custom_fields_dto

      oauth = OAuthConfig(
          client_id="...",
          client_secret="...",
          redirect_uri="...",
          storage=DjangoTokenStorage(my_settings_obj),
      )
      generate_custom_fields_dto("mycompany", oauth, output_file="my_models.py")

amocrm.codegen.generate_and_print(client, entities=None, base_module='amocrm', output_file=None)

  Получить кастомные поля и вывести/записать сгенерированный Python-код.

  Параметры:

    - client (AmoCRM) – Инициализированный клиент `AmoCRM`.

    - entities (list[str] | None) – Список типов сущностей. По умолчанию `["leads", "contacts", "companies"]`.

    - base_module (str) – Имя модуля для импорта базовых классов.

    - output_file (str | None) – Путь к файлу для записи. Если `None` — вывод в stdout.

  Тип результата:

    None

amocrm.codegen.fetch_custom_fields(client, entities=None)

  Загрузить определения кастомных полей из AmoCRM для заданных сущностей.

  Параметры:

    - client (AmoCRM) – Инициализированный клиент `AmoCRM`.

    - entities (list[str] | None) – Список типов сущностей. По умолчанию `["leads", "contacts", "companies"]`.

  Результат:

    Словарь `{entity: [CustomFieldDefinition, ...]}`.

  Тип результата:

    dict[str, list[CustomFieldDefinition]]

amocrm.codegen.generate_custom_models(fields_by_entity, base_module='amocrm')

  Сгенерировать Python-код типизированных подклассов DTO.

  Параметры:

    - fields_by_entity (dict[str, list[CustomFieldDefinition]]) – Словарь `{entity: [CustomFieldDefinition, ...]}`, полученный из `fetch_custom_fields()`.

    - base_module (str) – Имя модуля, из которого импортируются базовые классы. По умолчанию `"amocrm"`.

  Результат:

    Строка с Python-кодом, готовая к записи в файл.

  Тип результата:

    str