1*Faker* is a Python package that generates fake data for you. Whether
2you need to bootstrap your database, create good-looking XML documents,
3fill-in your persistence to stress test it, or anonymize data taken from
4a production service, Faker is for you.
5
6Faker is heavily inspired by `PHP Faker`_, `Perl Faker`_, and by `Ruby Faker`_.
7
8----
9
10::
11
12 _|_|_|_| _|
13 _| _|_|_| _| _| _|_| _| _|_|
14 _|_|_| _| _| _|_| _|_|_|_| _|_|
15 _| _| _| _| _| _| _|
16 _| _|_|_| _| _| _|_|_| _|
17
18|pypi| |unix_build| |windows_build| |coverage| |license|
19
20----
21
22For more details, see the `extended docs`_.
23
24Basic Usage
25-----------
26
27Install with pip:
28
29.. code:: bash
30
31 pip install Faker
32
33*Note: this package was previously called* ``fake-factory``.
34
35Use ``faker.Faker()`` to create and initialize a faker
36generator, which can generate data by accessing properties named after
37the type of data you want.
38
39.. code:: python
40
41 from faker import Faker
42 fake = Faker()
43
44 fake.name()
45 # 'Lucy Cechtelar'
46
47 fake.address()
48 # "426 Jordy Lodge
49 # Cartwrightshire, SC 88120-6700"
50
51 fake.text()
52 # Sint velit eveniet. Rerum atque repellat voluptatem quia rerum. Numquam excepturi
53 # beatae sint laudantium consequatur. Magni occaecati itaque sint et sit tempore. Nesciunt
54 # amet quidem. Iusto deleniti cum autem ad quia aperiam.
55 # A consectetur quos aliquam. In iste aliquid et aut similique suscipit. Consequatur qui
56 # quaerat iste minus hic expedita. Consequuntur error magni et laboriosam. Aut aspernatur
57 # voluptatem sit aliquam. Dolores voluptatum est.
58 # Aut molestias et maxime. Fugit autem facilis quos vero. Eius quibusdam possimus est.
59 # Ea quaerat et quisquam. Deleniti sunt quam. Adipisci consequatur id in occaecati.
60 # Et sint et. Ut ducimus quod nemo ab voluptatum.
61
62Each call to method ``fake.name()`` yields a different (random) result.
63This is because faker forwards ``faker.Generator.method_name()`` calls
64to ``faker.Generator.format(method_name)``.
65
66.. code:: python
67
68 for _ in range(10):
69 print(fake.name())
70
71 # Adaline Reichel
72 # Dr. Santa Prosacco DVM
73 # Noemy Vandervort V
74 # Lexi O'Conner
75 # Gracie Weber
76 # Roscoe Johns
77 # Emmett Lebsack
78 # Keegan Thiel
79 # Wellington Koelpin II
80 # Ms. Karley Kiehn V
81
82Providers
83---------
84
85Each of the generator properties (like ``name``, ``address``, and
86``lorem``) are called "fake". A faker generator has many of them,
87packaged in "providers".
88
89Check the `extended docs`_ for a list of `bundled providers`_ and a list of
90`community providers`_.
91
92Localization
93------------
94
95``faker.Factory`` can take a locale as an argument, to return localized
96data. If no localized provider is found, the factory falls back to the
97default en\_US locale.
98
99.. code:: python
100
101 from faker import Faker
102 fake = Faker('it_IT')
103 for _ in range(10):
104 print(fake.name())
105
106 > Elda Palumbo
107 > Pacifico Giordano
108 > Sig. Avide Guerra
109 > Yago Amato
110 > Eustachio Messina
111 > Dott. Violante Lombardo
112 > Sig. Alighieri Monti
113 > Costanzo Costa
114 > Nazzareno Barbieri
115 > Max Coppola
116
117You can check available Faker locales in the source code, under the
118providers package. The localization of Faker is an ongoing process, for
119which we need your help. Please don't hesitate to create a localized
120provider for your own locale and submit a Pull Request (PR).
121
122Included localized providers:
123
124- `ar\_EG <https://faker.readthedocs.io/en/master/locales/ar_EG.html>`__ - Arabic (Egypt)
125- `ar\_PS <https://faker.readthedocs.io/en/master/locales/ar_PS.html>`__ - Arabic (Palestine)
126- `ar\_SA <https://faker.readthedocs.io/en/master/locales/ar_SA.html>`__ - Arabic (Saudi Arabia)
127- `bg\_BG <https://faker.readthedocs.io/en/master/locales/bg_BG.html>`__ - Bulgarian
128- `cs\_CZ <https://faker.readthedocs.io/en/master/locales/cs_CZ.html>`__ - Czech
129- `de\_DE <https://faker.readthedocs.io/en/master/locales/de_DE.html>`__ - German
130- `dk\_DK <https://faker.readthedocs.io/en/master/locales/dk_DK.html>`__ - Danish
131- `el\_GR <https://faker.readthedocs.io/en/master/locales/el_GR.html>`__ - Greek
132- `en\_AU <https://faker.readthedocs.io/en/master/locales/en_AU.html>`__ - English (Australia)
133- `en\_CA <https://faker.readthedocs.io/en/master/locales/en_CA.html>`__ - English (Canada)
134- `en\_GB <https://faker.readthedocs.io/en/master/locales/en_GB.html>`__ - English (Great Britain)
135- `en\_US <https://faker.readthedocs.io/en/master/locales/en_US.html>`__ - English (United States)
136- `es\_ES <https://faker.readthedocs.io/en/master/locales/es_ES.html>`__ - Spanish (Spain)
137- `es\_MX <https://faker.readthedocs.io/en/master/locales/es_MX.html>`__ - Spanish (Mexico)
138- `et\_EE <https://faker.readthedocs.io/en/master/locales/et_EE.html>`__ - Estonian
139- `fa\_IR <https://faker.readthedocs.io/en/master/locales/fa_IR.html>`__ - Persian (Iran)
140- `fi\_FI <https://faker.readthedocs.io/en/master/locales/fi_FI.html>`__ - Finnish
141- `fr\_FR <https://faker.readthedocs.io/en/master/locales/fr_FR.html>`__ - French
142- `hi\_IN <https://faker.readthedocs.io/en/master/locales/hi_IN.html>`__ - Hindi
143- `hr\_HR <https://faker.readthedocs.io/en/master/locales/hr_HR.html>`__ - Croatian
144- `hu\_HU <https://faker.readthedocs.io/en/master/locales/hu_HU.html>`__ - Hungarian
145- `it\_IT <https://faker.readthedocs.io/en/master/locales/it_IT.html>`__ - Italian
146- `ja\_JP <https://faker.readthedocs.io/en/master/locales/ja_JP.html>`__ - Japanese
147- `ko\_KR <https://faker.readthedocs.io/en/master/locales/ko_KR.html>`__ - Korean
148- `lt\_LT <https://faker.readthedocs.io/en/master/locales/lt_LT.html>`__ - Lithuanian
149- `lv\_LV <https://faker.readthedocs.io/en/master/locales/lv_LV.html>`__ - Latvian
150- `ne\_NP <https://faker.readthedocs.io/en/master/locales/ne_NP.html>`__ - Nepali
151- `nl\_NL <https://faker.readthedocs.io/en/master/locales/nl_NL.html>`__ - Dutch (Netherlands)
152- `no\_NO <https://faker.readthedocs.io/en/master/locales/no_NO.html>`__ - Norwegian
153- `pl\_PL <https://faker.readthedocs.io/en/master/locales/pl_PL.html>`__ - Polish
154- `pt\_BR <https://faker.readthedocs.io/en/master/locales/pt_BR.html>`__ - Portuguese (Brazil)
155- `pt\_PT <https://faker.readthedocs.io/en/master/locales/pt_PT.html>`__ - Portuguese (Portugal)
156- `ro\_RO <https://faker.readthedocs.io/en/master/locales/ro_RO.html>`__ - Romanian
157- `ru\_RU <https://faker.readthedocs.io/en/master/locales/ru_RU.html>`__ - Russian
158- `sl\_SI <https://faker.readthedocs.io/en/master/locales/sl_SI.html>`__ - Slovene
159- `sv\_SE <https://faker.readthedocs.io/en/master/locales/sv_SE.html>`__ - Swedish
160- `tr\_TR <https://faker.readthedocs.io/en/master/locales/tr_TR.html>`__ - Turkish
161- `uk\_UA <https://faker.readthedocs.io/en/master/locales/uk_UA.html>`__ - Ukrainian
162- `zh\_CN <https://faker.readthedocs.io/en/master/locales/zh_CN.html>`__ - Chinese (China)
163- `zh\_TW <https://faker.readthedocs.io/en/master/locales/zh_TW.html>`__ - Chinese (Taiwan)
164- `ka\_GE <https://faker.readthedocs.io/en/master/locales/ka_GE.html>`__ - Georgian (Georgia)
165
166Command line usage
167------------------
168
169When installed, you can invoke faker from the command-line:
170
171.. code:: bash
172
173 faker [-h] [--version] [-o output]
174 [-l {bg_BG,cs_CZ,...,zh_CN,zh_TW}]
175 [-r REPEAT] [-s SEP]
176 [-i {package.containing.custom_provider otherpkg.containing.custom_provider}]
177 [fake] [fake argument [fake argument ...]]
178
179Where:
180
181- ``faker``: is the script when installed in your environment, in
182 development you could use ``python -m faker`` instead
183
184- ``-h``, ``--help``: shows a help message
185
186- ``--version``: shows the program's version number
187
188- ``-o FILENAME``: redirects the output to the specified filename
189
190- ``-l {bg_BG,cs_CZ,...,zh_CN,zh_TW}``: allows use of a localized
191 provider
192
193- ``-r REPEAT``: will generate a specified number of outputs
194
195- ``-s SEP``: will generate the specified separator after each
196 generated output
197
198- ``-i {my.custom_provider other.custom_provider}`` list of additional custom providers to use.
199 Note that is the import path of the package containing your Provider class, not the custom Provider class itself.
200
201- ``fake``: is the name of the fake to generate an output for, such as
202 ``name``, ``address``, or ``text``
203
204- ``[fake argument ...]``: optional arguments to pass to the fake (e.g. the profile fake takes an optional list of comma separated field names as the first argument)
205
206Examples:
207
208.. code:: bash
209
210 $ faker address
211 968 Bahringer Garden Apt. 722
212 Kristinaland, NJ 09890
213
214 $ faker -l de_DE address
215 Samira-Niemeier-Allee 56
216 94812 Biedenkopf
217
218 $ faker profile ssn,birthdate
219 {'ssn': u'628-10-1085', 'birthdate': '2008-03-29'}
220
221 $ faker -r=3 -s=";" name
222 Willam Kertzmann;
223 Josiah Maggio;
224 Gayla Schmitt;
225
226How to create a Provider
227------------------------
228
229.. code:: python
230
231 from faker import Faker
232 fake = Faker()
233
234 # first, import a similar Provider or use the default one
235 from faker.providers import BaseProvider
236
237 # create new provider class
238 class MyProvider(BaseProvider):
239 def foo(self):
240 return 'bar'
241
242 # then add new provider to faker instance
243 fake.add_provider(MyProvider)
244
245 # now you can use:
246 fake.foo()
247 > 'bar'
248
249How to customize the Lorem Provider
250-----------------------------------
251
252You can provide your own sets of words if you don't want to use the
253default lorem ipsum one. The following example shows how to do it with a list of words picked from `cakeipsum <http://www.cupcakeipsum.com/>`__ :
254
255.. code:: python
256
257 from faker import Faker
258 fake = Faker()
259
260 my_word_list = [
261 'danish','cheesecake','sugar',
262 'Lollipop','wafer','Gummies',
263 'sesame','Jelly','beans',
264 'pie','bar','Ice','oat' ]
265
266 fake.sentence()
267 #'Expedita at beatae voluptatibus nulla omnis.'
268
269 fake.sentence(ext_word_list=my_word_list)
270 # 'Oat beans oat Lollipop bar cheesecake.'
271
272
273How to use with Factory Boy
274---------------------------
275
276`Factory Boy` already ships with integration with ``Faker``. Simply use the
277``factory.Faker`` method of ``factory_boy``:
278
279.. code:: python
280
281 import factory
282 from myapp.models import Book
283
284 class BookFactory(factory.Factory):
285 class Meta:
286 model = Book
287
288 title = factory.Faker('sentence', nb_words=4)
289 author_name = factory.Faker('name')
290
291Accessing the `random` instance
292-------------------------------
293
294The ``.random`` property on the generator returns the instance of ``random.Random``
295used to generate the values:
296
297.. code:: python
298
299 from faker import Faker
300 fake = Faker()
301 fake.random
302 fake.random.getstate()
303
304By default all generators share the same instance of ``random.Random``, which
305can be accessed with ``from faker.generator import random``. Using this may
306be useful for plugins that want to affect all faker instances.
307
308Seeding the Generator
309---------------------
310
311When using Faker for unit testing, you will often want to generate the same
312data set. For convenience, the generator also provide a ``seed()`` method, which
313seeds the shared random number generator. Calling the same methods with the
314same version of faker and seed produces the same results.
315
316.. code:: python
317
318 from faker import Faker
319 fake = Faker()
320 fake.seed(4321)
321
322 print(fake.name())
323 > Margaret Boehm
324
325Each generator can also be switched to its own instance of ``random.Random``,
326separate to the shared one, by using the ``seed_instance()`` method, which acts
327the same way. For example:
328
329.. code-block:: python
330
331 from faker import Faker
332 fake = Faker()
333 fake.seed_instance(4321)
334
335 print(fake.name())
336 > Margaret Boehm
337
338Please note that as we keep updating datasets, results are not guaranteed to be
339consistent across patch versions. If you hardcode results in your test, make sure
340you pinned the version of ``Faker`` down to the patch number.
341
342Tests
343-----
344
345Installing dependencies:
346
347.. code:: bash
348
349 $ pip install -r tests/requirements.txt
350
351Run tests:
352
353.. code:: bash
354
355 $ python setup.py test
356
357or
358
359.. code:: bash
360
361 $ python -m unittest -v tests
362
363Write documentation for providers:
364
365.. code:: bash
366
367 $ python -m faker > docs.txt
368
369
370Contribute
371----------
372
373Please see `CONTRIBUTING`_.
374
375License
376-------
377
378Faker is released under the MIT License. See the bundled `LICENSE`_ file for details.
379
380Credits
381-------
382
383- `FZaninotto`_ / `PHP Faker`_
384- `Distribute`_
385- `Buildout`_
386- `modern-package-template`_
387
388
389.. _FZaninotto: https://github.com/fzaninotto
390.. _PHP Faker: https://github.com/fzaninotto/Faker
391.. _Perl Faker: http://search.cpan.org/~jasonk/Data-Faker-0.07/
392.. _Ruby Faker: https://github.com/stympy/faker
393.. _Distribute: https://pypi.org/project/distribute/
394.. _Buildout: http://www.buildout.org/
395.. _modern-package-template: https://pypi.org/project/modern-package-template/
396.. _extended docs: https://faker.readthedocs.io/en/latest/
397.. _bundled providers: https://faker.readthedocs.io/en/latest/providers.html
398.. _community providers: https://faker.readthedocs.io/en/latest/communityproviders.html
399.. _LICENSE: https://github.com/joke2k/faker/blob/master/LICENSE.txt
400.. _CONTRIBUTING: https://github.com/joke2k/faker/blob/master/CONTRIBUTING.rst
401.. _Factory Boy: https://github.com/FactoryBoy/factory_boy
402
403.. |pypi| image:: https://img.shields.io/pypi/v/Faker.svg?style=flat-square&label=version
404 :target: https://pypi.org/project/Faker/
405 :alt: Latest version released on PyPi
406
407.. |coverage| image:: https://img.shields.io/coveralls/joke2k/faker/master.svg?style=flat-square
408 :target: https://coveralls.io/r/joke2k/faker?branch=master
409 :alt: Test coverage
410
411.. |unix_build| image:: https://img.shields.io/travis/joke2k/faker/master.svg?style=flat-square&label=unix%20build
412 :target: http://travis-ci.org/joke2k/faker
413 :alt: Build status of the master branch on Mac/Linux
414
415.. |windows_build| image:: https://img.shields.io/appveyor/ci/joke2k/faker/master.svg?style=flat-square&label=windows%20build
416 :target: https://ci.appveyor.com/project/joke2k/faker
417 :alt: Build status of the master branch on Windows
418
419.. |license| image:: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square
420 :target: https://raw.githubusercontent.com/joke2k/faker/master/LICENSE.txt
421 :alt: Package license
422