欢迎来到 Faker 文档！¶

Faker 是一个 Python 包，可以为您生成假数据。无论您需要引导数据库、创建美观的 XML 文档、填充持久层进行压力测试，还是对来自生产服务的数据进行匿名化，Faker 都适合您。

Faker 深受 PHP Faker、Perl Faker 以及 Ruby Faker 的启发。

_|_|_|_|          _|
_|        _|_|_|  _|  _|      _|_|    _|  _|_|
_|_|_|  _|    _|  _|_|      _|_|_|_|  _|_|
_|      _|    _|  _|  _|    _|        _|
_|        _|_|_|  _|    _|    _|_|_|  _|

兼容性¶

从版本 4.0.0 开始，Faker 放弃了对 Python 2 的支持；从版本 5.0.0 开始，仅支持 Python 3.8 及更高版本。如果您仍然需要 Python 2 兼容性，请暂时安装版本 3.0.1，并考虑更新您的代码库以支持 Python 3，这样您就可以享受 Faker 提供的最新功能。请参阅扩展文档以获取更多详细信息，特别是如果您正在从版本 2.0.4 及更低版本升级，因为可能存在重大变更。

此包以前也称为 fake-factory，它已于 2016 年底弃用，此后发生了很大变化，因此请确保您的项目及其依赖项不依赖于旧包。

基本用法¶

使用 pip 安装

pip install Faker

使用 faker.Faker() 创建并初始化一个 faker 生成器，该生成器可以通过访问以您想要的数据类型命名的属性来生成数据。

from faker import Faker
fake = Faker()

fake.name()
# 'Lucy Cechtelar'

fake.address()
# '426 Jordy Lodge
#  Cartwrightshire, SC 88120-6700'

fake.text()
# 'Sint velit eveniet. Rerum atque repellat voluptatem quia rerum. Numquam excepturi
#  beatae sint laudantium consequatur. Magni occaecati itaque sint et sit tempore. Nesciunt
#  amet quidem. Iusto deleniti cum autem ad quia aperiam.
#  A consectetur quos aliquam. In iste aliquid et aut similique suscipit. Consequatur qui
#  quaerat iste minus hic expedita. Consequuntur error magni et laboriosam. Aut aspernatur
#  voluptatem sit aliquam. Dolores voluptatum est.
#  Aut molestias et maxime. Fugit autem facilis quos vero. Eius quibusdam possimus est.
#  Ea quaerat et quisquam. Deleniti sunt quam. Adipisci consequatur id in occaecati.
#  Et sint et. Ut ducimus quod nemo ab voluptatum.'

每次调用方法 fake.name() 都会产生不同的（随机）结果。这是因为 faker 将 faker.Generator.method_name() 调用转发给 faker.Generator.format(method_name)。

for _ in range(10):
  print(fake.name())

# 'Adaline Reichel'
# 'Dr. Santa Prosacco DVM'
# 'Noemy Vandervort V'
# 'Lexi O'Conner'
# 'Gracie Weber'
# 'Roscoe Johns'
# 'Emmett Lebsack'
# 'Keegan Thiel'
# 'Wellington Koelpin II'
# 'Ms. Karley Kiehn V'

Pytest fixture¶

Faker 也有自己的 pytest 插件，它提供了一个 faker fixture，您可以在测试中使用。请查看 pytest fixture 文档了解更多信息。

提供者¶

每个生成器属性（如 name、address 和 lorem）都被称为“fake”。一个 faker 生成器有很多这样的属性，它们被打包在“提供者”（providers）中。

from faker import Faker
from faker.providers import internet

fake = Faker()
fake.add_provider(internet)

print(fake.ipv4_private())

请查看扩展文档以获取捆绑提供者列表和社区提供者列表。

本地化¶

faker.Faker 可以接受一个 locale 作为参数，以返回本地化数据。如果找不到本地化的提供者，工厂将回退到 US english 的默认 LCID 字符串，即：en_US。

from faker import Faker
fake = Faker('it_IT')
for _ in range(10):
    print(fake.name())

# 'Elda Palumbo'
# 'Pacifico Giordano'
# 'Sig. Avide Guerra'
# 'Yago Amato'
# 'Eustachio Messina'
# 'Dott. Violante Lombardo'
# 'Sig. Alighieri Monti'
# 'Costanzo Costa'
# 'Nazzareno Barbieri'
# 'Max Coppola'

faker.Faker 还支持多种 locale。v3.0.0 新增。

from faker import Faker
fake = Faker(['it_IT', 'en_US', 'ja_JP'])
for _ in range(10):
    print(fake.name())

# 鈴木 陽一
# Leslie Moreno
# Emma Williams
# 渡辺 裕美子
# Marcantonio Galuppi
# Martha Davis
# Kristen Turner
# 中津川 春香
# Ashley Castillo
# 山田 桃子

您可以在源代码中，在 providers 包下查看可用的 Faker locale。Faker 的本地化是一个持续进行的过程，我们需要您的帮助。请不要犹豫为您的 locale 创建本地化提供者并提交拉取请求 (PR)。

优化¶

Faker 构造函数接受一个与性能相关的参数 use_weighting。它指定是否尝试使值的频率与真实世界的频率匹配（例如，英文名 Gary 的频率远高于 Lorimer）。如果 use_weighting 为 False，则所有项目被选中的机会均等，并且选择过程更快。默认值为 True。

命令行使用¶

安装后，您可以从命令行调用 faker

faker [-h] [--version] [-o output]
      [-l {bg_BG,cs_CZ,...,zh_CN,zh_TW}]
      [-r REPEAT] [-s SEP]
      [-i {package.containing.custom_provider otherpkg.containing.custom_provider}]
      [fake] [fake argument [fake argument ...]]

其中

faker: 是安装在您的环境中的脚本，在开发中您可以使用 python -m faker 代替
-h, --help: 显示帮助信息
--version: 显示程序的版本号
-o FILENAME: 将输出重定向到指定的 filename
-l {bg_BG,cs_CZ,...,zh_CN,zh_TW}: 允许使用本地化提供者
-r REPEAT: 将生成指定数量的输出
-s SEP: 将在每个生成的输出后生成指定的分隔符
-i {my.custom_provider other.custom_provider} 要使用的额外自定义提供者列表。请注意，这是包含您的 Provider 类的包的导入路径，而不是自定义 Provider 类本身。
fake: 是要生成输出的假数据名称，例如 name、address 或 text
[fake argument ...]: 传递给 fake 的可选参数（例如，profile fake 将逗号分隔的字段名称列表作为第一个可选参数）

示例

$ faker address
968 Bahringer Garden Apt. 722
Kristinaland, NJ 09890

$ faker -l de_DE address
Samira-Niemeier-Allee 56
94812 Biedenkopf

$ faker profile ssn,birthdate
{'ssn': '628-10-1085', 'birthdate': '2008-03-29'}

$ faker -r=3 -s=";" name
Willam Kertzmann;
Josiah Maggio;
Gayla Schmitt;

如何创建提供者¶

from faker import Faker
fake = Faker()

# first, import a similar Provider or use the default one
from faker.providers import BaseProvider

# create new provider class
class MyProvider(BaseProvider):
    def foo(self) -> str:
        return 'bar'

# then add new provider to faker instance
fake.add_provider(MyProvider)

# now you can use:
fake.foo()
# 'bar'

如何创建动态提供者¶

动态提供者可以从外部源读取元素。

from faker import Faker
from faker.providers import DynamicProvider

medical_professions_provider = DynamicProvider(
     provider_name="medical_profession",
     elements=["dr.", "doctor", "nurse", "surgeon", "clerk"],
)

fake = Faker()

# then add new provider to faker instance
fake.add_provider(medical_professions_provider)

# now you can use:
fake.medical_profession()
# 'dr.'

如何自定义 Lorem 提供者¶

如果您不想使用默认的 lorem ipsum 文本，可以提供自己的单词集。以下示例展示了如何使用从 cakeipsum 中挑选的单词列表来实现

from faker import Faker
fake = Faker()

my_word_list = [
'danish','cheesecake','sugar',
'Lollipop','wafer','Gummies',
'sesame','Jelly','beans',
'pie','bar','Ice','oat' ]

fake.sentence()
# 'Expedita at beatae voluptatibus nulla omnis.'

fake.sentence(ext_word_list=my_word_list)
# 'Oat beans oat Lollipop bar cheesecake.'

如何与 Factory Boy 一起使用¶

Factory Boy 已经集成了 Faker。只需使用 factory_boy 的 factory.Faker 方法即可

import factory
from myapp.models import Book

class BookFactory(factory.Factory):
    class Meta:
        model = Book

    title = factory.Faker('sentence', nb_words=4)
    author_name = factory.Faker('name')

访问 random 实例¶

生成器上的 .random 属性返回用于生成值的 random.Random 实例

from faker import Faker
fake = Faker()
fake.random
fake.random.getstate()

默认情况下，所有生成器共享相同的 random.Random 实例，可以通过 from faker.generator import random 访问。对于希望影响所有 faker 实例的插件来说，使用它可能很有用。

唯一值¶

通过使用生成器上的 .unique 属性，您可以保证为这个特定实例生成的任何值都是唯一的。

from faker import Faker
fake = Faker()
names = [fake.unique.first_name() for i in range(500)]
assert len(set(names)) == len(names)

对于具有多个 locale 的 Faker 实例，您可以使用下标表示法指定用于唯一值的 locale

from faker import Faker
fake = Faker(['en_US', 'fr_FR'])
names = [fake.unique["en_US"].first_name() for i in range(500)]
assert len(set(names)) == len(names)

调用 fake.unique.clear() 会清除已见过的值。

请注意，为了避免无限循环，在尝试查找唯一值达到一定次数后，Faker 将抛出 UniquenessException。请注意生日悖论，冲突的可能性比您想象的要高。

from faker import Faker

fake = Faker()
for i in range(3):
     # Raises a UniquenessException
     fake.unique.boolean()

此外，只有可哈希的参数和返回值才能与 .unique 一起使用。

为生成器设定种子¶

在进行单元测试时使用 Faker 时，您通常会希望生成相同的数据集。为了方便起见，生成器还提供了一个 seed() 方法，它为共享的随机数生成器设定种子。当使用相同版本的 faker 调用相同的方法时，种子会产生相同的结果。

from faker import Faker
fake = Faker()
Faker.seed(4321)

print(fake.name())
# 'Margaret Boehm'

每个生成器也可以通过使用 seed_instance() 方法切换为使用自己的 random.Random 实例，与共享实例分离，其作用相同。例如

from faker import Faker
fake = Faker()
fake.seed_instance(4321)

print(fake.name())
# 'Margaret Boehm'

请注意，随着我们不断更新数据集，结果不能保证在补丁版本之间保持一致。如果您在测试中硬编码结果，请确保将 Faker 的版本固定到补丁号。

如果您正在使用 pytest，您可以通过定义一个 faker_seed fixture 为 faker fixture 设定种子。请查看 pytest fixture 文档了解更多信息。

测试¶

运行测试

$ tox

为默认 locale 的提供者编写文档

$ python -m faker > docs.txt

为特定 locale 的提供者编写文档

$ python -m faker --lang=de_DE > docs_de.txt

贡献¶

请参阅 CONTRIBUTING。

许可证¶

Faker 根据 MIT 许可证发布。有关详细信息，请参阅捆绑的 LICENSE 文件。