Faker

You can instantiate a Faker instance with multiple locales by passing a list or an OrderedDict of locales. When calling provider methods directly on the Faker instance (e.g., fake.name()), the library selects a locale based on the weights provided during instantiation.

To access a specific locale's generator directly, use subscript notation (e.g., fake['en_US']). This allows you to call provider methods that might only be supported by specific locales.

Key attributes and methods:

• fake.locales: Returns the list of locales specified during instantiation.
• fake.factories: Returns the list of internal generators (one per locale).
• fake['locale_name']: Accesses the internal generator for a specific locale. Raises KeyError if the locale was not included during instantiation.
• fake.name(): Generates a value using weighted selection across all locales.
• fake['en_US'].name(): Generates a value specifically using the en_US locale.

from collections import OrderedDict
from faker import Faker

# Define locales with weights (higher number = higher probability)
locales = OrderedDict([
    ('en-US', 1),
    ('en-PH', 2),
    ('ja_JP', 3),
])
fake = Faker(locales)

# Weighted generation
name = fake.name() 

# Specific locale generation
name_us = fake['en_US'].name()

The documentation build process uses sphinx.ext.autodoc to preprocess docstrings. When valid :sample: lines are detected, they are removed from their original position and all generated outputs are collected into a single :examples: section appended to the end of the docstring.

Important Guidelines

1. Placement: Because :sample: lines are moved to the end of the docstring during preprocessing, you should place all :sample: lines at the end of your docstring to ensure the logical flow of your text remains intact.
2. Validation: If a :sample: line is malformed, it will be discarded, and a warning will be logged to the console.
3. Fallback: If a provider method lacks a docstring or valid :sample: lines, a default sample usage section is automatically generated.
4. Errors: If a sample run fails (e.g., due to invalid KWARGS or an exception raised by the method), a warning will be logged to the console.

The faker fixture is designed to be session-scoped for performance, but it can be forced to return a new, function-scoped instance for specific tests by activating a faker_locale fixture.

• Automatic switching: If you define an autouse faker_locale fixture with a non-session scope (e.g., in a submodule's conftest.py), the faker fixture will automatically provide a new instance for all tests in that scope.
• Manual injection: If you want fine-grained control, define faker_locale without autouse=True and inject it explicitly into the tests that require a specific locale.

import pytest

# Option 1: Automatic switching for a scope
@pytest.fixture(scope='function', autouse=True)
def faker_locale():
    return ['it_IT']

# Option 2: Manual injection for specific tests
@pytest.fixture()
def faker_locale():
    return ['it_IT']

def test_something(faker):
    # Uses the session-scoped instance
    pass

def test_something_else(faker, faker_locale):
    # Uses a new, function-scoped instance
    pass

The modern Faker class is a proxy object that manages one or more Generator objects (the internal engines that produce data).

• Single Locale Mode: Occurs when you provide one locale (or an empty value, which defaults to en_US). In this mode, the Faker instance proxies calls, properties, and attributes 1:1 to the single internal Generator. It behaves almost identically to the legacy Factory.create shortcut.
• Multiple Locale Mode: Occurs when you provide multiple locales. In this mode, the Faker instance uses selection logic to decide which internal Generator to use when you call a provider method (e.g., fake.name()).

Because of the complexity of multiple locale mode, it is recommended to create your own subclass or call methods directly on the internal Generator objects if you need to access attributes like add_provider or the random getter/setter.

from faker import Faker
# Single locale mode
fake = Faker('en_US')

# Multiple locale mode
fake = Faker(['en_US', 'ja_JP'])

To ensure that Faker generates the same dataset every time (useful for unit testing), you can seed the random number generator.

There are two ways to seed:

1. Global Seeding: Use Faker.seed(value) to seed the shared random number generator used by all instances.
2. Instance Seeding: Use fake.seed_instance(value) on a specific Faker instance to use a private random.Random instance, separating it from the shared one.

Warning: Because datasets are updated regularly, results are not guaranteed to be consistent across different patch versions. If you hardcode expected results in your tests, you must pin your Faker version to a specific patch number.

from faker import Faker

# Global seeding
fake = Faker()
Faker.seed(4321)
print(fake.name())
# 'Margaret Boehm'

# Instance-specific seeding
fake = Faker()
fake.seed_instance(4321)
print(fake.name())
# 'Margaret Boehm'