[Patches] [ python-Patches-876130 ] add C API to datetime module

Thu Mar 25 13:23:06 EST 2004

Patches item #876130, was opened at 2004-01-13 16:20
Message generated for change (Comment added) made by lemburg
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=305470&aid=876130&group_id=5470

Category: Modules
Group: Python 2.3
Status: Open
Resolution: None
Priority: 5
Submitted By: Anthony Tuininga (atuining)
Assigned to: M.-A. Lemburg (lemburg)
Summary: add C API to datetime module

Initial Comment:
The datetime module does not have a C API which means
that modules written in C cannot take advantage of the
datetime module without incurring significant overhead.
These patches supply this lack and are based on the C
API exported by the mxDateTime module and the cStringIO
module and enhanced as suggested by Guido.

----------------------------------------------------------------------

>Comment By: M.-A. Lemburg (lemburg)
Date: 2004-03-25 19:23

Message:
Logged In: YES 
user_id=38388

Thanks for the comments...

1)  Please put *all* the code for the C API into
datetimeapi.h. I don't like
your current mix of putting some things into datetime.h and
others into
datetimeapi.h (e.g. the PyDateTime_CAPI definition).

2) Since it's the only API missing if you want to use
datetime objects
in database interfacing, please add it.

3) dito.

4) Yes, the header file is the right place. Have a look at
unicodeobject.h
for what I have in mind (or mxDateTime.h for that matter).

5) Why add yet another magic number ? Isn't the Python API
number
enough ?

6) Since you don't provide a doc patch, please put comments into
the header file. There can never be enough documentation and 
developers tend to look at the code rather than the docs ;-)

----------------------------------------------------------------------

Comment By: Anthony Tuininga (atuining)
Date: 2004-03-25 19:08

Message:
Logged In: YES 
user_id=619560

Sorry for the delay. Things here have been quite busy
recently both at work and at home. Let me see if I can
answer your questions.

1) are you suggesting comments that include the macro names
in datetimeapi.h similar to what I put in the comments
below? Or something else? See modified datetimeapi.h for
more info.

2) TimeFromTicks() is a very DB API specific routine. In
chatting with others about the datetime module, they were
not keen on adding such a beast. I guess there will have to
be some discussion about whether datetimeapi.h is also a
sort of half implementation for a C module implementing the
DB API. I was intending to do this in my cx_Oracle module
but not in datetimeapi.h. Could you clarify?

3) I could add C APIS for the three DB API ticks interfaces
but I was simply intending to do that in cx_Oracle. Again,
see #2. I can do it either way. :-)

4) I have added limited documentation in datetimeapi.h but
is that really the right place for it? Is it even remotely
close to what is needed? I'm not sure what is needed here
exactly.

5) the API magic number is simply an arbitrary number which
is stored in datetime.h and need not be understood by the
implementor. For your information I simply took the name
"datetime", converted each letter to its ordinal value in
the alphabet, modded by 16 and used that hex character --
does that make any sense? This can be changed to whatever
makes sense, though.

6) Whether or not datetimeapi.h should be sufficient for a
developer or whether he should look at documentation in the
usual locations (html pages, for example) I'll leave up to
the Python development team. Let me know how I can assist.

----------------------------------------------------------------------

Comment By: M.-A. Lemburg (lemburg)
Date: 2004-03-25 18:35

Message:
Logged In: YES 
user_id=38388

Anthony, have you had a chance to look at the comments ?

----------------------------------------------------------------------

Comment By: Anthony Tuininga (atuining)
Date: 2004-02-26 16:06

Message:
Logged In: YES 
user_id=619560

Oops! It looks like my own misunderstanding of SourceForge
and how it works is to blame. :-( I'll take a look at this
and get back to you as soon as possible -- ignore my
previous comment.

----------------------------------------------------------------------

Comment By: Anthony Tuininga (atuining)
Date: 2004-02-26 16:03

Message:
Logged In: YES 
user_id=619560

You haven't yet responded to my previous comments -- it
looks like SourceForge put them __after__ your comments so
it is quite understandable why you didn't notice them. If
you can give me the answers to those questions or provide
additional questions that I need to answer, then I think we
can make progress again. I was waiting for __you__ :-)

----------------------------------------------------------------------

Comment By: M.-A. Lemburg (lemburg)
Date: 2004-02-26 00:08

Message:
Logged In: YES 
user_id=38388

Any progress on this ?

----------------------------------------------------------------------

Comment By: M.-A. Lemburg (lemburg)
Date: 2004-01-28 12:49

Message:
Logged In: YES 
user_id=38388

Thanks for the clarification. I had forgotten about the
macros -- I'd suggest that you document them in the
datetimeapi.h include file to not cause the same confusion
on the developer side (the trick to achieve adoption is to
make things easy on the developer).

As for TimeFromTicks(): 
This should be rather straight forward to implement: you
take the time part of the ticks timestamp and create a time
object from it. This is the way the DB API constructor works.

Could you add C APIs for the three DB API ticks interface
methods ?

Other things that are missing:
* documentation of the way the CAPI object can be used in
datetimeapi.h
* documentation of the various CAPI entries
* documentation of the API magic number (there should be
some scheme for this)

I think that datetimeapi.h should be enough for a developer
to read in order to use the interface.

----------------------------------------------------------------------

Comment By: Anthony Tuininga (atuining)
Date: 2004-01-26 22:02

Message:
Logged In: YES 
user_id=619560

I didn't think any additional API would be necessary for
extracting date time information since the following macros
are available:

PyDateTime_GET_YEAR(o)
PyDateTime_GET_MONTH(o)
PyDateTime_GET_DAY(o)
PyDateTime_DATE_GET_HOUR(o)
PyDateTime_DATE_GET_MINUTE(o)
PyDateTime_DATE_GET_SECOND(o)
PyDateTime_DATE_GET_MICROSECOND(o)
PyDateTime_TIME_GET_HOUR(o)
PyDateTime_TIME_GET_MINUTE(o)
PyDateTime_TIME_GET_SECOND(o)
PyDateTime_TIME_GET_MICROSECOND(o)

Were you thinking of something else that is needed?

As for interfacing at the C level for converting from Unix
ticks, the following method is already available and could
simply be used as a drop in replacement for DateFromTicks()
and TimestampFromTicks() from the DB API document.

DateFromTicks() --> datetime.date.fromtimestamp()
TimestampFromTicks() --> datetime.datetime.fromtimestamp()

TimeFromTicks() is not already exposed but discussions with
Tim Peters already suggested that would not happen since the
concept is rather strange. You'll have to discuss that with
him if you disagree! :-)

Any comments?

----------------------------------------------------------------------

Comment By: M.-A. Lemburg (lemburg)
Date: 2004-01-26 21:46

Message:
Logged In: YES 
user_id=38388

This is a good start. However, you should add more APIs for
extracting date/time information to the C API. mxDateTime.h
from egenix-mx-base can provide a good basis for this. 

If you want to make the datetime module usable for database
interfacing at C level, you'll also have to add interfaces for
Unix ticks conversion, since these are often used by database
C level interfaces.

----------------------------------------------------------------------

Comment By: Anthony Tuininga (atuining)
Date: 2004-01-26 19:36

Message:
Logged In: YES 
user_id=619560

I have no objection to providing patches for doc and test. A
quick look at _testcapimodule.c doesn't provide any obvious
ideas as to how to patch it. I looked for cStringIO which
has a C API already and found nothing in there at all. The
documentation also simply says "see the source for the
information you require". Any suggestions as to how to proceed?

----------------------------------------------------------------------

Comment By: Tim Peters (tim_one)
Date: 2004-01-26 04:17

Message:
Logged In: YES 
user_id=31435

Marc-Andre, can you review this?  I think you have more 
experience building C APIs for modules than anyone else 
(while I don't have any).

There's certainly no objection to giving datetime a C API, and 
Guido already said he doesn't want to rely on that Martin 
changed datetime to be built as part of the core (in 2.3 on 
Windows, datetime.pyd was a distinct DLL; in CVS, datetime 
is compiled into the core DLL now).

Anthony, you probably need to add doc and test patches.  
_testcapimodule.c holds tests of things you can only get at 
from C.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=305470&aid=876130&group_id=5470