टाइप और हेल्पर

हर अनुरोध और रिस्पॉन्स का एक type है: openemail.types में एक TypedDict, उसी नाम से जो उसके TypeScript जुड़वाँ का है। …Resource वह है जो API लौटाता है, और …Create, …Patch, …Input और …Send वे हैं जो आप पास करते हैं। फ़िल्टर और प्रति-कॉल विकल्प keyword आर्ग्युमेंट हैं, इसलिए उन्हें रखने वाले TypeScript types, जैसे 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'])

keys API के अपने camelCase फ़ील्ड नाम हैं, जैसे 'replyTo', 'scheduledAt' और 'nextCursor', आप जो भेजते हैं उसमें भी और जो वापस आता है उसमें भी। केवल मेथड के आर्ग्युमेंट snake_case में हैं (idempotency_key=, label_ids=), और जिस आर्ग्युमेंट का नाम from होता, वह from_= है, जैसे emails.list और calendar.list_events पर।

mypy और pyright दोनों इन्हें पढ़ते हैं, इसलिए ग़लत वर्तनी वाली key API तक पहुँचने के बजाय type जाँच में ही फेल हो जाती है। body के लिए mypy Extra key "replyto" for TypedDict "EmailSend" बताता है और रिस्पॉन्स के लिए TypedDict "SentEmailResource" has no key "satus", और pyright भी यही बात अपने शब्दों में कहता है। किसी सेट से बाहर का मान भी इसी तरह फेल होता है, जैसे emails.list पर status='sending-ish'।

• —क्लाइंट: 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।
• —Broadcasts: 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 जो कुछ भी और लौटाता है, बिलिंग से लेकर वर्कस्पेस तक, उन सबके types उन्हीं नामों से मौजूद हैं।

मानों के सेट openemail.constants में constants हैं, हर एक का नाम उसी पर रखा गया है जो उसमें है, और हर मान के लिए एक attribute है: EMAIL_STATUSES.SENT का मान 'sent' है। हर मान पाने के लिए किसी सेट पर iterate करें, बाहर से आए मान को in से जाँचें, और उन्हें len() से गिनें। हर सदस्य का type 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 constants export करता है: VERSION, LANGUAGES, PAGE_LIMITS, PAY_AS_YOU_GO_LIMITS_CENTS और 104 सेट, वे जिनकी किसी ऐप्लिकेशन को सबसे ज़्यादा ज़रूरत पड़ती है। बाकी, जैसे EMAIL_STATUSES और TEMPLATE_STATUSES, openemail.constants से import करें, जहाँ हर सेट रहता है।

किसी SDK रिलीज़ को कभी आपके और पहले से काम कर रहे endpoint के बीच नहीं खड़ा होना चाहिए। client.raw.request() एक path और keyword आर्ग्युमेंट लेता है और पार्स की गई body लौटाता है, जिसमें क्लाइंट का क्रेडेंशियल, base URL, timeout और retry नीति लागू होती है।

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

• —यह किसी request body को validate नहीं करता। नियमों की इकलौती प्रति सर्वर का schema है, और यहाँ रखी दूसरी प्रति किसी दिन ऐसा पता अस्वीकार कर देती जिसे नया सर्वर स्वीकार करता है, उस संस्करण में जिसे किसी ने दो साल पहले pin किया था।
• —यह httpx, anyio और typing-extensions पर निर्भर है, और किसी और चीज़ पर नहीं।
• —बाहर जाते समय यह सिर्फ़ उसे बदलता है जिसे JSON जैसा है वैसा नहीं ले जा सकता: attachment के content में bytes base64 बन जाते हैं, datetime UTC में एक ISO 8601 क्षण बन जाता है, date एक ISO तारीख़ और set एक list। to, cc या bcc में अकेला प्राप्तकर्ता एक list में लपेट दिया जाता है।
• —यह रिस्पॉन्स को केवल एक तरह से बदलता है: किसी संग्रह का data array उसके envelope से बाहर उठा लिया जाता है। पेज वाली सूची उसे hasMore और nextCursor के साथ items के रूप में लौटाती है, contacts.list_people उसे hasMore, nextCursor और seen के साथ items के रूप में, emails.send_batch उसे sent और failed के साथ items के रूप में, templates.list_sends उसे total, page और pageSize के साथ items के रूप में, temp_mail.list_messages उसे hasMore, nextCursor और expiresAt के साथ items के रूप में, और addresses.list उसे unrestricted, domains, hasMore तथा nextCursor के साथ addresses के रूप में। imports.list_failures अकेली सूची है जो वैसी ही छोड़ी जाती है जैसी API उसे भेजता है, {'object': ..., 'data': [...], 'nextCursor': ...}। बाकी हर जगह यह सादी list है। अंदर का हर resource प्रलेखित HTTP आकार बनाए रखता है।