Merge remote-tracking branch 'origin/develop'

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
         os: [windows-latest]
         # python-version: [2.7, 3.5, 3.6, 3.7, 3.8]
         python-version: [3.9]
-        tox-env: [py27, py35, py36, py37, py38, py39, py310]
+        tox-env: [py27, py36, py37, py38, py39, py310]
 
     steps:
     - uses: actions/checkout@v2

CHANGELOG.rst

@@ -2,6 +2,18 @@ Changelog
 ---------
 
 
+`0.46.0`_ (2022-02-12)
++++++++++++++++++++++++++
+
+* **[New]** ``pypinyin.contrib.tone_convert`` 模块新增 ``to_finals_tone`` 、``to_finals_tone2``
+  以及 ``to_finals_tone3`` 函数，用于将拼音转换为 ``Style.FINALS_TONE`` 、 ``Style.FINALS_TONE2``
+  以及 ``Style.FINALS_TONE3`` 风格的结果。
+* **[Changed]** 将 ``pypinyin.contrib.tone_convert`` 模块中 ``to_tone2`` 、 ``to_tone3``、
+  ``tone_to_tone2`` 及 ``tone_to_tone3`` 函数的 ``neutral_tone_with_5`` 参数重命名为统一的
+  ``neutral_tone_with_five`` 参数名称，兼容已有代码传入的 ``neutral_tone_with_5`` 参数。建议升级版本后择期修改为
+  使用新的 ``neutral_tone_with_five`` 参数名称。
+
+
 `0.45.0`_ (2022-01-23)
 +++++++++++++++++++++++++
 
@@ -960,3 +972,4 @@ __ https://github.com/mozillazg/python-pinyin/issues/8
 .. _0.43.0: https://github.com/mozillazg/python-pinyin/compare/v0.42.1...v0.43.0
 .. _0.44.0: https://github.com/mozillazg/python-pinyin/compare/v0.43.0...v0.44.0
 .. _0.45.0: https://github.com/mozillazg/python-pinyin/compare/v0.44.0...v0.45.0
+.. _0.46.0: https://github.com/mozillazg/python-pinyin/compare/v0.45.0...v0.46.0

README.rst

@@ -6,7 +6,7 @@
 
 将汉字转为拼音。可以用于汉字注音、排序、检索(`Russian translation`_) 。
 
-基于 `hotoo/pinyin <https://github.com/hotoo/pinyin>`__ 开发。
+最初版本的代码参考了 `hotoo/pinyin <https://github.com/hotoo/pinyin>`__ 的实现。
 
 * Documentation: http://pypinyin.rtfd.io/
 * GitHub: https://github.com/mozillazg/python-pinyin
@@ -166,6 +166,29 @@ y，w，ü (yu) 都不是声母。
 
 详见 `strict 参数的影响`_ 。
 
+
+如何将某一风格的拼音转换为其他风格的拼音
+++++++++++++++++++++++++++++++++++++++++++++
+
+可以通过 ``pypinyin.contrib.tone_convert`` 模块对标准拼音进行转换，得到不同风格的拼音。
+比如将 ``zhōng`` 转换为 ``zhong``，或者获取拼音中的声母或韵母数据：
+
+.. code-block:: python
+
+    >>> from pypinyin.contrib.tone_convert import to_normal, to_tone, to_initials, to_finals
+    >>> to_normal('zhōng')
+    'zhong'
+    >>> to_tone('zhong1')
+    'zhōng'
+    >>> to_initials('zhōng')
+    'zh'
+    >>> to_finals('zhōng')
+    'ong'
+
+更多拼音转换的辅助函数，详见 ``pypinyin.contrib.tone_convert`` 模块的
+`文档 <https://pypinyin.readthedocs.io/zh_CN/master/contrib.html#tone-convert>`__ 。
+
+
 如何减少内存占用
 ++++++++++++++++++++
 

docs/contrib.rst

@@ -14,6 +14,9 @@ contrib
 .. autofunction:: pypinyin.contrib.tone_convert.to_tone3
 .. autofunction:: pypinyin.contrib.tone_convert.to_initials
 .. autofunction:: pypinyin.contrib.tone_convert.to_finals
+.. autofunction:: pypinyin.contrib.tone_convert.to_finals_tone
+.. autofunction:: pypinyin.contrib.tone_convert.to_finals_tone2
+.. autofunction:: pypinyin.contrib.tone_convert.to_finals_tone3
 
 .. autofunction:: pypinyin.contrib.tone_convert.tone_to_normal
 .. autofunction:: pypinyin.contrib.tone_convert.tone_to_tone2

docs/index.rst

@@ -11,7 +11,7 @@
 
 将汉字转为拼音。可以用于汉字注音、排序、检索(`Russian translation`_) 。
 
-基于 `hotoo/pinyin <https://github.com/hotoo/pinyin>`__ 开发。
+最初版本的代码参考了 `hotoo/pinyin <https://github.com/hotoo/pinyin>`__ 的实现。
 
 * Documentation: http://pypinyin.rtfd.io
 * GitHub: https://github.com/mozillazg/python-pinyin

pypinyin/contrib/tone_convert.py

@@ -1,14 +1,16 @@
 # -*- coding: utf-8 -*-
 from __future__ import unicode_literals
 
-# 向后兼容
 from pypinyin.style._tone_convert import (  # noqa
     to_normal,
     to_tone,
     to_tone2,
     to_tone3,
     to_initials,
     to_finals,
+    to_finals_tone,
+    to_finals_tone2,
+    to_finals_tone3,
     tone_to_normal,
     tone_to_tone2,
     tone_to_tone3,
@@ -18,6 +20,7 @@
     tone3_to_normal,
     tone3_to_tone,
     tone3_to_tone2,
+    # 向后兼容
     _improve_tone3,
     _get_number_from_pinyin,
     _v_to_u,

pypinyin/contrib/tone_convert.pyi

@@ -10,19 +10,25 @@ def to_normal(pinyin: Text, v_to_u: bool = ...) -> Text: ...
 
 def to_tone(pinyin: Text) -> Text: ...
 
-def to_tone2(pinyin: Text, v_to_u: bool = ..., neutral_tone_with_5: bool = ...) -> Text: ...
+def to_tone2(pinyin: Text, v_to_u: bool = ..., neutral_tone_with_five: bool = ...) -> Text: ...
 
-def to_tone3(pinyin: Text, v_to_u: bool = ..., neutral_tone_with_5: bool = ...) -> Text: ...
+def to_tone3(pinyin: Text, v_to_u: bool = ..., neutral_tone_with_five: bool = ...) -> Text: ...
 
 def to_initials(pinyin: Text, strict: bool = ...) -> Text: ...
 
 def to_finals(pinyin: Text, strict: bool = ..., v_to_u: bool = ...) -> Text: ...
 
+def to_finals_tone(pinyin: Text, strict: bool = ...) -> Text: ...
+
+def to_finals_tone2(pinyin: Text, strict: bool = ..., v_to_u: bool = ..., neutral_tone_with_five: bool = ...) -> Text: ...
+
+def to_finals_tone3(pinyin: Text, strict: bool = ..., v_to_u: bool = ..., neutral_tone_with_five: bool = ...) -> Text: ...
+
 def tone_to_normal(tone: Text, v_to_u: bool = ...) -> Text: ...
 
-def tone_to_tone2(tone: Text, v_to_u: bool = ..., neutral_tone_with_5: bool = ...) -> Text: ...
+def tone_to_tone2(tone: Text, v_to_u: bool = ..., neutral_tone_with_five: bool = ...) -> Text: ...
 
-def tone_to_tone3(tone: Text, v_to_u: bool = ..., neutral_tone_with_5: bool = ...) -> Text: ...
+def tone_to_tone3(tone: Text, v_to_u: bool = ..., neutral_tone_with_five: bool = ...) -> Text: ...
 
 def tone2_to_normal(tone2: Text, v_to_u: bool = ...) -> Text: ...
 
@@ -36,7 +42,7 @@ def tone3_to_tone(tone3: Text) -> Text: ...
 
 def tone3_to_tone2(tone3: Text, v_to_u: bool = ...) -> Text: ...
 
-def _improve_tone3(tone3: Text, neutral_tone_with_5: bool = ...) -> Text: ...
+def _improve_tone3(tone3: Text, neutral_tone_with_five: bool = ...) -> Text: ...
 
 def _get_number_from_pinyin(pinyin: Text) -> Optional[int]: ...
 

pypinyin/style/__init__.py

@@ -25,7 +25,11 @@ def convert(pinyin, style, strict, default=None, **kwargs):
 
 
 def register(style, func=None):
-    """注册一个拼音风格实现
+    """注册一个拼音风格实现。
+    自定义的函数应当使用 ``**kwargs`` 来兼容后续可能会新增的关键字参数，
+    当前默认会传递如下参数：
+
+    * ``strict``
 
     ::