| Name | pingshui-rhyme JSON |
| Version |
0.17
JSON |
| download |
| home_page | https://github.com/rbnyng/pingshui_rhyme |
| Summary | A Python package for classifying Chinese characters phonologically based on the Middle Chinese Pingshui rhyme scheme |
| upload_time | 2024-09-11 02:11:12 |
| maintainer | None |
| docs_url | None |
| author | rbnyng |
| requires_python | >=3.6 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Pingshui Rhyme
**Pingshui Rhyme** is a Python package designed to classify tonal patterns ("ping" 平 and "ze" 仄 tones) and rhyme categories ("韻腳") of Chinese characters based on the [Pingshui Rhyme](https://zh.wikisource.org/wiki/%E5%B9%B3%E6%B0%B4%E9%9F%BB) (平水韻) rhyme scheme. You can read more about ping-ze, or tonal patterns, [here.](https://en.wikipedia.org/wiki/Tone_pattern) Modern Chinese varieties are not suitable for determining the phonological values of characters in middle Chinese due to sound changes, thus this package was built to use period accurate data to retrieve info about characters.
The package includes a pre-scraped JSON file that contains the complete data from the rhyme dictionary, and also provides a scraper to update the data if necessary.
## Features
- **Classify Chinese characters**: Easily classify characters as 'ping' or 'ze' based on the Pingshui Rhyme scheme.
- **Rhyme comparison**: Check if two characters rhyme based on their tonal and rhyme categories.
- **Rhyme group lookup**: Get detailed rhyme group information, such as tone type, tone group, and specific rhyme category for any given character.
- **Pre-packaged data**: Includes a pre-scraped JSON file with the complete rhyme data.
- **Scraper**: An optional scraper is included to regenerate the JSON file when the source data changes.
- **Poem structure checking**: Analyze and verify the structure of classical Chinese poems (Jueju and Lushi forms).
## Installation
You can install the package by running:
```bash
pip install pingshui_rhyme
```
## Usage
### Classifying Characters
Once installed, you can use the `PingZeClassifier` class to classify Chinese characters based on their tone as either "ping" (平) or "ze" (仄) tones:
```python
from pingshui_rhyme import PingZeClassifier
# Initialize the classifier (uses pre-packaged JSON by default)
classifier = PingZeClassifier()
# Classify a sentence
sentence = "知否？知否？應是綠肥紅瘦。"
result = classifier.classify(sentence)
print(result)
# Output: ['ping', 'ze', 'unknown', 'ping', 'ze', 'unknown', 'ping', 'ze', 'ze', 'ping', 'ping', 'ze', 'unknown']
```
### Rhyme Checking
You can also use the `RhymeChecker` class to check if two characters rhyme based on their tone group and rhyme category.
```python
from pingshui_rhyme import RhymeChecker
# Initialize the rhyme checker
rhyme_checker = RhymeChecker()
# Check if two characters rhyme
char1 = "東"
char2 = "同"
do_they_rhyme = rhyme_checker.do_rhyme(char1, char2)
print(do_they_rhyme) # Output: True
# Get the rhyme group of a character
rhyme_group = rhyme_checker.get_rhyme_group(char1)
print(rhyme_group)
# Output: ('ping', '上平聲部', '上平聲一東')
```
### Poem Structure Checking
The `PoemStructureChecker` class allows you to analyze and verify the structure of classical Chinese poems (Jueju and Lushi forms).
```python
from pingshui_rhyme import PoemStructureChecker
# Initialize the poem structure checker
poem_checker = PoemStructureChecker()
# Check a Jueju poem
jueju_poem = '''
床前明月光，
疑是地上霜。
舉頭望明月，
低頭思故鄉。
'''
result, message = checker.check_poem_rhyming(jueju_poem)
print(result) # Output: True
print(message) # Output: "Poem follows jueju rhyming rules."
# Check a Lushi poem
lushi_poem = '''
昔人已乘黃鶴去，
此地空餘黃鶴樓。
黃鶴一去不復返，
白雲千載空悠悠。
晴川歷歷漢陽樹，
芳草萋萋鸚鵡洲。
日暮鄉關何處是，
煙波江上使人愁。
'''
result, message = checker.check_poem_rhyming(lushi_poem)
print(result) # Output: True
print(message) # Output: "Poem follows lushi rhyming rules."
# Check ping-ze meter
pingze_poem = '''
歲莫陰陽催短景，天涯霜雪霽寒霄。
五更鼓角聲悲壯，三峽星河影動搖。
野哭千家聞戰伐，夷歌幾處起漁樵。
臥龍躍馬終黃土，人事音書漫寂寥。
'''
result, message = checker.check_poem_pingze_meter(pingze_poem)
print(result) # Output: True
print(message) # Output: "Poem follows the less restrictive ping-ze alternation pattern in 2nd, 4th, and 6th characters."
```
The `PoemStructureChecker` provides two main methods:
1. `check_poem_rhyming(poem)`: Checks if the poem follows the proper rhyme scheme for Jueju or Lushi forms.
2. `check_poem_pingze_meter(poem)`: Verifies if the poem follows the correct tonal pattern (ping-ze meter) according to classical Chinese poetry rules.
These methods return a tuple containing a boolean (indicating whether the poem passes the check) and a message explaining the result.
### Ping-Ze Label Conversion
The `PoemStructureChecker` class also provides methods to convert ping-ze labels between Chinese and English:
```python
from pingshui_rhyme import PoemStructureChecker
checker = PoemStructureChecker()
# Convert ping-ze labels to Chinese
chinese_labels = checker.pingze_en_convert_to_zh('ping')
print(chinese_labels) # Output: '平'
```
### Scraping and Regenerating the JSON Data
The package includes a pre-generated JSON file, but if the Pingshui Rhyme source from wikisource changes you can run the scraper.
#### Running the Scraper
By default, the scraper won't run if the JSON file already exists. To force a refresh and regenerate the JSON data, run the following command:
```bash
scrape-pingze --force-refresh
```
This will scrape the latest data from the source and regenerate the `organized_ping_ze_rhyme_dict.json` file.
## Dependencies
`requests`: For web scraping the Pingshui Rhyme data.
`beautifulsoup4`: For parsing the HTML content from the Pingshui Rhyme source page.
## Running Unit Tests
Unit tests for the classifiers and rhyme checker are included. You can run the tests using `unittest`:
```bash
python -m unittest discover
```
## License
This package is licensed under the MIT License. See the LICENSE[LICENSE] file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/rbnyng/pingshui_rhyme",
"name": "pingshui-rhyme",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "rbnyng",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/27/b5/778cc776879c7926d8d5de683aa2c140930bc80948d74141a2f489e0eccf/pingshui_rhyme-0.17.tar.gz",
"platform": null,
"description": "# Pingshui Rhyme\r\n\r\n**Pingshui Rhyme** is a Python package designed to classify tonal patterns (\"ping\" \u5e73 and \"ze\" \u4ec4 tones) and rhyme categories (\"\u97fb\u8173\") of Chinese characters based on the [Pingshui Rhyme](https://zh.wikisource.org/wiki/%E5%B9%B3%E6%B0%B4%E9%9F%BB) (\u5e73\u6c34\u97fb) rhyme scheme. You can read more about ping-ze, or tonal patterns, [here.](https://en.wikipedia.org/wiki/Tone_pattern) Modern Chinese varieties are not suitable for determining the phonological values of characters in middle Chinese due to sound changes, thus this package was built to use period accurate data to retrieve info about characters.\r\n\r\nThe package includes a pre-scraped JSON file that contains the complete data from the rhyme dictionary, and also provides a scraper to update the data if necessary.\r\n\r\n## Features\r\n\r\n- **Classify Chinese characters**: Easily classify characters as 'ping' or 'ze' based on the Pingshui Rhyme scheme.\r\n- **Rhyme comparison**: Check if two characters rhyme based on their tonal and rhyme categories.\r\n- **Rhyme group lookup**: Get detailed rhyme group information, such as tone type, tone group, and specific rhyme category for any given character.\r\n- **Pre-packaged data**: Includes a pre-scraped JSON file with the complete rhyme data.\r\n- **Scraper**: An optional scraper is included to regenerate the JSON file when the source data changes.\r\n- **Poem structure checking**: Analyze and verify the structure of classical Chinese poems (Jueju and Lushi forms).\r\n\r\n## Installation\r\n\r\nYou can install the package by running:\r\n\r\n```bash\r\npip install pingshui_rhyme\r\n```\r\n\r\n## Usage\r\n\r\n### Classifying Characters\r\n\r\nOnce installed, you can use the `PingZeClassifier` class to classify Chinese characters based on their tone as either \"ping\" (\u5e73) or \"ze\" (\u4ec4) tones:\r\n\r\n```python\r\nfrom pingshui_rhyme import PingZeClassifier\r\n\r\n# Initialize the classifier (uses pre-packaged JSON by default)\r\nclassifier = PingZeClassifier()\r\n\r\n# Classify a sentence\r\nsentence = \"\u77e5\u5426\uff1f\u77e5\u5426\uff1f\u61c9\u662f\u7da0\u80a5\u7d05\u7626\u3002\"\r\nresult = classifier.classify(sentence)\r\nprint(result)\r\n# Output: ['ping', 'ze', 'unknown', 'ping', 'ze', 'unknown', 'ping', 'ze', 'ze', 'ping', 'ping', 'ze', 'unknown']\r\n```\r\n\r\n### Rhyme Checking\r\n\r\nYou can also use the `RhymeChecker` class to check if two characters rhyme based on their tone group and rhyme category.\r\n\r\n```python\r\nfrom pingshui_rhyme import RhymeChecker\r\n\r\n# Initialize the rhyme checker\r\nrhyme_checker = RhymeChecker()\r\n\r\n# Check if two characters rhyme\r\nchar1 = \"\u6771\"\r\nchar2 = \"\u540c\"\r\ndo_they_rhyme = rhyme_checker.do_rhyme(char1, char2)\r\nprint(do_they_rhyme) # Output: True\r\n\r\n# Get the rhyme group of a character\r\nrhyme_group = rhyme_checker.get_rhyme_group(char1)\r\nprint(rhyme_group)\r\n# Output: ('ping', '\u4e0a\u5e73\u8072\u90e8', '\u4e0a\u5e73\u8072\u4e00\u6771')\r\n```\r\n\r\n### Poem Structure Checking\r\n\r\nThe `PoemStructureChecker` class allows you to analyze and verify the structure of classical Chinese poems (Jueju and Lushi forms).\r\n\r\n```python\r\nfrom pingshui_rhyme import PoemStructureChecker\r\n\r\n# Initialize the poem structure checker\r\npoem_checker = PoemStructureChecker()\r\n\r\n# Check a Jueju poem\r\njueju_poem = '''\r\n\u5e8a\u524d\u660e\u6708\u5149\uff0c\r\n\u7591\u662f\u5730\u4e0a\u971c\u3002\r\n\u8209\u982d\u671b\u660e\u6708\uff0c\r\n\u4f4e\u982d\u601d\u6545\u9109\u3002\r\n'''\r\nresult, message = checker.check_poem_rhyming(jueju_poem)\r\nprint(result) # Output: True\r\nprint(message) # Output: \"Poem follows jueju rhyming rules.\"\r\n\r\n# Check a Lushi poem\r\nlushi_poem = '''\r\n\u6614\u4eba\u5df2\u4e58\u9ec3\u9db4\u53bb\uff0c\r\n\u6b64\u5730\u7a7a\u9918\u9ec3\u9db4\u6a13\u3002\r\n\u9ec3\u9db4\u4e00\u53bb\u4e0d\u5fa9\u8fd4\uff0c\r\n\u767d\u96f2\u5343\u8f09\u7a7a\u60a0\u60a0\u3002\r\n\u6674\u5ddd\u6b77\u6b77\u6f22\u967d\u6a39\uff0c\r\n\u82b3\u8349\u840b\u840b\u9e1a\u9d61\u6d32\u3002\r\n\u65e5\u66ae\u9109\u95dc\u4f55\u8655\u662f\uff0c\r\n\u7159\u6ce2\u6c5f\u4e0a\u4f7f\u4eba\u6101\u3002\r\n'''\r\nresult, message = checker.check_poem_rhyming(lushi_poem)\r\nprint(result) # Output: True\r\nprint(message) # Output: \"Poem follows lushi rhyming rules.\"\r\n\r\n# Check ping-ze meter\r\npingze_poem = '''\r\n\u6b72\u83ab\u9670\u967d\u50ac\u77ed\u666f\uff0c\u5929\u6daf\u971c\u96ea\u973d\u5bd2\u9704\u3002\r\n\u4e94\u66f4\u9f13\u89d2\u8072\u60b2\u58ef\uff0c\u4e09\u5cfd\u661f\u6cb3\u5f71\u52d5\u6416\u3002\r\n\u91ce\u54ed\u5343\u5bb6\u805e\u6230\u4f10\uff0c\u5937\u6b4c\u5e7e\u8655\u8d77\u6f01\u6a35\u3002\r\n\u81e5\u9f8d\u8e8d\u99ac\u7d42\u9ec3\u571f\uff0c\u4eba\u4e8b\u97f3\u66f8\u6f2b\u5bc2\u5be5\u3002 \r\n'''\r\nresult, message = checker.check_poem_pingze_meter(pingze_poem)\r\nprint(result) # Output: True\r\nprint(message) # Output: \"Poem follows the less restrictive ping-ze alternation pattern in 2nd, 4th, and 6th characters.\"\r\n``` \r\n\r\nThe `PoemStructureChecker` provides two main methods:\r\n\r\n1. `check_poem_rhyming(poem)`: Checks if the poem follows the proper rhyme scheme for Jueju or Lushi forms.\r\n2. `check_poem_pingze_meter(poem)`: Verifies if the poem follows the correct tonal pattern (ping-ze meter) according to classical Chinese poetry rules.\r\n\r\nThese methods return a tuple containing a boolean (indicating whether the poem passes the check) and a message explaining the result.\r\n\r\n### Ping-Ze Label Conversion\r\n\r\nThe `PoemStructureChecker` class also provides methods to convert ping-ze labels between Chinese and English:\r\n\r\n```python\r\nfrom pingshui_rhyme import PoemStructureChecker\r\n\r\nchecker = PoemStructureChecker()\r\n\r\n# Convert ping-ze labels to Chinese\r\nchinese_labels = checker.pingze_en_convert_to_zh('ping')\r\nprint(chinese_labels) # Output: '\u5e73'\r\n```\r\n\r\n### Scraping and Regenerating the JSON Data\r\n\r\nThe package includes a pre-generated JSON file, but if the Pingshui Rhyme source from wikisource changes you can run the scraper.\r\n\r\n#### Running the Scraper\r\n\r\nBy default, the scraper won't run if the JSON file already exists. To force a refresh and regenerate the JSON data, run the following command:\r\n\r\n```bash\r\nscrape-pingze --force-refresh\r\n```\r\n\r\nThis will scrape the latest data from the source and regenerate the `organized_ping_ze_rhyme_dict.json` file.\r\n\r\n## Dependencies\r\n\r\n `requests`: For web scraping the Pingshui Rhyme data.\r\n `beautifulsoup4`: For parsing the HTML content from the Pingshui Rhyme source page.\r\n\r\n## Running Unit Tests\r\n\r\nUnit tests for the classifiers and rhyme checker are included. You can run the tests using `unittest`:\r\n\r\n```bash\r\npython -m unittest discover\r\n```\r\n\r\n## License\r\n\r\nThis package is licensed under the MIT License. See the LICENSE[LICENSE] file for details.\r\n\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python package for classifying Chinese characters phonologically based on the Middle Chinese Pingshui rhyme scheme",
"version": "0.17",
"project_urls": {
"Homepage": "https://github.com/rbnyng/pingshui_rhyme"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "81732dee3b0ad0f0d243f0a4e94c5a945a390eebb5b03fcedf1a72d08e39fa5b",
"md5": "6e4ff76e864cdd3ba94074355474fa5e",
"sha256": "1eac4ac3f4f7a6bfcc495291d50b08194c7948b5b43be06832108fd8138b8a7e"
},
"downloads": -1,
"filename": "pingshui_rhyme-0.17-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6e4ff76e864cdd3ba94074355474fa5e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 38356,
"upload_time": "2024-09-11T02:11:10",
"upload_time_iso_8601": "2024-09-11T02:11:10.390124Z",
"url": "https://files.pythonhosted.org/packages/81/73/2dee3b0ad0f0d243f0a4e94c5a945a390eebb5b03fcedf1a72d08e39fa5b/pingshui_rhyme-0.17-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "27b5778cc776879c7926d8d5de683aa2c140930bc80948d74141a2f489e0eccf",
"md5": "032b29cfcad8e149bf4d1c9434befe96",
"sha256": "0b87dab3f66192185c68a9c522a5481ab2329b728a14061cbe5d5780844fa84a"
},
"downloads": -1,
"filename": "pingshui_rhyme-0.17.tar.gz",
"has_sig": false,
"md5_digest": "032b29cfcad8e149bf4d1c9434befe96",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 39832,
"upload_time": "2024-09-11T02:11:12",
"upload_time_iso_8601": "2024-09-11T02:11:12.070221Z",
"url": "https://files.pythonhosted.org/packages/27/b5/778cc776879c7926d8d5de683aa2c140930bc80948d74141a2f489e0eccf/pingshui_rhyme-0.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-11 02:11:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rbnyng",
"github_project": "pingshui_rhyme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pingshui-rhyme"
}
