Documentation fix for set() with timeout

[snordhausen]

I noticed a small but significant omission in the API reference at http://sendapatch.se/projects/pylibmc/reference.html . For the set(key, value[, time=0....) operation it says:

If time is given, it specifies the number of seconds until key will expire.

However, in Python, the following happens:

>>> mc.set("y", "10", time=30 * 24 * 60 * 60)
True
>>> print mc.get("y")
10
>>> mc.set("y", "10", time=30 * 24 * 60 * 60 + 1)
True
>>> print mc.get("y")
None

That's because the protocol at http://code.google.com/p/memcached/wiki/NewCommands#Standard_Protocol specifies:

An expiration time, in seconds. Can be up to 30 days. After 30 days, is treated as a unix timestamp of an exact date.

Since the timeout is not converted in pylibmc, the semantics of the original protocol apply. That should definitely be part of the API documentation. Maybe it would be a good idea to throw an exception if anyone uses a value from 30 * 24 * 60 * 60 + 1 to, lets says, 1,000,000,000, because people most likely expect something that will not happen.

[lericson]

Hm, yes that is very confusing. I did know about this behavior, but libmemcached doesn't actually document this behavior either.

IMO this is pretty weird design, I agree that we should not let an int object specify a date. To fix this proper we should accept datetime objects and convert these to UNIX timestamps in the client. This would allow for both usecases to continue working.

The question arises then, what do we do with big ints? I say issue a warning.

Thoughts, implementation, documentation?

[lericson]

Ping @BrianAker as this is relevant to libmemcached as well.