### Example Docstring Structure with :sample:

Source: https://faker.readthedocs.io/en/stable/_sources/writing-docs.rst.txt

Illustrates a typical docstring structure for a Faker provider, showing the placement of summary, detailed description, and :examples: sections. The :sample: directive is used to generate testable code examples.

```python
   # Resulting docstring (more or less) after preprocessing
   def foo():
       """Summary line

       Lorem ipsum dolor sit amet, consectetur adipiscing elit.
       Fusce auctor faucibus condimentum.


       Duis posuere lacinia porta.
       Quisque mauris nisl, mattis sed ornare eget, accumsan sit amet mauris.

       :examples:

       >>> Faker.seed(0)
       >>> for _ in range(5):
       ...     fake.foo()
       ...
       1
       1
       1
       1
       1

       >>> Faker.seed(1000)
       >>> for _ in range(10):
       ...     fake.foo()
       ...
       1
       1
       1
       1
       1
       1
       1
       1
       1
       1
       """
       pass
```

--------------------------------

### Install Faker

Source: https://faker.readthedocs.io/en/stable/index.html

Install the Faker package using pip. This is the first step to using Faker in your Python project.

```bash
pip install Faker
```

--------------------------------

### Docstring Preprocessing Example

Source: https://faker.readthedocs.io/en/stable/_sources/writing-docs.rst.txt

This snippet shows a typical Python docstring structure that includes the ':sample:' directive, which will be processed by Sphinx to generate an ':examples:' section.

```python
# Source code docstring
def foo():
    """Summary line

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Fusce auctor faucibus condimentum.

    :sample:

    Duis posuere lacinia porta.
    Quisque mauris nisl, mattis sed ornare eget, accumsan sit amet mauris.
    
```

--------------------------------

### Example docstring with multiple :sample: lines

Source: https://faker.readthedocs.io/en/stable/writing-docs.html

This Python docstring contains multiple ':sample:' lines, demonstrating how the system handles them during preprocessing.

```python
def foo():
    """Summary line

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Fusce auctor faucibus condimentum.

    :sample:

    Duis posuere lacinia porta.
    Quisque mauris nisl, mattis sed ornare eget, accumsan sit amet mauris.

    :sample size=10 seed=1000:
    """
    return 1

```

--------------------------------

### Generate Hostnames with Levels

Source: https://faker.readthedocs.io/en/stable/locales/cs_CZ.html

Produces a hostname with a specified number of subdomain levels. Examples show default, zero, and multi-level usage.

```python
>>> hostname()
db-01.nichols-phillips.com
>>> hostname(0)
laptop-56
>>> hostname(2)
web-12.williamson-hopkins.jackson.com
```

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.hostname()
...
'web-66.pospisil.com'
'laptop-47.mala.cz'
'desktop-21.pokorny.cz'
'email-92.horak.cz'
'desktop-78.urban.com'
```

--------------------------------

### past_datetime

Source: https://faker.readthedocs.io/en/stable/locales/id_ID.html

Get a datetime object based on a random date between a given date and 1 second ago. Supports specifying a start date and timezone.

```APIDOC
## past_datetime

### Description
Get a datetime object based on a random date between a given date and 1 second ago.

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Parameters
* **start_date** (DateParseType) - Optional - Defaults to `"-30d"`. A `DateParseType`.
* **tzinfo** (tzinfo | None) - Optional - timezone, instance of datetime.tzinfo subclass

### Request Example
```python
# No request example available in source
```

### Response
#### Success Response
* **datetime** (datetime) - A datetime object.

#### Response Example
```json
{
  "example": "datetime.datetime(2026, 6, 6, 4, 53, 34, 594731)"
}
```
```

--------------------------------

### Customizing sample size and arguments with :sample:

Source: https://faker.readthedocs.io/en/stable/writing-docs.html

This shows how to specify the number of samples and pass keyword arguments to the provider method using the ':sample:' pseudo-role.

```rst
:sample size=10: a=1, b=2, c=3
```

--------------------------------

### past_date

Source: https://faker.readthedocs.io/en/stable/locales/id_ID.html

Get a Date object based on a random date between a given date and 1 day ago. Supports specifying a start date and timezone.

```APIDOC
## past_date

### Description
Get a Date object based on a random date between a given date and 1 day ago.

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Parameters
* **start_date** (DateParseType) - Optional - Defaults to `"-30d"`. A `DateParseType`.
* **tzinfo** (tzinfo | None) - Optional - timezone, instance of datetime.tzinfo subclass

### Request Example
```python
# No request example available in source
```

### Response
#### Success Response
* **date** (date) - A date object.

#### Response Example
```json
{
  "example": "datetime.date(2026, 6, 4)"
}
```
```

--------------------------------

### Generate EAN Barcode with Single Prefix

Source: https://faker.readthedocs.io/en/stable/providers/faker.providers.barcode.html

Generates an EAN barcode (default length 13) that starts with a specified prefix. This example uses '00' as the prefix.

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.ean(prefixes=('00', ))
...
```

--------------------------------

### Basic :sample: pseudo-role usage

Source: https://faker.readthedocs.io/en/stable/writing-docs.html

This demonstrates the basic syntax for the ':sample:' pseudo-role in a docstring. It will generate a default sample usage section.

```rst
:sample:
```

--------------------------------

### Generate Datetime Between Dates (Defaults)

Source: https://faker.readthedocs.io/en/stable/locales/cs_CZ.html

Generates a random datetime using default start and end dates. This example shows repeated calls with default parameters.

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.date_time_between_dates()
...
datetime.datetime(2026, 6, 10, 20, 53, 58)
datetime.datetime(2026, 6, 10, 20, 53, 58)
datetime.datetime(2026, 6, 10, 20, 53, 58)
datetime.datetime(2026, 6, 10, 20, 53, 58)
datetime.datetime(2026, 6, 10, 20, 53, 58)

```

--------------------------------

### Example Docstring with Sample Usage

Source: https://faker.readthedocs.io/en/stable/writing-docs.html

This docstring demonstrates the structure for including sample usage sections within a Python function's docstring. It shows how Faker's seeding and method calls are represented for documentation generation.

```python
def foo():
    """Summary line

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Fusce auctor faucibus condimentum.


    Duis posuere lacinia porta.
    Quisque mauris nisl, mattis sed ornare eget, accumsan sit amet mauris.

    :examples:

    >>> Faker.seed(0)
    >>> for _ in range(5):
    ...     fake.foo()
    ...
    1
    1
    1
    1
    1

    >>> Faker.seed(1000)
    >>> for _ in range(10):
    ...     fake.foo()
    ...
    1
    1
    1
    1
    1
    1
    1
    1
    1
    1
    """
    pass
```

--------------------------------

### Generate EAN-8 Barcode with Prefix (Direct Call)

Source: https://faker.readthedocs.io/en/stable/providers/faker.providers.barcode.html

Generates an EAN-8 barcode starting with a specified prefix using the `ean8` method. This example uses '00' as the prefix.

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.ean8(prefixes=('00', ))
...
```

--------------------------------

### CSV Output Example

Source: https://faker.readthedocs.io/en/stable/locales/fil_PH.html

Demonstrates generating CSV data using the `dsv` method with the 'excel' dialect and specific data columns for name and address. This is useful for creating mock CSV files.

```python
from faker import Faker

fake = Faker()
Faker.seed(0)
for _ in range(5):
    fake.dsv(dialect='excel', data_columns=('{{name}}', '{{address}}'))
```

--------------------------------

### Generate EAN-13 Barcode with Prefix (Direct Call)

Source: https://faker.readthedocs.io/en/stable/providers/faker.providers.barcode.html

Generates an EAN-13 barcode starting with a specified prefix using the `ean13` method. This example uses '00' as the prefix.

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.ean13(prefixes=('00', ))
...
```

--------------------------------

### Generate EAN Barcode with Multiple Prefixes

Source: https://faker.readthedocs.io/en/stable/providers/faker.providers.barcode.html

Generates an EAN barcode (default length 13) that starts with one of the specified prefixes. This example uses '45' or '49'.

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.ean(prefixes=('45', '49'))
...
```

--------------------------------

### Basic Sample Usage Generation

Source: https://faker.readthedocs.io/en/stable/_sources/writing-docs.rst.txt

This snippet demonstrates the basic usage of the ':sample:' pseudo-role to generate a default sample usage section. It calls the provider method 5 times with a default seed of 0.

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.method1()
...
# Output 1
# Output 2
# Output 3
# Output 4
# Output 5
```

--------------------------------

### Get Tagalog Word List

Source: https://faker.readthedocs.io/en/stable/locales/tl_PH.html

Generates a list of words using the locale's built-in word list. This example demonstrates repeated calls to retrieve the same list.

```python
from faker import Faker

fake = Faker()

Faker.seed(0)
for _ in range(5):
    fake.get_words_list(ext_word_list=['abc', 'def', 'ghi', 'jkl'])
```

--------------------------------

### Sample Usage Generation with Multi-line Arguments

Source: https://faker.readthedocs.io/en/stable/_sources/writing-docs.rst.txt

This snippet demonstrates how to format long keyword arguments across multiple lines within the ':sample:' directive for better readability in the docstring.

```text
:sample size=25 seed=12345: arg1='very long value, unfortunately',
                            arg2='yet another long value'
```

```python
>>> Faker.seed(12345)
>>> for _ in range(25):
...     fake.method1(arg1='very long value, unfortunately', arg2='yet another long value')
...
# Output 1
# Output 2
# ...
# Output 24
# Output 25
```

--------------------------------

### Generate Past Date

Source: https://faker.readthedocs.io/en/stable/locales/es.html

Get a Date object based on a random date between a given start date and 1 day ago. Defaults to 30 days ago.

```python
from faker import Faker
faker = Faker()

# Get a past date (default: from 30 days ago)
past_date_obj = faker.past_date()
print(past_date_obj)

# Get a past date starting from 1 year ago
past_date_obj_custom = faker.past_date(start_date='-1y')
print(past_date_obj_custom)
```

--------------------------------

### Create a Dynamic Faker Provider

Source: https://faker.readthedocs.io/en/stable/index.html

Shows how to create a dynamic provider that can read elements from an external source.

```python
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.'

```

--------------------------------

### Generate Provider Documentation for Default Locale

Source: https://faker.readthedocs.io/en/stable/index.html

Command to generate documentation for Faker providers in the default locale by running the module as a script.

```bash
$ python -m faker > docs.txt
```

--------------------------------

### Generate EAN-8 Barcode with Multiple Prefixes (Direct Call)

Source: https://faker.readthedocs.io/en/stable/providers/faker.providers.barcode.html

Generates an EAN-8 barcode starting with one of the specified prefixes using the `ean8` method. This example uses '45' or '49'.

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.ean8(prefixes=('45', '49'))
...
```

--------------------------------

### Provider.pyset()

Source: https://faker.readthedocs.io/en/stable/locales/en_US.html

Generates a fake Python set.

```APIDOC
## Provider.pyset()

### Description
Generates a fake Python set.

### Method
N/A (Method call)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response
- **pyset** (set) - A randomly generated Python set.
```

--------------------------------

### Generate EAN-13 Barcode with Multiple Prefixes (Direct Call)

Source: https://faker.readthedocs.io/en/stable/providers/faker.providers.barcode.html

Generates an EAN-13 barcode starting with one of the specified prefixes using the `ean13` method. This example uses '45' or '49'.

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.ean13(prefixes=('45', '49'))
...
```

--------------------------------

### Generate Datetimes Between Specified Date Range (Future Output)

Source: https://faker.readthedocs.io/en/stable/locales/uz_UZ.html

Example output of 5 datetime objects generated by `date_time_between_dates` with current date as start and one year from now as end, using seed 0.

```python
datetime.datetime(2027, 4, 15, 6, 55, 0, 441207)
datetime.datetime(2027, 3, 14, 16, 57, 49, 993625)
datetime.datetime(2026, 11, 11, 11, 32, 49, 345382)
datetime.datetime(2026, 9, 13, 10, 31, 10, 534973)
datetime.datetime(2026, 12, 14, 14, 37, 44, 405703)
```

--------------------------------

### Create a Custom Faker Provider

Source: https://faker.readthedocs.io/en/stable/index.html

Demonstrates how to create and add a custom provider to a Faker instance.

```python
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'

```

--------------------------------

### Generate Datetime Between Dates (Default)

Source: https://faker.readthedocs.io/en/stable/locales/ar_AA.html

Generates a random datetime using default start and end dates, which are the UNIX epoch and the current date/time respectively. This example shows the default behavior without explicit date parameters.

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.date_time_between_dates()
...
```

--------------------------------

### faker.providers.barcode.en_CA.Provider.ean13

Source: https://faker.readthedocs.io/en/stable/locales/en_CA.html

Generates an EAN-13 barcode. Allows control over whether the barcode starts with a zero, or can be forced to start with specific prefixes. Note that EAN-13 starting with zero can be converted to UPC-A.

```APIDOC
## `ean13`

### Description
Generate an EAN-13 barcode. If `leading_zero` is `True`, the leftmost digit of the barcode will be set to `0`. If `False`, the leftmost digit cannot be `0`. If `None` (default), the leftmost digit can be any digit. If a value for `prefixes` is specified, the result will begin with one of the sequences in `prefixes` and will ignore `leading_zero`. This method uses the standard barcode provider’s `ean13()` under the hood with the `prefixes` argument set to the correct value to attain the behavior described above.

### Method
`ean13(prefixes: Tuple[int | str | Tuple[int | str, ...], ...] = (), leading_zero: bool | None = None) -> str`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from faker import Faker

fake = Faker()

# Default EAN-13
print(fake.ean13())

# EAN-13 without leading zero
print(fake.ean13(leading_zero=False))

# EAN-13 with leading zero
print(fake.ean13(leading_zero=True))

# EAN-13 with prefixes
print(fake.ean13(prefixes=('00',)))
print(fake.ean13(prefixes=('45', '49')))
```

### Response
#### Success Response (200)
- **barcode** (str) - A generated EAN-13 barcode string.

#### Response Example
```json
{
  "barcode": "6604876475937"
}
```
```

--------------------------------

### Customize Faker's Lorem Provider

Source: https://faker.readthedocs.io/en/stable/index.html

Illustrates how to provide a custom list of words for the Lorem provider.

```python
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.'

```

--------------------------------

### Multi-line keyword arguments in :sample:

Source: https://faker.readthedocs.io/en/stable/writing-docs.html

This shows how to break long keyword arguments into multiple lines within the ':sample:' pseudo-role for better readability.

```rst
:sample size=25 seed=12345: arg1='very long value, unfortunately',
                            arg2='yet another long value'

```

--------------------------------

### Generate ASCII Safe Emails

Source: https://faker.readthedocs.io/en/stable/locales/bg_BG.html

Generates a list of ASCII email addresses using the 'example.com' domain. Ideal for creating placeholder or example email addresses in documentation or tests.

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.ascii_safe_email()
...
'frodo2012@example.com'
'mustakovatoshka@example.com'
'yakimkobilarov@example.com'
'kiberzlatkov@example.org'
'zdravelin42@example.org'
```

--------------------------------

### Specifying a seed for reproducible output with :sample:

Source: https://faker.readthedocs.io/en/stable/writing-docs.html

This demonstrates how to use the 'seed=SEED' option within the ':sample:' pseudo-role to ensure reproducible output by setting a specific initial seed.

```rst
:sample seed=12345: a=2
```

--------------------------------

### Generate Azerbaijan Start Digits

Source: https://faker.readthedocs.io/en/stable/locales/az_AZ.html

Generates 5 starting digits for phone numbers in Azerbaijan. Seeding Faker ensures repeatable sequences.

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.start_digit()
...
```

--------------------------------

### CSV Generation Example with Faker Seed

Source: https://faker.readthedocs.io/en/stable/locales/tl_PH.html

Demonstrates generating CSV data using the `dsv` method after seeding the Faker generator. This ensures reproducible results for the generated data.

```python
from faker import Faker

Faker.seed(0)
for _ in range(5):
    fake.dsv(dialect='excel', data_columns=('{{name}}', '{{address}}'))

```

--------------------------------

### Generate Date Object Between Dates (Custom Start)

Source: https://faker.readthedocs.io/en/stable/locales/da_DK.html

Generates a `datetime.date` object between a custom start date (e.g., '-1w' for one week ago) and the default end date ('today').

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.date_between(start_date='-1w')
...
datetime.date(2026, 6, 8)
datetime.date(2026, 6, 8)
datetime.date(2026, 6, 5)
datetime.date(2026, 6, 4)
datetime.date(2026, 6, 6)
```

--------------------------------

### Sample Usage Generation with Custom Size and Arguments

Source: https://faker.readthedocs.io/en/stable/_sources/writing-docs.rst.txt

This snippet shows how to customize sample usage generation by specifying the number of calls (size) and passing custom keyword arguments to the provider method.

```python
>>> Faker.seed(0)
>>> for _ in range(10):
...     fake.method1(a=1, b=2, c=3)
...
# Output 1
# Output 2
# Output 3
# Output 4
# Output 5
# Output 6
# Output 7
# Output 8
# Output 9
# Output 10
```

--------------------------------

### time_object()

Source: https://faker.readthedocs.io/en/stable/locales/gu_IN.html

Get a time object.

```APIDOC
## time_object()

### Description
Get a time object.

### Method
N/A (This is a method call on a Faker instance)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **end_datetime** (DateParseType | None) - Optional - A `DateParseType`. Defaults to the current date and time

### Request Example
```python
fake.time_object(end_datetime='+1h')
```

### Response
#### Success Response
- **time** (time) - A time object.

#### Response Example
```json
"16:23:20.441376"
```
```

--------------------------------

### Generate Date Between Dates (Custom Start Date)

Source: https://faker.readthedocs.io/en/stable/locales/bn_BD.html

Generates a random date object between a custom start date (e.g., '-1w') and the default end date ('today'). Useful for defining specific past date ranges.

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.date_between(start_date='-1w')
...
```

--------------------------------

### File Provider Methods

Source: https://faker.readthedocs.io/en/stable/_sources/providers/faker.providers.file.rst.txt

The `faker.providers.file.Provider` class offers several methods for generating file-related data. These include generating file extensions, full file names, file paths, MIME types, and Unix-specific file attributes.

```APIDOC
## File Provider Methods

### Description
Provides methods to generate various file-related attributes.

### Methods
- `file_extension()`: Generates a random file extension.
- `file_name()`: Generates a random file name.
- `file_path()`: Generates a random file path.
- `mime_type()`: Generates a random MIME type.
- `unix_device()`: Generates a random Unix device name.
- `unix_partition()`: Generates a random Unix partition name.

### Usage Examples
```python
from faker import Faker

faker = Faker()

print(faker.file_extension())
print(faker.file_name())
print(faker.file_path())
print(faker.mime_type())
print(faker.unix_device())
print(faker.unix_partition())
```
```

--------------------------------

### Generate DSV with Custom Arguments

Source: https://faker.readthedocs.io/en/stable/locales/en_US.html

Demonstrates setting provider-specific arguments for data generation within the `dsv` method. Here, `top_half` arguments are set for `pyint` to control its range.

```python
fake.set_arguments(‘top_half’, {‘min_value’: 50, ‘max_value’: 100})
fake.dsv(data_columns=(‘{{ name }}’, ‘{{ pyint:top_half }}’))
```

--------------------------------

### Generate Random Datetime Between Dates

Source: https://faker.readthedocs.io/en/stable/locales/en_PH.html

Generates a random datetime object. Defaults to the UNIX epoch for the start and the current date/time for the end. Can specify custom start and end dates using string formats like '-30y' or 'now'.

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.date_time_between()
...
datetime.datetime(2021, 10, 10, 4, 4, 55, 236214)
datetime.datetime(2019, 3, 7, 17, 29, 41, 808743)
datetime.datetime(2009, 1, 21, 22, 59, 22, 361449)
datetime.datetime(2004, 3, 17, 16, 9, 58, 49189)
datetime.datetime(2011, 10, 12, 19, 26, 54, 171082)
```

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.date_time_between_dates()
...
datetime.datetime(2026, 6, 10, 20, 54, 12)
datetime.datetime(2026, 6, 10, 20, 54, 12)
datetime.datetime(2026, 6, 10, 20, 54, 12)
datetime.datetime(2026, 6, 10, 20, 54, 12)
datetime.datetime(2026, 6, 10, 20, 54, 12)
```

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.date_time_between_dates(datetime_start='-30y', datetime_end='now')
...
datetime.datetime(2021, 10, 10, 4, 4, 55, 236214)
datetime.datetime(2019, 3, 7, 17, 29, 41, 808743)
datetime.datetime(2009, 1, 21, 22, 59, 22, 361449)
datetime.datetime(2004, 3, 17, 16, 9, 58, 49189)
datetime.datetime(2011, 10, 12, 19, 26, 54, 171082)
```

```python
>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.date_time_between_dates(datetime_start='now', datetime_end='+1y')
...
datetime.datetime(2027, 4, 15, 6, 54, 9, 441207)
datetime.datetime(2027, 3, 14, 16, 56, 58, 993625)
datetime.datetime(2026, 11, 11, 11, 31, 58, 345382)
datetime.datetime(2026, 9, 13, 10, 30, 19, 534973)
datetime.datetime(2026, 12, 14, 14, 36, 53, 405703)
```

--------------------------------

### Provider.nic_handle()

Source: https://faker.readthedocs.io/en/stable/providers/faker.providers.internet.html

Generates a NIC handle.

```APIDOC
## Provider.nic_handle()

### Description
Generates a NIC handle.

### Method
Provider.nic_handle()

### Parameters
None

### Response
- Returns a string representing a NIC handle.
```

--------------------------------

### time()

Source: https://faker.readthedocs.io/en/stable/locales/gu_IN.html

Get a time string in a specified format.

```APIDOC
## time()

### Description
Get a time string (24h format by default).

### Method
N/A (This is a method call on a Faker instance)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **pattern** (str) - Optional - format. Defaults to `"%H:%M:%S"`
- **end_datetime** (DateParseType | None) - Optional - A `DateParseType`. Defaults to the current date and time

### Request Example
```python
fake.time(pattern='%I:%M %p')
```

### Response
#### Success Response
- **time_string** (str) - The formatted time string.

#### Response Example
```json
"03:32 PM"
```
```

--------------------------------

### Provider.nic_handles()

Source: https://faker.readthedocs.io/en/stable/locales/en_US.html

Generates a list of fake NIC handles.

```APIDOC
## Provider.nic_handles()

### Description
Generates a list of fake NIC handles.

### Method
N/A (Method call)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response
- **nic_handles** (list of strings) - A list of randomly generated NIC handles.
```

--------------------------------

### date_this_century

Source: https://faker.readthedocs.io/en/stable/locales/da_DK.html

Gets a Date object for the current century.

```APIDOC
## date_this_century

### Description
Gets a Date object for the current century.

### Method
GET

### Endpoint
```
fake.date_this_century(before_today=True, after_today=False)
```

### Parameters
#### Query Parameters
- **before_today** (bool) - Optional - Include days in the current century before today. Defaults to True.
- **after_today** (bool) - Optional - Include days in the current century after today. Defaults to False.

### Response
#### Success Response (200)
- **date** (date) - A Date object from the current century.

#### Response Example
```json
{
  "example": "2022-04-29"
}
```
```

--------------------------------

### date_between

Source: https://faker.readthedocs.io/en/stable/locales/pl_PL.html

Gets a Date object between two given dates.

```APIDOC
## date_between

### Description
Gets a Date object based on a random date between two given dates. Accepts date strings that can be recognized by strtotime().

### Method
GET

### Endpoint
N/A (SDK method)

### Parameters
#### Query Parameters
- **start_date** (DateParseType) - Optional - Defaults to 30 years ago.
- **end_date** (DateParseType) - Optional - Defaults to "today".

### Request Example
```python
fake.date_between()
fake.date_between(start_date='-1w')
fake.date_between(start_date="-1y", end_date="+1w")
```

### Response
#### Success Response
- **return value** (date) - A `datetime.date` object.

### Response Example
```json
"2021-10-09"
"2026-06-08"
"2026-04-19"
```
```

--------------------------------

### Generate Provider Documentation for Specific Locale

Source: https://faker.readthedocs.io/en/stable/index.html

Command to generate documentation for Faker providers in a specific locale (e.g., 'de_DE') by running the module as a script with the --lang option.

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

--------------------------------

### date_between_dates

Source: https://faker.readthedocs.io/en/stable/locales/ru_RU.html

Gets a random date between two given dates.

```APIDOC
## date_between_dates

### Description
Gets a random date between the two given dates.

### Method
GET

### Endpoint
N/A (SDK method)

### Parameters
#### Query Parameters
- **date_start** (DateParseType) - Optional - The start date. Defaults to the UNIX epoch.
- **date_end** (DateParseType) - Optional - The end date. Defaults to the current date and time.

### Request Example
```python
from faker import Faker

fake = Faker()

# Default range (UNIX epoch to now)
print(fake.date_between_dates())
```

### Response
#### Success Response
- **date**: A `datetime.date` object within the specified range.

### Response Example
```json
"2026-06-10"
```
```

--------------------------------

### Provider.pylist()

Source: https://faker.readthedocs.io/en/stable/locales/en_US.html

Generates a fake Python list.

```APIDOC
## Provider.pylist()

### Description
Generates a fake Python list.

### Method
N/A (Method call)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response
- **pylist** (list) - A randomly generated Python list.
```

--------------------------------

### Run Project Tests with Tox

Source: https://faker.readthedocs.io/en/stable/index.html

Command to execute the project's automated tests using the `tox` tool.

```bash
$ tox
```

--------------------------------

### date_between

Source: https://faker.readthedocs.io/en/stable/locales/es_ES.html

Gets a random date between two given dates.

```APIDOC
## date_between

### Description
Get a Date object based on a random date between two given dates. Accepts date strings that can be recognized by strtotime().

### Method
`date_between(start_date: DateParseType = '-30y', end_date: DateParseType = 'today') -> date`

### Parameters
#### Query Parameters
- **start_date** (DateParseType) - Optional - A `DateParseType`. Defaults to 30 years ago
- **end_date** (DateParseType) - Optional - A `DateParseType`. Defaults to "today"

### Response Example
```
datetime.date(2021, 10, 9)
```
```

--------------------------------

### date_object

Source: https://faker.readthedocs.io/en/stable/locales/de_DE.html

Get a date object between January 1, 1970 and now.

```APIDOC
## date_object

### Description
Get a date object between January 1, 1970 and now.

### Method
N/A (This is a method call on a Faker instance)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **end_datetime** (DateParseType) - Optional - Defaults to the current date and time.

### Request Example
```python
from faker import Faker
fake = Faker()

# Default end_datetime
print(fake.date_object())

# With end_datetime
print(fake.date_object(end_datetime='+1w'))
```

### Response
#### Success Response
- **date** (date) - A `datetime.date` object.

### Response Example
```json
"2017-08-29"
```
```

--------------------------------

### Provider.pytuple()

Source: https://faker.readthedocs.io/en/stable/locales/en_US.html

Generates a fake Python tuple.

```APIDOC
## Provider.pytuple()

### Description
Generates a fake Python tuple.

### Method
N/A (Method call)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response
- **pytuple** (tuple) - A randomly generated Python tuple.
```

--------------------------------

### Sample Usage Generation with Specific Seed

Source: https://faker.readthedocs.io/en/stable/_sources/writing-docs.rst.txt

This snippet illustrates how to use a specific seed value to ensure reproducible output, especially when a particular output is desired. It also includes custom arguments.

```python
>>> Faker.seed(12345)
>>> for _ in range(5):
...     fake.method1(a=2)
...
# Output 1
# Output 2
# Output 3
# Output 4
# Output 5
```

--------------------------------

### iso8601

Source: https://faker.readthedocs.io/en/stable/locales/fil_PH.html

Get an ISO 8601 string for a datetime between the UNIX epoch and now.

```APIDOC
## `iso8601`

Get an ISO 8601 string for a datetime between the UNIX epoch and now.

### Parameters

* **tzinfo** (tzinfo | None) - Optional - Timezone information.
* **end_datetime** (date | datetime | timedelta | str | int | None) - Optional - A `DateParseType`. Defaults to the current date and time.
* **sep** (str) - Optional - Separator between date and time. Defaults to ‘T’.
* **timespec** (str) - Optional - Format specifier for the time part. Defaults to ‘auto’ - see datetime.isoformat() documentation.

### Examples

```python
from faker import Faker

fake = Faker()
Faker.seed(0)

print(fake.iso8601())
```
```

--------------------------------

### date_this_century(before_today=True, after_today=False)

Source: https://faker.readthedocs.io/en/stable/locales/ja_JP.html

Gets a Date object for the current century.

```APIDOC
## date_this_century(before_today=True, after_today=False)

### Description
Gets a Date object for the current century.

### Method
GET

### Endpoint
N/A (SDK method)

### Parameters
#### Query Parameters
- **before_today** (bool) - Optional - include days in current century before today. Defaults to True.
- **after_today** (bool) - Optional - include days in current century after today. Defaults to False.

### Response
#### Success Response (200)
- **date** (date) - A date object within the current century.

### Response Example
```json
{
  "example": "datetime.date(2022, 4, 29)"
}
```
```

--------------------------------

### date_object(end_datetime=None)

Source: https://faker.readthedocs.io/en/stable/locales/ja_JP.html

Get a date object between January 1, 1970 and now.

```APIDOC
## date_object(end_datetime=None)

### Description
Get a date object between January 1, 1970 and now.

### Method
GET

### Endpoint
N/A (SDK method)

### Parameters
#### Query Parameters
- **end_datetime** (DateParseType) - Optional - Defaults to the current date and time.

### Response
#### Success Response (200)
- **date** (date) - A date object.

### Response Example
```json
{
  "example": "datetime.date(2017, 8, 29)"
}
```

```json
{
  "example": "datetime.date(2017, 9, 4)"
}
```
```

--------------------------------

### Provider.nic_handles()

Source: https://faker.readthedocs.io/en/stable/providers/faker.providers.internet.html

Generates multiple NIC handles.

```APIDOC
## Provider.nic_handles()

### Description
Generates multiple NIC handles.

### Method
Provider.nic_handles()

### Parameters
None

### Response
- Returns a list of strings representing NIC handles.
```

--------------------------------

### Random Sampling with Replacement

Source: https://faker.readthedocs.io/en/stable/providers/baseprovider.html

Demonstrates how to randomly select elements from a weighted collection with replacement. Useful for simulating scenarios where items can be chosen multiple times based on their probability.

```python
from collections import OrderedDict

fake.random_elements(
    elements=OrderedDict([
        ("variable_1", 0.5),        # Generates "variable_1" 50% of the time
        ("variable_2", 0.2),        # Generates "variable_2" 20% of the time
        ("variable_3", 0.2),        # Generates "variable_3" 20% of the time
        ("variable_4", 0.1),        # Generates "variable_4" 10% of the time
    ]), unique=False
)
```

--------------------------------

### date_time_ad

Source: https://faker.readthedocs.io/en/stable/locales/ar_EG.html

Get a datetime object for a date between January 1, 0001 and now.

```APIDOC
## date_time_ad

### Description
Get a datetime object for a date between January 1, 0001 and now.

### Method
`fake.date_time_ad()`

### Parameters
#### Query Parameters
- **tzinfo** (tzinfo) - Optional - timezone, instance of datetime.tzinfo subclass
- **end_datetime** (DateParseType) - Optional - Defaults to the current date and time
- **start_datetime** (DateParseType) - Optional - Defaults to UNIX timestamp `-62135596800`, equivalent to 0001-01-01 00:00:00 UTC

### Request Example
```json
{
  "tzinfo": "UTC",
  "end_datetime": "2023-10-27T10:00:00Z",
  "start_datetime": "0001-01-01T00:00:00Z"
}
```

### Response
#### Success Response (200)
- **datetime** (datetime.datetime) - A datetime object between 0001-01-01 and now.
```

--------------------------------

### past_date

Source: https://faker.readthedocs.io/en/stable/locales/es.html

Generates a random date object between a specified start date and yesterday.

```APIDOC
## `past_date`

### Description
Get a Date object based on a random date between a given date and 1 day ago.

### Parameters

* **start_date** – A `DateParseType`. Defaults to `"-30d"`
* **tzinfo** – timezone, instance of datetime.tzinfo subclass

### Sample

```python
past_date(start_date='-1y')
```
```

--------------------------------

### Provider.binary()

Source: https://faker.readthedocs.io/en/stable/locales/en_US.html

Generates a fake binary string.

```APIDOC
## Provider.binary()

### Description
Generates a fake binary string.

### Method
N/A (Method call)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response
- **binary** (string) - A randomly generated binary string.
```

--------------------------------

### Currency Provider Methods

Source: https://faker.readthedocs.io/en/stable/locales/es_CL.html

Methods for generating cryptocurrency and currency details specific to the es_CL locale.

```APIDOC
## `faker.providers.currency.es_CL`

### Description
Provides methods to generate cryptocurrency and currency data for the Chilean Spanish locale.

### Methods

- **cryptocurrency()**
  - Description: Generates a tuple containing the cryptocurrency code and name.
  - Example:
    ```python
    fake.cryptocurrency()
    ```

- **cryptocurrency_code()**
  - Description: Generates a cryptocurrency code (e.g., 'XRP', 'BTC').
  - Example:
    ```python
    fake.cryptocurrency_code()
    ```

- **cryptocurrency_name()**
  - Description: Generates a cryptocurrency name (e.g., 'Ripple', 'Bitcoin').
  - Example:
    ```python
    fake.cryptocurrency_name()
    ```

- **currency()**
  - Description: Generates a tuple containing the currency code and name.
  - Example:
    ```python
    fake.currency()
    ```

- **currency_code()**
  - Description: Generates a currency code (e.g., 'CLP', 'USD').
  - Example:
    ```python
    fake.currency_code()
    ```

- **currency_name()**
  - Description: Generates a currency name (e.g., 'Peso chileno', 'Dólar estadounidense').
  - Example:
    ```python
    fake.currency_name()
    ```

- **currency_symbol(code: str | None = None)**
  - Description: Generates a currency symbol. An optional currency code can be provided.
  - Example:
    ```python
    fake.currency_symbol()
    fake.currency_symbol('USD')
    ```

- **pricetag()**
  - Description: Generates a price tag string.
  - Example:
    ```python
    fake.pricetag()
    ```
```

--------------------------------

### date_between_dates(date_start=None, date_end=None)

Source: https://faker.readthedocs.io/en/stable/locales/ja_JP.html

Get a random date between the two given dates.

```APIDOC
## date_between_dates(date_start=None, date_end=None)

### Description
Get a random date between the two given dates.

### Method
GET

### Endpoint
N/A (SDK method)

### Parameters
#### Query Parameters
- **date_start** (DateParseType) - Optional - Defaults to the UNIX epoch.
- **date_end** (DateParseType) - Optional - Defaults to the current date and time.

### Response
#### Success Response (200)
- **date** (date) - A random date object between the specified start and end dates.

### Response Example
```json
{
  "example": "datetime.date(2026, 6, 10)"
}
```
```