تایپ‌ها و کمک‌کننده‌ها

هر درخواست و پاسخی یکی دارد، یک 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'])

کلیدها همان نام‌های camelCase فیلدهای خودِ API هستند، مانند '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.

• —کلاینت: 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 هستند که هر کدام به نام چیزی که در خود دارد نام‌گذاری شده، با یک attribute برای هر مقدار: EMAIL_STATUSES.SENT برابر 'sent' است. برای گرفتن همهٔ مقدارها روی یک مجموعه پیمایش کنید، مقداری را که از بیرون آمده با in بررسی کنید، و با len() بشمارید. هر عضو با Final تایپ شده است، پس mypy و pyright مقدار EMAIL_STATUSES.SENT را همان literal '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 ثابت را export می‌کند: VERSION، LANGUAGES، PAGE_LIMITS، PAY_AS_YOU_GO_LIMITS_CENTS و 104 مجموعه، همان‌هایی که یک برنامه بیش از همه سراغشان می‌رود. بقیه، مانند EMAIL_STATUSES و TEMPLATE_STATUSES، را از openemail.constants import کنید، جایی که همهٔ مجموعه‌ها قرار دارند.

یک انتشار SDK هرگز نباید چیزی باشد که میان شما و اندپوینتی که از پیش کار می‌کند بایستد. client.raw.request() یک مسیر و آرگومان‌های کلیدواژه‌ای می‌گیرد و بدنهٔ تجزیه‌شده را برمی‌گرداند، با اعمال اعتبارنامه، URL پایه، تایم‌اوت و سیاست تلاش دوبارهٔ کلاینت.

result = client.raw.request(    '/something-new',    method='POST',    query={'dryRun': True},    body={'name': 'Invoices'},    repeatable=True,) print(result)

• —هیچ بدنهٔ درخواستی را اعتبارسنجی نمی‌کند. اسکیمای سرور تنها نسخهٔ قواعد است، و نسخهٔ دومی اینجا سرانجام آدرسی را رد می‌کرد که سروری تازه‌تر می‌پذیرد، آن هم در نسخه‌ای که کسی دو سال پیش pin کرده است.
• —به 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 خود را نگه می‌دارد.