التابع `datetime.datetime.isoformat()‎` في بايثون

يعيد التابع سلسلة نصية تمثّل التاريخ بصيغة ISO 8601.

البنية العامة

isoformat(sep='T', timespec='auto')

المعاملات

`sep`

معامل اختياري يأخذ القيمة الافتراضية 'T' ويمثّل فاصلًا يتكوّن من حرف واحد يوضع بين جزئي الوقت والتاريخ في النتيجة المعادة.

`timespec`

يحدّد المعامل الاختياري timespec عدد المكوّنات الإضافية التي سيتضمّنها كائن الوقت (القيمة الافتراضية هي 'auto')، ويمكن للمكونات أن تكون واحدة ممّا يلي:

'auto': مشابه للمكون 'second' إن كانت أجزاء الثانية مساوية للصفر، وإلا فإنّه مشابه للمكوّن 'microseconds'.
'hours': تضمين الساعة بهيئة رقمين HH.
'minutes': تضمين الساعة والدقيقة بالصيغة HH:MM.
'seconds': تضمين الساعة والدقيقة والثانية بالصيغة HH:MM:SS.
'milliseconds': تضمين الوقت كاملًا، مع اقتطاع قيم الثانية الكسرية إلى أجزاء من الثانية، بالصيغة HH:MM:SS.sss.
'microseconds': عرض الوقت كاملًا بالصيغة HH:MM:SS.mmmmmm.

ملاحظة: تُقتطع مكوّنات الوقت المستثناة ولا تقرّب.

ملاحظة: أضيف المعامل timespec في الإصدار 3.6 من اللغة.

تطلق اللغة الخطأ ValueError في حال استخدام معامل timesepc غير صالح.

القيمة المعادة

يعيد التابع سلسلة نصية تمثّل التاريخ بصيغة ISO 8601 هي YYYY-MM-DDTHH:MM:SS.mmmmmm في حال تضمّن كائن datetime أجزاء الثانية، والصيغة YYYY-MM-DDTHH:MM:SS إن كانت قيمة أجزاء الثانية مساوية للصفر.

إن لم يعد التابع utcoffset()‎ القيمة None، فإنّ التابع يُلحق بالسلسلة النصية المعادة سلسلة نصية أخرى ذات ستة أحرف، تتضمّن مقدار الإزاحة عن التوقيت العالمي المنسّق بالساعات والدقائق (مع إضافة إشارة سالب أو موجب للإشارة إلى التقدم أو التأخر عن هذا التوقيت)، لتصبح النتيجة المعادة بالصيغة: YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM، أو إن كانت قيمة أجزاء الثانية صفرًا، فتكون النتيجة المعادة بالصيغة YYYY-MM-DDTHH:MM:SS+HH:MM.

أمثلة

يبين المثال التالي آلية عمل التابع:

‎>>> from datetime import datetime
>>> dt = datetime(2018, 6, 27, 20, 58)
>>> dt.isoformat()
'2018-06-27T20:58:00'
>>> dt = datetime(2290, 12, 8, 11, 23, 9, 4939)
>>> dt.isoformat()
'2290-12-08T11:23:09.004939'
>>> dt.isoformat(sep="#")
'2290-12-08#11:23:09.004939'
>>> dt.isoformat(timespec="minutes")
'2290-12-08T11:23'
>>> dt.isoformat(timespec="milliseconds")
'2290-12-08T11:23:09.004'
>>> dt.isoformat(timespec="hours")
'2290-12-08T11'

أما المثال التالي فيعرض النتيجة المعادة بعد استخدام التابعutcoffset()‎:

>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     def utcoffset(self, dt): return timedelta(minutes=-399)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'

انظر أيضًا

التابع datetime.isocalendar()‎: يعيد التابع صفًّا يضمّ ثلاثة عناصر هي (ISO year, ISO week number, ISO weekday).
التابع datetime.isoweekday()‎: يعيد التابع اليوم في الأسبوع على هيئة عدد صحيح، حيث يأخذ يوم الاثنين الرقم 0 ويوم الأحد الرقم 6.

مصادر

قسم datetime Objects في صفحة Basic date and time types في توثيق بايثون الرسمي.