# Recipes

## Imports and initialization

```python
from fake import FAKER
```

---

## Providers

### first_name

Returns a random first name.

```python
from fake import FAKER

FAKER.first_name()
```

---

### last_name

Returns a random last name.

```python
from fake import FAKER

FAKER.last_name()
```

---

### name

Returns a random full name.

```python
from fake import FAKER

FAKER.name()
```

---

### word

Returns a random word.

```python
from fake import FAKER

FAKER.word()
```

---

### words

Returns a list of `nb` (number) random words.

```python
from fake import FAKER

FAKER.words()
```

Arguments:

- `nb` (type: `int`, default value: `5`) is an optional argument.

Example with arguments (returns a list of 10 words):

```python
from fake import FAKER

FAKER.words(nb=10)
```

---

### sentence

Returns a random sentence with `nb_words` number of words.

```python
from fake import FAKER

FAKER.sentence()
```

Arguments:

- `nb_words` (type: `int`, default value: `5`) is an optional argument.

Example with arguments (returns a sentence of 10 words):

```python
from fake import FAKER

FAKER.sentence(nb_words=10)
```

---

### sentences

Returns a list of `nb` (number) random sentences.

```python
from fake import FAKER

FAKER.sentences()
```

Arguments:

- `nb` (type: `int`, default value: `3`) is an optional argument.

Example with arguments (returns a list of 10 sentences):

```python
from fake import FAKER

FAKER.sentences(nb=10)
```

---

### paragraph

Returns a random paragraph with `nb_sentences` number of sentences.

```python
from fake import FAKER

FAKER.paragraph()
```

Arguments:

- `nb_sentences` (type: `int`, default value: `5`) is an optional
  argument.

Example with arguments (returns a paragraph of 10 sentences):

```python
from fake import FAKER

FAKER.paragraph(nb_sentences=10)
```

---

### paragraphs

Returns a list of `nb` (number) random paragraphs.

```python
from fake import FAKER

FAKER.paragraphs()
```

Arguments:

- `nb` (type: `int`, default value: `3`) is an optional argument.

Example with arguments (returns a list of 10 paragraphs):

```python
from fake import FAKER

FAKER.paragraphs(nb=10)
```

---

### text

Returns random text with up to `nb_chars` characters.

```python
from fake import FAKER

FAKER.text()
```

Arguments:

- `nb_chars` (type: `int`, default value: `200`) is an optional argument.

Example with arguments (returns a 1000 character long text):

```python
from fake import FAKER

FAKER.text(nb_chars=1_000)
```

---

### texts

Returns a list of `nb` (number) random texts.

```python
from fake import FAKER

FAKER.texts()
```

Arguments:

- `nb` (type: `int`, default value: `3`) is an optional argument.

Example with arguments (returns a list of 10 texts):

```python
from fake import FAKER

FAKER.texts(nb=10)
```

---

### file_name

Returns a random file name with the given extension.

```python
from fake import FAKER

FAKER.file_name()
```

Arguments:

- `extension` (type: `str`, default value: `txt`) is an optional
  argument.
- `prefix` (type: `str`, default value: `""`) is an optional
  argument.

Example with arguments (returns a filename with “png” extension):

```python
from fake import FAKER

FAKER.file_name(extension="png")
```

---

### file_path

Returns a random file path with the given extension.

```python
from fake import FAKER

FAKER.file_path()
```

Arguments:

- `extension` (type: `str`, default value: `txt`) is an optional
  argument.
- `prefix` (type: `str`, default value: `""`) is an optional
  argument.

Example with arguments (returns a file path with “png” extension):

```python
from fake import FAKER

FAKER.file_path(extension="png")
```

---

### dir_path

Returns a random directory path.

```python
from fake import FAKER

FAKER.dir_path()
```

Arguments:

- `depth` (type: `int`, default value: `1`) is an optional
  argument.

Example with arguments (returns a directory path):

```python
from fake import FAKER

FAKER.dir_path(depth=3)
```

---

### file_extension

Returns a random file extension.

```python
from fake import FAKER

FAKER.file_extension()
```

---

### tld

Returns a TLD (top-level domain name).

```python
from fake import FAKER

FAKER.tld()
```

Arguments:

- `tlds` (type: `Optional[Tuple[str, ...]]`, default value: `None`) is
  an optional argument.

Example with arguments (returns either “com”, “net” or “org” TLD):

```python
from fake import FAKER

FAKER.tld(tlds=("com", "net", "org"))
```

---

### domain_name

Returns a domain name.

```python
from fake import FAKER

FAKER.domain_name()
```

Arguments:

- `tlds` (type: `Optional[Tuple[str, ...]]`, default value: `None`) is
  an optional argument.

Example with arguments (returns an domain name with either “com”, “net” or
“org” TLD):

```python
from fake import FAKER

FAKER.domain_name(tlds=("com", "net", "org"))
```

---

### free_email_domain

Returns a free e-mail domain name.

```python
from fake import FAKER

FAKER.free_email_domain()
```

---

### email

Returns a random e-mail address.

```python
from fake import FAKER

FAKER.email()
```

Arguments:

- `domain_names` (type: `Optional[Tuple[str, ...]]`, default
  value: `None`) is an optional argument.

Example with arguments (returns an e-mail address with either “gmail.com”
or “proton.me” domain):

```python
from fake import FAKER

FAKER.email(domain_names=("gmail.com", "proton.me"))
```

---

### company_email

Returns a random company e-mail address.

```python
from fake import FAKER

FAKER.company_email()
```

Arguments:

- `domain_names` (type: `Optional[Tuple[str, ...]]`, default
  value: `None`) is an optional argument.

Example with arguments (returns an e-mail address with either “microsoft.com”
or “google.com” domain):

```python
from fake import FAKER

FAKER.email(domain_names=("microsoft.com", "google.com"))
```

---

### free_email

Returns a random free e-mail address.

```python
from fake import FAKER

FAKER.free_email()
```

Arguments:

- `domain_names` (type: `Optional[Tuple[str, ...]]`, default
  value: `None`) is an optional argument.

Example with arguments (returns an e-mail with either “gmail.com”
or “proton.me” domain):

```python
from fake import FAKER

FAKER.email(domain_names=("gmail.com", "proton.me"))
```

---

### url

Returns a random URL.

```python
from fake import FAKER

FAKER.url()
```

Arguments:

- `protocols` (type: `Optional[Tuple[str]]`, default value: `None`) is
  an optional argument.
- `tlds` (type: `Optional[Tuple[str]]`, default value: `None`) is
  an optional argument.
- `suffixes` (type: `Optional[Tuple[str]]`, default value: `None`) is
  an optional argument.

---

### image_url

Returns a valid random image URL.

```python
from fake import FAKER

FAKER.image_url()
```

Arguments:

- `width` (type: `int`, default value: `800`) is
  a required argument.
- `height` (type: `int`, default value: `600`) is
  an required argument.
- `service_url` (type: `Optional[str]`, default value: `None`) is
  an optional argument.

Example with arguments (alternative dimensions):

```python
from fake import FAKER

FAKER.image_url(width=640, height=480)
```

---

### pyint

Returns a random integer between `min_value` and `max_value`.

```python
from fake import FAKER

FAKER.pyint()
```

Arguments:

- `min_value` (type: `int`, default value: `0`) is an optional argument.
- `max_value` (type: `int`, default value: `9999`) is an optional
  argument.

Example with arguments (returns an integer between 0 and 100):

```python
from fake import FAKER

FAKER.pyint(min_value=0, max_value=100)
```

---

### pybool

Returns a random boolean value.

```python
from fake import FAKER

FAKER.pybool()
```

---

### pystr

Returns a random string of `nb_chars` length.

```python
from fake import FAKER

FAKER.pystr()
```

Arguments:

- `nb_chars` (type: `int`, default value: `20`) is an optional argument.

Example with arguments (returns a string of 64 characters):

```python
from fake import FAKER

FAKER.pystr(nb_chars=64)
```

---

### pyfloat

Returns a random float between `min_value` and `max_value`.

```python
from fake import FAKER

FAKER.pyfloat()
```

Arguments:

- `min_value` (type: `float`, default value: `0.0`) is an optional
  argument.
- `max_value` (type: `float`, default value: `10.00`) is an optional
  argument.

Example with arguments (returns a float between 0 and 100):

```python
from fake import FAKER

FAKER.pyfloat(min_value=0.0, max_value=100.0)
```

---

### pydecimal

Returns a random decimal, according to given `left_digits` and
`right_digits`.

```python
from fake import FAKER

FAKER.pydecimal()
```

Arguments:

- `left_digits` (type: `int`, default value: `5`) is an optional
  argument.
- `right_digits` (type: `int`, default value: `2`) is an optional
  argument.
- `positive` (type: `bool`, default value: `True`) is an optional
  argument.

Example with arguments:

```python
from fake import FAKER

FAKER.pydecimal(left_digits=1, right_digits=4, positive=False)
```

---

### ipv4

Returns a random IPv4 address.

```python
from fake import FAKER

FAKER.ipv4()
```

---

### date

Generates a random date.

Both `start_date` and `end_date` support:

1. **ISO format dates**:
   - `'YYYY-MM-DD'` (e.g., `'2000-01-01'`)
   - `'YYYY-MM-DD HH:MM:SS'` (e.g., `'2000-01-01 12:00:00'`)
2. **Relative shorthand notation**: `[+/-][number][unit]`

   Units:
   - `d`  days
   - `h`  hours
   - `m`  minutes
   - `w`  weeks
   - `mo` months
   - `y`  years

   Sign: `+` for future, `-` for past, or omit `+` for future

   Special: `'now'`, `'today'` for current datetime

Shorthand notation examples:

- `'-7d'`: 7 days ago
- `'+3d'` or `'3d'`: 3 days from now
- `'-2w'`: 2 weeks ago
- `'+1mo'`: 1 month from now
- `'-1y'`: 1 year ago
- `'-24h'`: 24 hours ago
- `'+2h'`: 2 hours from now
- `'-30m'`: 30 minutes ago
- `'today'` or `'now'`: current datetime

ISO format examples:

- `'2000-01-01'`: January 1, 2000
- `'2025-12-31'`: December 31, 2025
- `'2000-01-01 00:00:00'`: with time component

```python
from fake import FAKER

FAKER.date()
```

Usage examples:

```python
from fake import FAKER

FAKER.date()  # random date between 7 days ago and now
FAKER.date('-7d', '+0d')  # same as above (explicit)
FAKER.date('-24h', '+0h')  # in the past 24 hours
FAKER.date('-30m', '+30m')  # within 1-hour window around now
FAKER.date('-2w', '+1w')  # within 3-week window
FAKER.date('-3mo', '+6mo')  # within 9-month window
FAKER.date('-1y', '+1y')  # within 1 year window
```

---

### date_time

Generates a random datetime.

Both `start_date` and `end_date` support:

1. **ISO format dates**:
   - `'YYYY-MM-DD'` (e.g., `'2000-01-01'`)
   - `'YYYY-MM-DD HH:MM:SS'` (e.g., `'2000-01-01 12:00:00'`)
2. **Relative shorthand notation**: `[+/-][number][unit]`

   Units:
   - `d`  days
   - `h`  hours
   - `m`  minutes
   - `w`  weeks
   - `mo` months
   - `y`  years

   Sign: `+` for future, `-` for past, or omit `+` for future

   Special: `'now'`, `'today'` for current datetime

Shorthand notation examples:

- `'-7d'`: 7 days ago
- `'+3d'` or `'3d'`: 3 days from now
- `'-2w'`: 2 weeks ago
- `'+1mo'`: 1 month from now
- `'-1y'`: 1 year ago
- `'-24h'`: 24 hours ago
- `'+2h'`: 2 hours from now
- `'-30m'`: 30 minutes ago
- `'today'` or `'now'`: current datetime

ISO format examples:

- `'2000-01-01'`: January 1, 2000
- `'2025-12-31 23:59:59'`: with time component

Usage examples:

```python
from fake import FAKER

FAKER.date_time()  # random datetime between 7 days ago and now
FAKER.date_time('-7d', '+0d')  # same as above (explicit)
FAKER.date_time('-24h', '+0h')  # in the past 24 hours
FAKER.date_time('-30m', '+30m')  # within 1-hour window around now
FAKER.date_time('-2w', '+1w')  # within 3-week window
FAKER.date_time('-3mo', '+6mo')  # within 9-month window
FAKER.date_time('-1y', '+1y')  # within 1 year window
```

---

### pdf

Generates a content (`bytes`) of a PDF document.

```python
from fake import FAKER

FAKER.pdf()
```

Arguments:

- `nb_pages` (type: `int`, default value: `1`) is an optional argument.
- `texts` (type: `list[str]`, default value: `None`) is an optional
  argument.
- `generator`
  (type: `Union[Type[TextPdfGenerator], Type[GraphicPdfGenerator]]`,
  default value: `GraphicPdfGenerator`) is an optional argument.
- `metadata` (type: `MetaData`, default value: `None`) is an optional
  argument.

#### NOTE
`texts` is valid only in case `TextPdfGenerator` is used.

#### NOTE
Either `nb_pages` or `texts` shall be provided. `nb_pages` is by
default set to `1`, but if `texts` is given, the value of `nb_pages`
is adjusted accordingly.

Examples with arguments.

Generate a content (`bytes`) of a PDF document of 100 pages with random
graphics:

```python
from fake import FAKER

FAKER.pdf(nb_pages=100)
```

Generate a content (`bytes`) of a PDF document of 100 pages with random
texts:

```python
from fake import FAKER
from fake import TextPdfGenerator

FAKER.pdf(nb_pages=100, generator=TextPdfGenerator)
```

If you want to get insights of the content used to generate the PDF (texts),
pass the `metadata` argument.

```python
from fake import FAKER
from fake import MetaData, TextPdfGenerator

metadata = MetaData()
FAKER.pdf(nb_pages=100, generator=TextPdfGenerator, metadata=metadata)

print(metadata.content)  # Inspect ``metadata``
```

---

### image

Generates a content (`bytes`) of an image of the specified format and colour.

```python
from fake import FAKER

FAKER.image()  # Supported formats are `png`, `svg`, `bmp` and `gif`
```

Arguments:

- `image_format` (type: `str`, default value: `png`) is an optional
  argument.
- `size` (type: `Tuple[int, int]`, default value: `(100, 100)`) is an
  optional argument.
- `color` (type: `Tuple[int, int, int]`, default value: `(0, 0, 255)`)
  is an optional argument.

Example with arguments.

```python
from fake import FAKER

FAKER.image(
    image_format="svg",  # SVG format
    size=(640, 480),  # 640px width, 480px height
    color=(0, 0, 0),  # Fill rectangle with black
)
```

---

### docx

Generates a content (`bytes`) of a DOCX document.

```python
from fake import FAKER

FAKER.docx()
```

Arguments:

- `nb_pages` (type: `int`, default value: `1`) is an optional argument.
- `texts` (type: `list[str]`, default value: `None`) is an optional
  argument.

#### NOTE
Either `nb_pages` or `texts` shall be provided. `nb_pages` is by
default set to `1`, but if `texts` is given, the value of `nb_pages`
is adjusted accordingly.

Examples with arguments.

Generate a content (`bytes`) of a DOCX document of 100 pages with random
texts:

```python
from fake import FAKER

FAKER.docx(nb_pages=100)
```

If you want to get insights of the content used to generate the DOCX (texts),
pass the `metadata` argument.

```python
from fake import FAKER
from fake import MetaData

metadata = MetaData()
FAKER.docx(nb_pages=100, metadata=metadata)

print(metadata.content)  # Inspect ``metadata``
```

---

### odt

Generates a content (`bytes`) of a ODT document.

```python
from fake import FAKER

FAKER.odt()
```

Arguments:

- `nb_pages` (type: `int`, default value: `1`) is an optional argument.
- `texts` (type: `list[str]`, default value: `None`) is an optional
  argument.

#### NOTE
Either `nb_pages` or `texts` shall be provided. `nb_pages` is by
default set to `1`, but if `texts` is given, the value of `nb_pages`
is adjusted accordingly.

Examples with arguments.

Generate a content (`bytes`) of a ODT document of 100 pages with random
texts:

```python
from fake import FAKER

FAKER.odt(nb_pages=100)
```

If you want to get insights of the content used to generate the ODT (texts),
pass the `metadata` argument.

```python
from fake import FAKER
from fake import MetaData

metadata = MetaData()
FAKER.odt(nb_pages=100, metadata=metadata)

print(metadata.content)  # Inspect ``metadata``
```

---

### bin

Generates a content (`bytes`) of a BIN document.

```python
from fake import FAKER

FAKER.bin()
```

Arguments:

- `length` (type: `int`, default value: `16`) is a required argument.

Examples with arguments.

Generate a content (`bytes`) of a BIN document of length 100:

```python
from fake import FAKER

FAKER.bin(length=100)
```

---

### zip

Generates a content (`bytes`) of a ZIP document.

```python
from fake import FAKER

FAKER.zip()
```

Arguments:

- `options` (type: `Dict`, default value: `None`) is an optional
  argument.

---

### eml

Generates a content (`bytes`) of a EML document.

```python
from fake import FAKER

FAKER.eml()
```

Arguments:

- `options` (type: `Dict`, default value: `None`) is an optional
  argument.
- `content` (type: `str`, default value: `None`) is an optional
  argument.
- `subject` (type: `str`, default value: `None`) is an optional
  argument.

---

### tar

Generates a content (`bytes`) of a TAR document.

```python
from fake import FAKER

FAKER.tar()
```

Arguments:

- `options` (type: `Dict`, default value: `None`) is an optional
  argument.

---

### pdf_file

Generates a `PDF` file.

```python
from fake import FAKER

FAKER.pdf_file()
```

Arguments:

#### NOTE
Accepts all arguments of `pdf` + the following:

- `storage` (type: `BaseStorage`, default value: `None`) is an optional
  argument.
- `basename` (type: `str`, default value: `None`) is an optional
  argument.
- `prefix` (type: `str`, default value: `None`) is an optional argument.

Examples with arguments.

Generate a PDF document of 100 pages with random graphics:

```python
from fake import FAKER

FAKER.pdf_file(nb_pages=100)
```

Generate a PDF document of 100 pages with random texts:

```python
from fake import FAKER
from fake import TextPdfGenerator

FAKER.pdf_file(nb_pages=100, generator=TextPdfGenerator)
```

If you want to get insights of the content used to generate the PDF (texts),
pass the `metadata` argument.

```python
from fake import FAKER
from fake import MetaData, TextPdfGenerator

metadata = MetaData()
FAKER.pdf_file(nb_pages=100, generator=TextPdfGenerator, metadata=metadata)

print(metadata.content)  # Inspect ``metadata``
```

---

### png_file

Generates a `PNG` file.

```python
from fake import FAKER

FAKER.png_file()
```

Arguments:

#### NOTE
Accepts all arguments of `png` + the following:

- `storage` (type: `BaseStorage`, default value: `None`) is an optional
  argument.
- `basename` (type: `str`, default value: `None`) is an optional
  argument.
- `prefix` (type: `str`, default value: `None`) is an optional argument.

Example with arguments.

```python
from fake import FAKER

FAKER.png_file(
    basename="png_file",  # Basename
    size=(640, 480),  # 640px width, 480px height
    color=(0, 0, 0),  # Fill rectangle with black
)
```

---

### svg_file

Generates an `SVG` file.

```python
from fake import FAKER

FAKER.svg_file()
```

Arguments:

#### NOTE
Accepts all arguments of `svg` + the following:

- `storage` (type: `BaseStorage`, default value: `None`) is an optional
  argument.
- `basename` (type: `str`, default value: `None`) is an optional
  argument.
- `prefix` (type: `str`, default value: `None`) is an optional argument.

Example with arguments.

```python
from fake import FAKER

FAKER.svg_file(
    basename="svg_file",  # Basename
    size=(640, 480),  # 640px width, 480px height
    color=(0, 0, 0),  # Fill rectangle with black
)
```

---

### bmp_file

Generates a `BMP` file.

```python
from fake import FAKER

FAKER.bmp_file()
```

Arguments:

#### NOTE
Accepts all arguments of `bmp` + the following:

- `storage` (type: `BaseStorage`, default value: `None`) is an optional
  argument.
- `basename` (type: `str`, default value: `None`) is an optional
  argument.
- `prefix` (type: `str`, default value: `None`) is an optional argument.

Example with arguments.

```python
from fake import FAKER

FAKER.bmp_file(
    basename="bmp_file",  # Basename
    size=(640, 480),  # 640px width, 480px height
    color=(0, 0, 0),  # Fill rectangle with black
)
```

---

### gif_file

Generates a `GIF` file.

```python
from fake import FAKER

FAKER.gif_file()
```

Arguments:

#### NOTE
Accepts all arguments of `gif` + the following:

- `storage` (type: `BaseStorage`, default value: `None`) is an optional
  argument.
- `basename` (type: `str`, default value: `None`) is an optional
  argument.
- `prefix` (type: `str`, default value: `None`) is an optional argument.

Example with arguments.

```python
from fake import FAKER

FAKER.gif_file(
    basename="gif_file",  # Basename
    size=(640, 480),  # 640px width, 480px height
    color=(0, 0, 0),  # Fill rectangle with black
)
```

---

### txt_file

Generates a `TXT` file.

```python
from fake import FAKER

FAKER.txt_file()
```

Arguments:

#### NOTE
Accepts all arguments of `text` + the following:

- `storage` (type: `BaseStorage`, default value: `None`) is an optional
  argument.
- `basename` (type: `str`, default value: `None`) is an optional
  argument.
- `prefix` (type: `str`, default value: `None`) is an optional argument.

Example with arguments.

```python
from fake import FAKER

FAKER.txt_file(
    basename="txt_file",  # Basename
    nb_chars=10_000,  # 10_000 characters long
)
```

---

### city

Get a random city.

```python
from fake import FAKER

FAKER.city()
```

---

### country

Get a random country.

```python
from fake import FAKER

FAKER.country()
```

---

### geo_location

Get a random geo-location.

```python
from fake import FAKER

FAKER.geo_location()
```

---

### country_code

Get a random country code.

```python
from fake import FAKER

FAKER.country_code()
```

---

### locale

Generate a random locale.

```python
from fake import FAKER

FAKER.locale()
```

---

### latitude

Generate a random latitude.

```python
from fake import FAKER

FAKER.latitude()
```

---

### longitude

Generate a random longitude.

```python
from fake import FAKER

FAKER.longitude()
```

---

### latitude_longitude

Generate a random (latitude, longitude) pair.

```python
from fake import FAKER

FAKER.latitude_longitude()
```

---

### isbn10

Generate a random ISBN10. Can be validated using [isbn-checker](https://isbn-checker.netlify.app/).

```python
from fake import FAKER

FAKER.isbn10()
```

---

### isbn13

Generate a random ISBN13. Can be validated using [isbn-checker](https://isbn-checker.netlify.app/).

```python
from fake import FAKER

FAKER.isbn13()
```

---

### iban

Generate a random IBAN. Can be validated using [iban-calculator](https://www.ibancalculator.com/iban_validieren.html).

```python
from fake import FAKER

FAKER.iban()
```

---

### random_choice

Picks a random element from the sequence given.

```python
from fake import FAKER

FAKER.random_choice(("Art", "Photography", "Generative AI"))
```

---

### random_sample

Picks a given number of random elements from the sequence given.

```python
from fake import FAKER

FAKER.random_sample(("Art", "Photography", "Generative AI"), 2)
```

---

### randomise_string

Replaces placeholders in a given string with random letters and digits.

- Placeholders `?` are replaced by random uppercase letters.
- Placeholders `#` are replaced by random digits.

```python
from fake import FAKER

FAKER.randomise_string("???? ##")
```

---

Optional arguments:

- `letters` (type: `str`, default value: `string.ascii_uppercase`).
- `digits` (type: `str`, default value: `string.digits`).

Example with arguments.

```python
import string
from fake import FAKER

FAKER.randomise_string(
    "???? ##",
    letters=string.ascii_letters,  # Use both upper- and lower-case
    digits="123456789",  # Exclude 0
)
```

Sample output:

```text
1234 Aa
```

---