Python/datetime/date
يمثل كائن التاريخ date تاريخًا (سنة وشهر ويوم) في التقويم المثالي، وهو التقويم الميلادي الممتدّ إلى ما لا نهاية في كلا الاتجاهين، ويمثّل اليوم ذو التاريخ 1 كانون الثاني (يناير) سنة 1 ميلادي اليوم ذا العدد 1 في هذا الكائن، واليوم ذو التاريخ 2 كانون الثاني (يناير) سنة 1 ميلادي اليوم ذا العدد 2 في هذا الكائن، وهكذا دواليك. يطابق هذا الترقيم تعريف "التقويم الكريكوري التنبؤي proleptic Gregorian" والذي وضعه كلّ من Dershowitz و Reingold في كتابهما Calendrical Calculations والذي يضع التقويم الأساسي المعتمد في جميع الحواسيب. ويمكن مراجعة هذا الكتاب للاطلاع على الخوارزميات التي يمكن استخدامها للتحويل التاريخ من التقويم الكريكوري التنبؤي إلى أنظمة التقويم الأخرى.
البنية العامة
datetime.date(year, month, day)
المعاملات
جميع المعاملات مطلوبة عند التصريح عن هذا الصنف.
year
عدد صحيح يمثّل السنة المطلوبة، ويجب أن يكون ضمن المدى MINYEAR <= year <= MAXYEAR.
month
عدد صحيح يمثّل الشهر المطلوب، ويجب أن يكون ضمن المدى 1 <= month <= 12.
day
عدد صحيح يمثّل اليوم المطلوب، ويجب أن يكون ضمن المدى 1 <= day <= MAXDAYS حيث MAXDAYS هو عدد الأيام في الشهر أو السنة المعطاة.
إن تجاوزت قيمة أحد هذه المعاملات المدى المحدد لها، تطلق اللغة الخطأ ValueError.
أمثلة
يبين المثال التالي الطريقة الصحيحة للتصريح عن الصنف date:
from datetime import date
>>> now = date.today()
>>> now.day
24
>>> now.year
2018
>>> now.month
3
توابع الصنف date
التابع date.today()
يعيد هذا التابع اليوم الحالي في الإعدادات المحلية.
التابع date.fromtimestamp()
يعيد هذا التابع التاريخ المحلي المرتبط بالختم الزمني ذي الصيغة POSIX كالذي يعيده التابع time.time().
التابع date.fromordinal()
يعيد هذا التابع التاريخ بحسب العدد الترتيبي المعطى والتابع للتقويم الكريكوري التنبؤي.
خصائص الصنف date
يقدّم الصنف date الخصائص التالية:
date.min
أقدم تاريخ يمكن تمثيله. date(MINYEAR, 1, 1).
date.max
أقصى تاريخ يمكن تمثيله date(MAXYEAR, 12, 31).
date.resolution
أدنى فارق ممكن بين كائني date غير متساويين timedelta(days=1).
خصائص نسخة الصنف date
تمتلك النسخ التي تنشأ من الصنف date الخصائص التالية:
date.year
السنة، وتمتد من MINYEAR إلى MAXYEAR ضمنيًّا.
date.month
الشهر، ويمتد من 1 إلى 12 ضمنيًّا.
date.day
اليوم، ويمتد من 1 إلى عدد الأيام ضمن الشهر المعطى في السنة المعطاة.
ملاحظة: هذه الخصائص للقراءة فقط.
توابع نسخة الصنف date
تقدّم النسخ التي تنشأ من الصنف date التوابع التالية:
التابع date.replace()
يستبدل التابع القيم المعطاة في المعاملات بالقيم الأصلية في كائن التاريخ.
التابع date.timetuple()
يعيد التابع الصنف time.struct_time. وهو عبارة عن كائن يتضمّن صفًّا مسمّىً named tuple. ويمكن الوصول إلى القيم عبر الفهرس index أو عبر اسم الخاصية.
التابع date.toordinal()
يعيد التابع العدد الترتيبي للتاريخ الذي يمثّله كائن التاريخ حسب التقويم التنبّؤي الكريكوري.
التابع date.weekday()
يعيد التابع اليوم في الأسبوع على هيئة عدد صحيح.
التابع date.isoweekday()
يعيد التابع اليوم في الأسبوع على هيئة عدد صحيح، بالاعتماد على تقويم ISO.
التابع date.isocalendar()
يعيد التابع صفًّا يضمّ ثلاثة عناصر هي (ISO year, ISO week number, ISO weekday).
التابع date.isoformat()
يعيد التابع سلسلة نصية تمثّل التاريخ بصيغة ISO 8601 هي 'YYYY-MM-DD'.
التابع date.__str__()
يتيح هذا التابع إعادة تمثيل للكائن date على هيئة سلسلة نصية قابلة للطباعة، باستخدام الدالة str().
التابع date.ctime()
يعيد التابع سلسلة نصية تمثل التاريخ، وتتضمّن الاسم المختصر لكل من اليوم والشهر يتبعهما اليوم ثم الساعة والدقيقة والثانية ثم السنة.
التابع date.strftime()
ينسّق التابع التاريخ باستخدام سلسلة التنسيق النصية المعطاة.
التابع date.__format__()
يسمح هذا التابع بتعيين سلسلسة تنسيق نصية لكائن التاريخ باستخدام محارف سلاسل التنسيق النصية وعند استخدام التابع str.format().
مصادر