Pendulum ########

.. image:: https://img.shields.io/pypi/v/pendulum.svg :target: https://pypi.python.org/pypi/pendulum

.. image:: https://img.shields.io/pypi/l/pendulum.svg :target: https://pypi.python.org/pypi/pendulum

.. image:: https://github.com/sdispater/pendulum/actions/workflows/tests.yml/badge.svg :alt: Pendulum 构建状态 :target: https://github.com/sdispater/pendulum/actions

让 Python 日期时间变得简单。

支持 Python 3.8 及更新版本。

.. code-block:: python

import pendulum

now_in_paris = pendulum.now('Europe/Paris') now_in_paris '2016-07-04T00:49:58.502116+02:00'

无缝切换时区

now_in_paris.in_timezone('UTC') '2016-07-03T22:49:58.502116+00:00'

tomorrow = pendulum.now().add(days=1) last_week = pendulum.now().subtract(weeks=1)

past = pendulum.now().subtract(minutes=2) past.diff_for_humans() '2 minutes ago'

delta = past - last_week delta.hours 23 delta.in_words(locale='en') '6 days 23 hours 58 minutes'

正确处理日期时间标准化

pendulum.datetime(2013, 3, 31, 2, 30, tz='Europe/Paris') '2013-03-31T03:30:00+02:00' # 2:30 不存在（跳过的时间）

正确处理夏令时转换

just_before = pendulum.datetime(2013, 3, 31, 1, 59, 59, 999999, tz='Europe/Paris') '2013-03-31T01:59:59.999999+01:00' just_before.add(microseconds=1) '2013-03-31T03:00:00+02:00'

资源

官方网站 <https://pendulum.eustace.io>_
文档 <https://pendulum.eustace.io/docs/>_
问题追踪 <https://github.com/sdispater/pendulum/issues>_

为什么选择 Pendulum？

原生的 datetime 实例对于基本情况来说已经足够，但当面对更复杂的用例时，它们往往显示出局限性，而且使用起来不那么直观。Pendulum 提供了更清晰、更易于使用的 API，同时仍然依赖于标准库。所以它仍然是 datetime，只是更好。

与 Python 的其他日期时间库不同，Pendulum 是标准 datetime 类的直接替代品（它继承自 datetime），因此，基本上你可以在代码中用 DateTime 实例替换所有的 datetime 实例（对于使用 type 函数检查对象类型的库，如 sqlite3 或 PyMySQL 等，存在例外情况）。

它还消除了简单日期时间的概念：每个 Pendulum 实例都是时区感知的，默认为 UTC，便于使用。

Pendulum 还通过提供更直观的方法和属性改进了标准的 timedelta 类。

局限性

尽管 DateTime 类是 datetime 的子类，但在一些罕见的情况下，它无法直接替代原生类。以下是报告的案例列表（非详尽），以及可能的解决方案（如果有）：

sqlite3 默认会使用 type() 函数来确定对象的类型。要解决这个问题，你可以注册一个新的适配器：

.. code-block:: python

from pendulum import DateTime
from sqlite3 import register_adapter

register_adapter(DateTime, lambda val: val.isoformat(' '))

mysqlclient（原 MySQLdb）和 PyMySQL 默认会使用 type() 函数来确定对象的类型。要解决这个问题，你可以注册一个新的适配器：

.. code-block:: python

import MySQLdb.converters
import pymysql.converters

from pendulum import DateTime

MySQLdb.converters.conversions[DateTime] = MySQLdb.converters.DateTime2literal
pymysql.converters.conversions[DateTime] = pymysql.converters.escape_datetime

django 会使用 isoformat() 方法将日期时间存储在数据库中。然而，由于 pendulum 始终是时区感知的，isoformat() 总是会返回偏移信息，这至少会在 MySQL 数据库中引发错误。要解决这个问题，你可以创建自己的 DateTimeField 或使用前面针对 MySQLdb 的解决方案：

.. code-block:: python

from django.db.models import DateTimeField as BaseDateTimeField
from pendulum import DateTime


class DateTimeField(BaseDateTimeField):

    def value_to_string(self, obj):
        val = self.value_from_object(obj)

        if isinstance(value, DateTime):
            return value.to_datetime_string()

        return '' if val is None else val.isoformat()

贡献

欢迎贡献，特别是本地化方面的贡献。

入门

要在 Pendulum 代码库上工作，你需要在本地克隆项目并通过 poetry <https://poetry.eustace.io>_ 安装所需的依赖项。

.. code-block:: bash

$ git clone git@github.com:sdispater/pendulum.git
$ poetry install

本地化

如果你想帮助本地化，有两种不同的情况：区域设置已经存在或不存在。

如果区域设置不存在，你需要使用 clock 工具创建它：

.. code-block:: bash

./clock locale create <your-locale>

它将在 pendulum/locales 中生成一个以你的区域设置命名的目录，结构如下：

.. code-block:: text

<your-locale>/
    - custom.py
    - locale.py

不得修改 locale.py 文件。它包含由 CLDR 数据库提供的翻译。

custom.py 文件是你要修改的文件。它包含 Pendulum 所需的、CLDR 数据库未提供的数据。你可以参考 en <https://github.com/sdispater/pendulum/tree/master/pendulum/locales/en/custom.py>_ 数据，看看需要哪些数据。

你还应该为创建或修改的区域设置添加测试。