5 ms·

Pendulum is a new library for Python to ease datetimes, timedeltas and timezones manipulation. It is heavily inspired by [Carbon](http://carbon.nesbot.com http

Pendulum is a new library for Python to ease datetimes, timedeltas and timezones manipulation. It is heavily inspired by [Carbon](http://carbon.nesbot.com http://carbon.nesbot.com) for PHP. Basically, the Pendulum class is a replacement for the native datetime one with some useful and intuitive methods, the Interval class is intended to be a better time delta class and, finally, the Period class is a datetime-aware timedelta. Timezones are also easier to deal with: Pendulum will automatically normalize your datetime to handle DST transitions for you. import pendulum pendulum.create(2013, 3, 31, 2, 30, 0, 0, 'Europe/Paris’) # 2:30 for the 31th of March 2013 does not exist # so pendulum will return the actual time which is 3:30+02:00 '2013-03-31T03:30:00+02:00’ dt = pendulum.create(2013, 3, 31, 1, 59, 59, 999999, 'Europe/Paris’) '2013-03-31T01:59:59.999999+01:00’ dt = dt.add(microseconds=1) '2013-03-31T03:00:00+02:00’ dt.subtract(microseconds=1) '2013-03-31T01:59:59.999998+01:00’ To those wondering: yes I know [Arrow](http://crsmithdev.com/arrow/ http://crsmithdev.com/arrow/) exists but its flaws and strange API (you can throw almost anything at get() and it will do its best to determine what you wanted, for instance) motivated me to start this project. You can check why I think Arrow is flawed here: https://pendulum.eustace.io/faq/#why-not-arrow https://pendulum.eustace.io/faq/#why-not-arrow Link to the official documentation: https://pendulum.eustace.io/docs/ https://pendulum.eustace.io/docs/ Link to the github project: https://github.com/sdispater/pendulum https://github.com/sdispater/pendulum

dvl 10y ago
I already faced some of mentioned problems using Arrow, I'll give pendulum a try tomorrow.
antar 10y ago
Why not submit fixes for the existing library instead?
- detaro 10y ago
  Can't talk about the specific complaints the author has, but there are a bunch of datetime libraries for python with often intentionally different behaviors. Submitting "fixes" requires the other libraries' authors to see what you want to fix as a defect and not a design decision/feature/to irrelevant to justify breaking changes. At least that was my impression from trying to find a combination of libraries I like and reading various bug trackers in the process. In the end I pick and choose the pieces that do what I like for each part of the process, luckily the datatypes are mostly compatible or easily adapted.
  - oneweekwonder 10y ago
    What mysql lib would you recommend? I'm doing a `pip install https://dev.mysql.com/get/Downloads/Connector-Python/mysql-connector-python-2.1.3.tar.gz` https://dev.mysql.com/get/Downloads/Connector-Python/mysql-c... on older centos boxes. Because I found `pip install mysql-connector-python` seems to fail on older boxes. I also wonder if I should not start to look at SQLAlchemy. Not so much the ORM. But rather the simple DBAPI[0] interface. I'm already using Postgres FDW to integrate PostGIS into our mysql dbs. So I am going to drag a Postgres python lib around in the near future, any recommendations. PS: I Believe I just convinced myself, to go invest some time into learning SQLAlchemy. http://aosabook.org/en/sqlalchemy.html http://aosabook.org/en/sqlalchemy.html
- sdispater 10y ago
  Simply because I do not really like the API of the existing libraries (Arrow or Delorean) and I just can't fix the design decisions made by the authors.
was_boring 10y ago
Good, because arrow is effectively dead at this point
tedmiston 10y ago
I can't decide if auto-normalizing my times to DST is a feature or anti-feature. If I didn't know it was there, I would consider it a surprising default.
- sdispater 10y ago
  I see what you mean but as soon as you deal with timezone-aware datetimes you don't really have a choice, if an hour has been skipped, it simply doesn't exist. What is important here, I think, is that any time arithmetic is not affected by this normalization, so if you add an hour the difference will be an hour, so you don't really have to think about it.
  - Walkman 10y ago
    > I see what you mean but as soon as you deal with timezone-aware datetimes you don't really have a choice, if an hour has been skipped, it simply doesn't exist. So somebody clearly made a mistake (either the user or the programmer not checking the input) which you can't automagically fix. Well, at least, it's a terrible idea. I understand the intent of helping them, but you make more harm this way. It's also against the ZEN of Python.
    - lukasgraf 10y ago
      I tend to agree. Obviously automatic normalisation is the correct thing to do when doing arithmetic that crosses DST-rollover boundaries (this is what the Python stdlib gets wrong), but I don't think it should be done (by default) upon creation with a location-based TZ specification: pendulum.create(2016, 10, 30, 2, 30, 00, 0, 'Europe/Paris') is ambiguous, and pendulum.create(2016, 3, 27, 2, 30, 00, 0, 'Europe/Paris') is non-existent. pytz raises AmbiguousTimeError or NonExistentTimeError respectively in cases where you try to construct local times like that and specifiy is_dst=None: http://pytz.sourceforge.net/#problems-with-localtime http://pytz.sourceforge.net/#problems-with-localtime With pendulum I don't see a possibility to enforce a "strict mode" that turns of those automatic assumptions.
      - 10y ago
jsmeaton 10y ago
Cool library, I'll definitely be looking into this more closely in the future. The automatic handling of ambiguous time during timezone transitions is curious. As an example, Django punts on automatic handling and requires a user to choose between pre and post transition (I wrote the is_dst handling): https://github.com/django/django/blob/19e20a2a3f763388bba9263d56db34012e90cf5b/django/utils/timezone.py#L368 https://github.com/django/django/blob/19e20a2a3f763388bba926... What if you were to begin with a time at 3:30 and then subtract an hour. Would your library properly return 1:30? What if a user had a naive time at 3:30, subtracted an hour, and then converted to an aware time using your library? For what it's worth, I think moving to 3:30 is the correct behaviour in the vast amount of cases. Requiring a user to provide a direction to move and throwing an exception if they don't is dangerous. How often are users going to see this exception, if at all? Just wondering how much you've considered cases, if they exist, that would be better off moving to 1:30. I'll add one more thing. As soon as I started browsing the page I thought "why would I use this over arrow?". Great to see you addressed that by default. I didn't know about some of arrows shortcomings/bugs, so they were really useful. Handling dates, times, and timezones in particular is a tricky problem, as evident by the large number of libraries in each language trying to get it right. If you haven't already, I'd really recommend reading the blog posts of Jon Skeet regarding Noda Time http://blog.nodatime.org/ http://blog.nodatime.org/ and https://codeblog.jonskeet.uk/category/nodatime/ https://codeblog.jonskeet.uk/category/nodatime/ even if it turns up some corner cases you haven't considered, or validates ones you have. Thanks!
- AdamN 10y ago
  PEP 495 - Local Time Disambiguation (folding) handles this in Python 3.6 quite elegantly: https://www.python.org/dev/peps/pep-0495/ https://www.python.org/dev/peps/pep-0495/ It adds an extra attribute 'fold' that can be '0' (the default) for normal times and '1' for the later version with that same local time representation in the case of the clock going backwards.

dvl 10y ago

I already faced some of mentioned problems using Arrow, I'll give pendulum a try tomorrow.

antar 10y ago

Why not submit fixes for the existing library instead?

detaro 10y ago
Can't talk about the specific complaints the author has, but there are a bunch of datetime libraries for python with often intentionally different behaviors. Submitting "fixes" requires the other libraries' authors to see what you want to fix as a defect and not a design decision/feature/to irrelevant to justify breaking changes. At least that was my impression from trying to find a combination of libraries I like and reading various bug trackers in the process. In the end I pick and choose the pieces that do what I like for each part of the process, luckily the datatypes are mostly compatible or easily adapted.
- oneweekwonder 10y ago
  What mysql lib would you recommend? I'm doing a `pip install https://dev.mysql.com/get/Downloads/Connector-Python/mysql-connector-python-2.1.3.tar.gz` https://dev.mysql.com/get/Downloads/Connector-Python/mysql-c... on older centos boxes. Because I found `pip install mysql-connector-python` seems to fail on older boxes. I also wonder if I should not start to look at SQLAlchemy. Not so much the ORM. But rather the simple DBAPI[0] interface. I'm already using Postgres FDW to integrate PostGIS into our mysql dbs. So I am going to drag a Postgres python lib around in the near future, any recommendations. PS: I Believe I just convinced myself, to go invest some time into learning SQLAlchemy. http://aosabook.org/en/sqlalchemy.html http://aosabook.org/en/sqlalchemy.html
sdispater 10y ago
Simply because I do not really like the API of the existing libraries (Arrow or Delorean) and I just can't fix the design decisions made by the authors.

was_boring 10y ago

Good, because arrow is effectively dead at this point

tedmiston 10y ago

I can't decide if auto-normalizing my times to DST is a feature or anti-feature. If I didn't know it was there, I would consider it a surprising default.

sdispater 10y ago
I see what you mean but as soon as you deal with timezone-aware datetimes you don't really have a choice, if an hour has been skipped, it simply doesn't exist. What is important here, I think, is that any time arithmetic is not affected by this normalization, so if you add an hour the difference will be an hour, so you don't really have to think about it.
- Walkman 10y ago
  > I see what you mean but as soon as you deal with timezone-aware datetimes you don't really have a choice, if an hour has been skipped, it simply doesn't exist. So somebody clearly made a mistake (either the user or the programmer not checking the input) which you can't automagically fix. Well, at least, it's a terrible idea. I understand the intent of helping them, but you make more harm this way. It's also against the ZEN of Python.
  - lukasgraf 10y ago
    I tend to agree. Obviously automatic normalisation is the correct thing to do when doing arithmetic that crosses DST-rollover boundaries (this is what the Python stdlib gets wrong), but I don't think it should be done (by default) upon creation with a location-based TZ specification: pendulum.create(2016, 10, 30, 2, 30, 00, 0, 'Europe/Paris') is ambiguous, and pendulum.create(2016, 3, 27, 2, 30, 00, 0, 'Europe/Paris') is non-existent. pytz raises AmbiguousTimeError or NonExistentTimeError respectively in cases where you try to construct local times like that and specifiy is_dst=None: http://pytz.sourceforge.net/#problems-with-localtime http://pytz.sourceforge.net/#problems-with-localtime With pendulum I don't see a possibility to enforce a "strict mode" that turns of those automatic assumptions.
    - 10y ago

jsmeaton 10y ago

Cool library, I'll definitely be looking into this more closely in the future. The automatic handling of ambiguous time during timezone transitions is curious. As an example, Django punts on automatic handling and requires a user to choose between pre and post transition (I wrote the is_dst handling): https://github.com/django/django/blob/19e20a2a3f763388bba9263d56db34012e90cf5b/django/utils/timezone.py#L368 https://github.com/django/django/blob/19e20a2a3f763388bba926... What if you were to begin with a time at 3:30 and then subtract an hour. Would your library properly return 1:30? What if a user had a naive time at 3:30, subtracted an hour, and then converted to an aware time using your library? For what it's worth, I think moving to 3:30 is the correct behaviour in the vast amount of cases. Requiring a user to provide a direction to move and throwing an exception if they don't is dangerous. How often are users going to see this exception, if at all? Just wondering how much you've considered cases, if they exist, that would be better off moving to 1:30. I'll add one more thing. As soon as I started browsing the page I thought "why would I use this over arrow?". Great to see you addressed that by default. I didn't know about some of arrows shortcomings/bugs, so they were really useful. Handling dates, times, and timezones in particular is a tricky problem, as evident by the large number of libraries in each language trying to get it right. If you haven't already, I'd really recommend reading the blog posts of Jon Skeet regarding Noda Time http://blog.nodatime.org/ http://blog.nodatime.org/ and https://codeblog.jonskeet.uk/category/nodatime/ https://codeblog.jonskeet.uk/category/nodatime/ even if it turns up some corner cases you haven't considered, or validates ones you have. Thanks!

AdamN 10y ago
PEP 495 - Local Time Disambiguation (folding) handles this in Python 3.6 quite elegantly: https://www.python.org/dev/peps/pep-0495/ https://www.python.org/dev/peps/pep-0495/ It adds an extra attribute 'fold' that can be '0' (the default) for normal times and '1' for the later version with that same local time representation in the case of the clock going backwards.