← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/c-api/datetime.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/c-api/datetime.rst
 
1
.. highlightlang:: c
 
2
 
 
3
.. _datetimeobjects:
 
4
 
 
5
DateTime Objects
 
6
----------------
 
7
 
 
8
Various date and time objects are supplied by the :mod:`datetime` module.
 
9
Before using any of these functions, the header file :file:`datetime.h` must be
 
10
included in your source (note that this is not included by :file:`Python.h`),
 
11
and the macro :cfunc:`PyDateTime_IMPORT` must be invoked.  The macro puts a
 
12
pointer to a C structure into a static variable,  ``PyDateTimeAPI``, that is
 
13
used by the following macros.
 
14
 
 
15
Type-check macros:
 
16
 
 
17
.. cfunction:: int PyDate_Check(PyObject *ob)
 
18
 
 
19
   Return true if *ob* is of type :cdata:`PyDateTime_DateType` or a subtype of
 
20
   :cdata:`PyDateTime_DateType`.  *ob* must not be *NULL*.
 
21
 
 
22
 
 
23
.. cfunction:: int PyDate_CheckExact(PyObject *ob)
 
24
 
 
25
   Return true if *ob* is of type :cdata:`PyDateTime_DateType`. *ob* must not be
 
26
   *NULL*.
 
27
 
 
28
 
 
29
.. cfunction:: int PyDateTime_Check(PyObject *ob)
 
30
 
 
31
   Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType` or a subtype of
 
32
   :cdata:`PyDateTime_DateTimeType`.  *ob* must not be *NULL*.
 
33
 
 
34
 
 
35
.. cfunction:: int PyDateTime_CheckExact(PyObject *ob)
 
36
 
 
37
   Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType`. *ob* must not
 
38
   be *NULL*.
 
39
 
 
40
 
 
41
.. cfunction:: int PyTime_Check(PyObject *ob)
 
42
 
 
43
   Return true if *ob* is of type :cdata:`PyDateTime_TimeType` or a subtype of
 
44
   :cdata:`PyDateTime_TimeType`.  *ob* must not be *NULL*.
 
45
 
 
46
 
 
47
.. cfunction:: int PyTime_CheckExact(PyObject *ob)
 
48
 
 
49
   Return true if *ob* is of type :cdata:`PyDateTime_TimeType`. *ob* must not be
 
50
   *NULL*.
 
51
 
 
52
 
 
53
.. cfunction:: int PyDelta_Check(PyObject *ob)
 
54
 
 
55
   Return true if *ob* is of type :cdata:`PyDateTime_DeltaType` or a subtype of
 
56
   :cdata:`PyDateTime_DeltaType`.  *ob* must not be *NULL*.
 
57
 
 
58
 
 
59
.. cfunction:: int PyDelta_CheckExact(PyObject *ob)
 
60
 
 
61
   Return true if *ob* is of type :cdata:`PyDateTime_DeltaType`. *ob* must not be
 
62
   *NULL*.
 
63
 
 
64
 
 
65
.. cfunction:: int PyTZInfo_Check(PyObject *ob)
 
66
 
 
67
   Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType` or a subtype of
 
68
   :cdata:`PyDateTime_TZInfoType`.  *ob* must not be *NULL*.
 
69
 
 
70
 
 
71
.. cfunction:: int PyTZInfo_CheckExact(PyObject *ob)
 
72
 
 
73
   Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType`. *ob* must not be
 
74
   *NULL*.
 
75
 
 
76
 
 
77
Macros to create objects:
 
78
 
 
79
.. cfunction:: PyObject* PyDate_FromDate(int year, int month, int day)
 
80
 
 
81
   Return a ``datetime.date`` object with the specified year, month and day.
 
82
 
 
83
 
 
84
.. cfunction:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
 
85
 
 
86
   Return a ``datetime.datetime`` object with the specified year, month, day, hour,
 
87
   minute, second and microsecond.
 
88
 
 
89
 
 
90
.. cfunction:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
 
91
 
 
92
   Return a ``datetime.time`` object with the specified hour, minute, second and
 
93
   microsecond.
 
94
 
 
95
 
 
96
.. cfunction:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
 
97
 
 
98
   Return a ``datetime.timedelta`` object representing the given number of days,
 
99
   seconds and microseconds.  Normalization is performed so that the resulting
 
100
   number of microseconds and seconds lie in the ranges documented for
 
101
   ``datetime.timedelta`` objects.
 
102
 
 
103
 
 
104
Macros to extract fields from date objects.  The argument must be an instance of
 
105
:cdata:`PyDateTime_Date`, including subclasses (such as
 
106
:cdata:`PyDateTime_DateTime`).  The argument must not be *NULL*, and the type is
 
107
not checked:
 
108
 
 
109
.. cfunction:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
 
110
 
 
111
   Return the year, as a positive int.
 
112
 
 
113
 
 
114
.. cfunction:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
 
115
 
 
116
   Return the month, as an int from 1 through 12.
 
117
 
 
118
 
 
119
.. cfunction:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
 
120
 
 
121
   Return the day, as an int from 1 through 31.
 
122
 
 
123
 
 
124
Macros to extract fields from datetime objects.  The argument must be an
 
125
instance of :cdata:`PyDateTime_DateTime`, including subclasses. The argument
 
126
must not be *NULL*, and the type is not checked:
 
127
 
 
128
.. cfunction:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
 
129
 
 
130
   Return the hour, as an int from 0 through 23.
 
131
 
 
132
 
 
133
.. cfunction:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
 
134
 
 
135
   Return the minute, as an int from 0 through 59.
 
136
 
 
137
 
 
138
.. cfunction:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
 
139
 
 
140
   Return the second, as an int from 0 through 59.
 
141
 
 
142
 
 
143
.. cfunction:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
 
144
 
 
145
   Return the microsecond, as an int from 0 through 999999.
 
146
 
 
147
 
 
148
Macros to extract fields from time objects.  The argument must be an instance of
 
149
:cdata:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*,
 
150
and the type is not checked:
 
151
 
 
152
.. cfunction:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
 
153
 
 
154
   Return the hour, as an int from 0 through 23.
 
155
 
 
156
 
 
157
.. cfunction:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
 
158
 
 
159
   Return the minute, as an int from 0 through 59.
 
160
 
 
161
 
 
162
.. cfunction:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
 
163
 
 
164
   Return the second, as an int from 0 through 59.
 
165
 
 
166
 
 
167
.. cfunction:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
 
168
 
 
169
   Return the microsecond, as an int from 0 through 999999.
 
170
 
 
171
 
 
172
Macros for the convenience of modules implementing the DB API:
 
173
 
 
174
.. cfunction:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
 
175
 
 
176
   Create and return a new ``datetime.datetime`` object given an argument tuple
 
177
   suitable for passing to ``datetime.datetime.fromtimestamp()``.
 
178
 
 
179
 
 
180
.. cfunction:: PyObject* PyDate_FromTimestamp(PyObject *args)
 
181
 
 
182
   Create and return a new ``datetime.date`` object given an argument tuple
 
183
   suitable for passing to ``datetime.date.fromtimestamp()``.