Metadata-Version: 2.3
Name: mingzi
Version: 1.1.2
Author-email: Aliyacs Souna <17818403529@139.com>
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.5
Description-Content-Type: text/markdown

### MINGZI
这是一个用来生成随机中文姓名的包。

This is a library for developers to use to generate random Chinese names.

该包本身是纯Python，不依赖于标准Python发行版之外的模块或包。

The package itself is pure Python with no dependencies on modules or packages outside the standard Python distribution.

几个月以前，作者在对一个中学的数据库进行测试时，需要用到大量随机姓名，发现似乎缺少能满足这一需求的包，因而展开了这个项目。

The project began a few months ago when the authors were testing a high school database with a large number of random names and found that there seemed to be a lack of packages to meet this need.

### Installation

```{python}
pip install mingzi
```

### Quick Start

您可以通过控制 volume 参数来控制输出的随机姓名的数量。

You can control the number of names output by controlling the volume variable.

```{python}
mingzi(volume=5)
>>> [['温悠', '女'], ['李嘉茵', '女'], ['孟虚', '男'], ['王俊', '男'], ['周伦', '男']]
```

### Show Gender

像世界上大多数其他国家一样，你可以从我们中国人的姓名大致知道其性别。为了满足开发中的实际需要，你可以通过 show_gender 参数来控制是否输出姓名的性别信息。

Like in most other countries in the world, you can roughly know our Chinese person's gender from their name. In order to meet the practical needs of development, you can use the show_gender parameter to control whether to output the gender information of the name.

```{python}
mingzi(volume=5, show_gender=False)
>>> ['李昊惟', '邵儿', '朱奕', '刘宇军', '孙易']
```

```{python}
mingzi(volume=5, show_gender=True)
>>> [['范若翰', '男'], ['邓铭锵', '男'], ['刘贝韵', '女'], ['施喆', '男'], ['陈楚悦', '女']]
```

### Female Rate

你可以通过 female_rate 参数来控制输出姓名列表中女性姓名的比例，这一参数默认为0.49，即为中国目前(2024年)人口女性比例。

You can use the female_rate parameter to control the proportion of female names in the output name list. This parameter defaults to 0.49, which is the proportion of women in the current(2024)population of China.

```{python}
mingzi(volume=5, female_rate=0.2)
>>> [['尚旭', '男'], ['任淇', '男'], ['杨鑫', '男'], ['陈素卿', '女'], ['王杭', '男']]

mingzi(volume=5, female_rate=0)
>>> [['祝泽商', '男'], ['骆奎', '男'], ['王凯泽', '男'], ['郑舱', '男'], ['孙魏', '男']]
```

### Surname Distribution

中国人的姓名由姓氏和名字组成，不同的姓氏在人口中占有不同的比例。你以笔者的姓氏，“李姓”为例，这个比例大概在百分之七左右，在设计这个包的时候，这一点得到了妥善的考虑：不同的姓氏在输出数据中占有的不同的比例，具体参考于当前的人口统计数据。

如果你是国人的话，你能从如下测试数据中很容易地发现，这和我们的日常经验是相符的。

Chinese names consist of surnames and first names, and different surnames occupy different proportions in the population. If you take the author's last name, "李" for example, the percentage is around seven percent, which was properly taken into account when designing the package: different surnames account for different percentages in the output data, specific to the current demographic data. 

If you are a Chinese, you can easily see from the following test data, which is consistent with our daily experience.

```{python}
mingzi(volume=100, show_gender=False)
>>> ['刘灏风', '叶松', '宋恬', '赵秦齐', '何怡芬', '余伟', '唐平', '吴忆狄', '黄书', '于琪纯', '傅娴', '罗菲', '徐宇', '张风', '李雁楚', '童虞', '李虚', '陈稹', '宋语', '陈拾', '刘彰', '潘任', '孙晨纶', '汤元', '江永茂', '张生', '贾昭美', '韦科', '吴哲', '王盛', '徐娅', '朱诗', '胡鑫', '姜翠', '魏谚', '梁泽商', '王嘉茵', '孙拾', '秦艳', '傅娴', '刘菁', '周蒙', '韦曦', '李痴', '吴偌瑾', '谢雄', '李宇军', '胡佳禾', '程丽', '史鸣哲', '陈若翰', '锺宁', '史自昊', '罗书琴', '潘觅', '孙璥', '陈泽商', '舒莉', '薛聪', '张锋玮', '杨熙岩', '王泰骞', '孙娥', '楼函', '魏妮', '向珅南', '高蓝', '吴若娜', '李茂', '马群', '陈君', '王青熙', '易新菱', '叶令', '王舞', '王茂彦', '李纹窈', '陈旭平', '李万信', '孔松樱', '苗松芬', '田希嫣', '张奕', '李林', '蓝慕巧', '李觅蕴', '孔希嫣', '罗州', '马行', '汤宇', '苏晴茹', '陈阳', '杨梓琪', '陈赫', '王霄', '郭霆', '刘雅妙', '刘秦恒', '王纹窈', '马峰']

```

### Complex Surname

少数中国人的姓氏由两个汉字组成，也就是“复姓”，复姓人口在中国占有的比例很少，只有大概千分之一，然而你可以通过调整 com_rate 参数的大小，来调整这一比例，来提高输出数据中复姓姓名的比例，这在某些情形，你比如说为一个武侠游戏生成测试数据和素材，是很有必要的。

A few Chinese surnames are composed of two Chinese characters, namely "compound surname". The proportion of compound surname population in China is very small, only about one thousand. However, you can adjust this proportion by adjusting the size of com_rate parameter, so as to increase the proportion of compound surname in output data. It is necessary for you to generate test data and material for, say, a martial arts game.

```{python}
mingzi(volume=10, com_rate=0.9, show_gender=False)
>>> ['申屠素卿', '单于怡芬', '呼延莎', '刘清滢', '姚玥', '公良雁楚', '吴嘉茵', '夏侯凌', '公羊冰', '巫马昶']

```

### Single Rate

绝大多数中国人的名字是单字名或者双字名，此包也仅仅生成这两种类型的名字。你可以通过 single_rate 来控制输出的姓名中单字名的比例，这个变量的缺省值为0.14，即为目前统计数据显示的中国单字名在全部人口中所占的比例。

The vast majority of Chinese names are single-word or double-word names, and this package generates only those two types of names. You can control the proportion of single names in the output by single_rate. The default value of this variable is 0.14, which is the proportion of Chinese single names in the total population as shown in the current statistics.

```{python}
mingzi(volume=10, single_rate=0.7, show_gender=False)
>>> ['魏炫灿', '康文芝', '赵贻', '张南', '杜靖', '罗茵', '杨凯', '周燕', '谷浦宇', '陈君']

```
