Типы и вспомогательные функции
Что ещё экспортирует пакет.
Экспорты времени выполнения
| Экспорт | Что это |
|---|---|
| init, openemail | Настройте общий клиент один раз, а дальше импортируйте openemail где угодно. Если init не вызывался, клиент соберёт себя из OPENEMAIL_API_KEY. |
| get_client, reset_client | Сам общий клиент и способ его сбросить, чтобы следующий вызов собрал новый. Именно это нужно тесту между случаями. |
| OpenEmail, create_client | Отдельный клиент. OpenEmail() берёт из окружения всё, что вы не указали, а create_client является другим именем для него. |
| AsyncOpenEmail | Тот же клиент, в котором каждый метод вызывается через await, на asyncio или trio. |
| create_temp_mail, create_async_temp_mail | Клиент одноразового ящика, который не несёт API-ключа, и его асинхронный аналог. |
| OpenEmailError, OpenEmailApiError, OpenEmailNetworkError и WebhookVerificationError | Ошибки, которые выбрасывает пакет, все наследуют OpenEmailError. OpenEmailApiError несёт разобранный ответ с ошибкой в body, а также fields, когда подписка через форму была отклонена. |
| verify_webhook_signature | Сравнение за постоянное время, с окном защиты от повторов. Возвращает разобранную полезную нагрузку и выбрасывает WebhookVerificationError при любом сбое. |
| to_base64 | Base64 для байтов вложений из bytes, bytearray или memoryview. |
| is_api_key | Имеет ли строка форму oe_live_ или oe_test_. Это проверка формы, а не доказательство того, что ключ ещё работает. |
| is_access_token | Имеет ли строка вид токена доступа OAuth: от 1 до 512 символов и не начинается с oe_. |
| is_sealed, MESSAGE_ENCRYPTION_FORMATS | Является ли тело письма шифротекстом, и пять конвертов, которые может назвать приём почты. is_sealed равно false для двух ПОДПИСАННЫХ форматов, тела которых пришли в открытом виде. Именно поэтому функция и поставляется, а не оставлена на выведение вызывающим из объединения типов. |
| LANGUAGES, resolve_language, language_by_code и is_rtl_language | Встроенная таблица языков и функции поиска, нужные для выбора языка. |
| API_SCOPES | Словарь областей для экрана создания ключа. |
| WEBHOOK_EVENTS, WEBHOOK_SIGNATURE_HEADERS | События, на которые может подписаться эндпоинт, и имена заголовков, которые несёт доставка. |
| RULE_FIELDS, RULE_OPERATORS и RULE_ACTIONS | Словарь, из которого строятся условия и действия правила. |
| PAGE_LIMITS | Максимальный и используемый по умолчанию limit для большинства постраничных списков: 100 и 25. contacts.list, audiences.list_contacts и списки tracking принимают до 200 при значении по умолчанию 50, а temp_mail.list_messages принимает до 50. |
| ERROR_TYPES | Замороженный словарь ошибок. |
| VERSION, __version__ | Версия пакета. |
| THREAD_SORTS, PEOPLE_SORTS, CONTACT_THREAD_SORTS и FILE_SORTS | Порядки, в которых можно сортировать списки цепочек, людей, цепочек контакта и файлов. |
| FILE_KINDS, FILE_DIRECTIONS, CONTACT_BLOCK_LISTS и CONTACT_PHOTO_TYPES | Фильтры списка файлов, два списка блокировки рабочего пространства и типы изображений, которыми может быть фото контакта. |
| BROADCAST_STATUSES, BROADCAST_RECIPIENT_FILTERS, SUPPRESSION_REASONS и WEBHOOK_REPLAY_ERROR_CODES | На каком этапе рассылка, какие её копии выводить, почему адрес подавлен и почему повторная отправка вебхука была отклонена. |
| PROVIDER_IMPORT_RESOURCES, PROVIDER_IMPORT_STATUSES и PROVIDER_IMPORT_DOMAIN_STATES | Что может перенести импорт от провайдера, на каком этапе запуск и на каком этапе каждый найденный им домен. |
| FILE_USAGES | Почему файл сохраняется, а не может быть удалён: received, sent, linked или scheduled. |
| CREDENTIAL_KINDS, STEP_UP_METHODS и STEP_UP_ERROR_CODES | Какие учётные данные описывают me.get() и me.ping() (apiKey или oauth), как проверяется код подтверждения (email или totp) и коды, с которыми подтверждение может не пройти. |
| FORM_STATUSES, FORM_SUBMISSION_STATUSES, FORM_FIELD_TYPES, FORM_STARTER_SLUGS и FORM_* | Значения, которые принимают форма, её поля и её подписки, в шестнадцати наборах: статусы, типы полей, заготовки, шрифты, ширины и причины, по которым ответ отклоняется. |
| BILLING_*, BRAND_*, DNS_*, DOMAIN_* и другие наборы | Значения всех остальных пространств имён, каждый набор назван по тому, что он содержит. |
Типы
У каждого запроса и ответа есть свой TypedDict в openemail.types с тем же именем, что и у его аналога на TypeScript. …Resource описывает то, что возвращает API, а …Create, …Patch, …Input и …Send описывают то, что передаёте вы. Фильтры и параметры конкретного вызова передаются именованными аргументами, поэтому у типов TypeScript, которые их несут, например EmailListOptions, здесь нет аналога.
from openemail.types import EmailSend, Page, SentEmailResource, ThreadSummaryResource message: EmailSend = { 'from': 'Acme Billing <[email protected]>', 'to': '[email protected]', 'replyTo': '[email protected]', 'subject': 'Your September invoice', 'text': 'Your invoice is attached.',} sent: SentEmailResource = client.emails.send(message)inbox: Page[ThreadSummaryResource] = client.threads.list(folder='inbox') print(sent['status'], sent['scheduledAt'], inbox['nextCursor'])Ключи совпадают с собственными именами полей API в camelCase, например 'replyTo', 'scheduledAt' и 'nextCursor', и в том, что вы отправляете, и в том, что приходит обратно. В snake_case записаны только аргументы методов (idempotency_key=, label_ids=), а аргумент, который назывался бы from, называется from_=, как в emails.list и calendar.list_events.
mypy и pyright оба их читают, поэтому ключ с опечаткой проваливает проверку типов, а не доходит до API. mypy сообщает Extra key "replyto" for TypedDict "EmailSend" для тела и TypedDict "SentEmailResource" has no key "satus" для ответа, а pyright говорит то же самое своими словами. Значение вне набора проваливается так же, например status='sending-ish' в emails.list.
Они существуют для вашего средства проверки типов. Во время выполнения каждый TypedDict является обычным dict, поэтому импорт ничего не стоит и во время работы программы ничего не проверяется.
- Клиент:
Page,ApiKeyMode,RawBody.openemail.types.clientдобавляетAccessTokenProvider,AsyncAccessTokenProvider,HeaderValueиQueryValue. - Ошибки:
ErrorType,FormFieldProblem. - Письма:
EmailSend,EmailTranslate,EmailResource,SentEmailResource,EmailRecipientResource,EmailEventResource,EmailStatus,EmailSource,EmailTransport,EmailTrackingSummary,EmailTranslationResource,TranslationResource,RecipientStatus,BatchItemResource,BatchResultResource. - Шаблоны:
TemplateCreate,TemplatePatch,TemplateContent,TemplatePreviewInput,TemplateSend,TemplateResource,TemplateDetailResource,TemplateVersionResource,TemplatePreviewResource,TemplateSendsResource,SentTemplateEmailResource,DeletedTemplateResource,TemplateEngine,TemplateProp,TemplateSlot,TemplateStatus,TemplateValueKind. - Отслеживание:
TrackingResource,TrackingSummary,TrackingRecipientResource,TrackingLinkResource,TrackingOpenResource,TrackingClickResource,TrackingStatsResource,TrackingGrain. - Переписки и черновики:
ThreadPatch,ThreadResource,ThreadSummaryResource,UpdatedThreadResource,TrashedThreadResource,SnoozedThreadResource,DraftInput,DraftResource,DraftSummaryResource,SavedDraftResource,DeletedDraftResource. - Метки, контакты, домены и адреса:
LabelInput,LabelColor,LabelResource,DeletedLabelResource,ContactCreate,ContactPatch,ContactSource,ContactResource,ContactDetailResource,ContactAudienceResource,ContactAudiencesSet,DeletedContactResource,PeoplePage,PersonResource,DomainPatch,DomainResource,DomainDetailResource,DomainSendingState,DomainTracking,DomainTrackingState,AddressBookPage,AddressBookResource,AddressResource,SendableDomainResource. - Аудитории:
AudienceCreate,AudiencePatch,AudienceMemberSort,AudienceContactAdd,AudienceContactsBatch,AudienceImport,AudienceImportRow,AudienceResource,AudienceBuiltin,AudienceContactResource,AudienceMemberResource,RemovedAudienceContactResource,DeletedAudienceResource,EmptiedAudienceResource,AudienceBatchAddResource,AudienceBatchRemoveResource,AudienceImportResource,AudienceGrowthResource,AudienceGrowthTotals,AudienceGrowthSeries,AudienceGrowthBucket. - Рассылки:
BroadcastCreate,BroadcastPreviewInput,BroadcastResource,BroadcastCounts,BroadcastStatus,BroadcastPreviewResource,BroadcastRecipientResource,BroadcastRecipientContentResource,BroadcastRecipientFilter,BroadcastStatsResource,BroadcastStatsTotals,BroadcastStatsBucket. - Правила:
RuleCreate,RulePatch,RuleTestInput,RuleResource,RuleRunResource,RuleTestResource,DeletedRuleResource,RuleCondition,RuleConditionInput,RuleAction,RuleActionType,RuleField,RuleOperator. - Вебхуки:
WebhookCreate,WebhookPatch,WebhookResource,CreatedWebhookResource,DeletedWebhookResource,WebhookDeliveryResource,WebhookDeliveryDetailResource,WebhookDeliveryAttempt,WebhookReplayResource,WebhookReplayRefusal,WebhookReplayErrorCode,WebhookTestResource,WebhookEvent,WebhookPayload,EmailOpenedData,EmailClickedData,EmailDownloadedData,FileEventData. - Календарь и настройки:
CalendarOccurrenceResource,CalendarEventResource,CalendarAttendeeResource,SettingsPatch,SettingsResource. - Роли, участники и ключи:
RoleCreate,RolePatch,RoleResource,DeletedRoleResource,PermissionResource,MemberAdd,MemberPatch,MemberAddressGrant,MemberResource,MemberAddressResource,RemovedMemberResource,MemberAccess,KeyResource,PingResource. - Одноразовые ящики:
TempInboxCreate,TempInboxResource,CreatedTempInboxResource,DeletedTempInboxResource,TempDomainResource,TempMessageResource,TempMessagesResource,TempMessageDetailResource,DeletedTempMessageResource. - Общие:
RecipientInput,AttachmentInput,AttachmentResource,MessageResource,MessageEncryption,MessageEncryptionFormat,TrackingRequest,TranslateOptions,SendTranslateOptions,LanguageResource,ApiScope,Permission,BuiltinRole,HitKind. - Токены доступа и коды подтверждения:
CredentialKind,ApiKeySelfResource,OauthTokenSelfResource,ApiKeyPingResource,OauthTokenPingResource,StepUpBegin,StepUpVerify,StepUpMethod,StepUpErrorCode,StepUpStatusResource,StepUpChallengeResource,StepUpVerifiedResource. - Формы:
FormCreate,FormPatch,FormResource,FormDetailResource,FormDocument,FormField,FormCopy,FormStyle,FormSettings,FormSettingsInput,FormStats,FormAudience,FormStarterResource,FormStarterDetailResource,FormAnalyticsResource,FormSubmissionResource,FormAnswer,ResentFormConfirmationResource,FormSubscribeValues,FormSubscriptionResource,FormSubmittedEventData,FormConfirmedEventData. - У всего остального, что возвращает API, от биллинга до рабочих пространств, есть типы под теми же именами.
Наборы строк
Наборы значений являются константами в openemail.constants, каждая названа по тому, что содержит, с атрибутом для каждого значения: EMAIL_STATUSES.SENT равен 'sent'. Итерируйте набор, чтобы получить все значения, проверяйте пришедшее извне значение через in и считайте их через len(). Каждый член типизирован как Final, поэтому mypy и pyright читают EMAIL_STATUSES.SENT как литерал 'sent' и принимают его везде, где ожидается EmailStatus.
from openemail import PAGE_LIMITS, WEBHOOK_EVENTSfrom openemail.constants import EMAIL_STATUSES failed = client.emails.list(status=EMAIL_STATUSES.FAILED, limit=PAGE_LIMITS.MAX_LIMIT) print(EMAIL_STATUSES.SENT, list(EMAIL_STATUSES), len(WEBHOOK_EVENTS))print('email.opened' in WEBHOOK_EVENTS, len(failed['items']))Сам openemail экспортирует 108 констант: VERSION, LANGUAGES, PAGE_LIMITS, PAY_AS_YOU_GO_LIMITS_CENTS и 104 набора, те, что нужны приложению чаще всего. Остальные, например EMAIL_STATUSES и TEMPLATE_STATUSES, импортируйте из openemail.constants, где лежат все наборы.
Эндпоинт, который пока не обёрнут
Релиз SDK никогда не должен стоять между вами и эндпоинтом, который уже работает. client.raw.request() принимает путь и именованные аргументы и возвращает разобранное тело, применяя учётные данные клиента, базовый URL, таймаут и политику повторов.
result = client.raw.request( '/something-new', method='POST', query={'dryRun': True}, body={'name': 'Invoices'}, repeatable=True,) print(result)GET повторяется так же, как любое другое чтение. Любой другой метод отправляется один раз, если вы не передали repeatable=True, то есть не заявили, что его можно отправить дважды. query пропускает значения, равные None или пустые, а api_key= и timeout= работают так же, как и во всех остальных методах. В AsyncOpenEmail вызов выполняется через await.
Путь должен начинаться с одного /. Любой другой путь, как и путь, итоговый URL которого вышел бы за пределы origin API, выбрасывает ValueError до отправки запроса, так что учётные данные никогда не попадут на другой хост.
Чего он намеренно не делает
- Он не проверяет тело запроса. Схема на сервере является единственной копией правил, а вторая копия здесь рано или поздно отвергла бы адрес, который более новый сервер принимает, в версии, зафиксированной кем-то два года назад.
- Он зависит от
httpx,anyioиtyping-extensionsи больше ни от чего. - На выходе он преобразует только то, что JSON не может передать как есть:
bytesвcontentвложения становятся base64,datetimeстановится моментом ISO 8601 в UTC,dateстановится датой ISO, аsetсписком. Одиночный получатель вto,ccилиbccоборачивается в список. - Он меняет форму ответа ровно одним способом: массив
dataколлекции вынимается из конверта. Постраничный список отдаёт его какitemsрядом сhasMoreиnextCursor,contacts.list_peopleкакitemsрядом сhasMore,nextCursorиseen,emails.send_batchкакitemsрядом сsentиfailed,templates.list_sendsкакitemsрядом сtotal,pageиpageSize,temp_mail.list_messagesкакitemsрядом сhasMore,nextCursorиexpiresAt, аaddresses.listкакaddressesрядом сunrestricted,domains,hasMoreиnextCursor.imports.list_failuresостаётся единственным списком в том виде, в каком его присылает API:{'object': ..., 'data': [...], 'nextCursor': ...}. Во всех остальных случаях это обычный список. Каждый ресурс внутри сохраняет задокументированную форму HTTP.
Проверка соответствия в пакете следит, чтобы это оставалось правдой. Она запускает каждый метод рядом с его аналогом на TypeScript, с теми же аргументами и со всеми заданными опциями, и падает, когда метода нет, он принимает другие опции, отправляет другой запрос или возвращает другое значение.