الأنواع والمساعدات
ما تصدّره الحزمة أيضًا.
الصادرات في وقت التشغيل
| الصادر | ما هي |
|---|---|
| init, openemail | هيّئ العميل المشترك مرة واحدة، ثم استورد openemail في أي مكان. ويبني نفسه من OPENEMAIL_API_KEY إن لم يُنفَّذ init قط. |
| 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 | أين يقف البث، وأي نسخه تُعرض، ولماذا كُتم العنوان، ولماذا رُفضت إعادة تشغيل webhook. |
| 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 كأي قراءة أخرى. أما أي أسلوب HTTP آخر فيُرسل مرة واحدة ما لم تمرّر repeatable=True، وهو إقرارك بأنه يجوز إرساله مرتين. ويتخطى query القيم التي هي None أو فارغة، ويعمل api_key= وtimeout= كما يعملان في كل دالة أخرى. وفي AsyncOpenEmail يُستدعى مع await.
يجب أن يبدأ المسار بـ/ واحدة. وأي شيء آخر، وكذلك المسار الذي سيغادر عنوانه النهائي أصلَ 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، بالوسائط نفسها ومع ضبط كل خيار، ويفشل حين تغيب دالة، أو تقبل خيارات مختلفة، أو ترسل طلبًا مختلفًا، أو تعيد قيمة مختلفة.