• Home »
  • smartfaker package
View on GitHub
Star —
Used by —

smartfaker package

SmartFaker — Fake address & IBAN generator for 200+ countries.

A lightweight Python library for generating realistic fake postal addresses and IBAN numbers across hundreds of countries and territories. Bundled country data, zero network calls, and a true sync and async API.

Public API consists of the single Faker class with methods for both synchronous and asynchronous use:

Synchronous

  • Faker.address() — fake address for a single country.

  • Faker.batch_addresses() — fake addresses for many countries at once.

  • Faker.iban() — generate one or more valid IBANs.

Asynchronous

  • Faker.aaddress() — async variant of Faker.address().

  • Faker.abatch_addresses() — async variant of Faker.batch_addresses().

  • Faker.aiban() — async variant of Faker.iban().

Example — Sync

from smartfaker import Faker

faker = Faker()
addr = faker.address("us")
iban = faker.iban("DE")
print(addr["city"], iban["iban"])

Example — Async

import asyncio
from smartfaker import Faker

faker = Faker()

async def main():
    addr = await faker.aaddress("gb")
    iban = await faker.aiban("FR")
    print(addr["city"], iban["iban"])

asyncio.run(main())

Documentation site: https://abirxdhack.github.io/TheSmartFaker

class smartfaker.Faker

Bases: object

Generate realistic fake addresses and IBAN numbers for 200+ countries.

Addresses are loaded from bundled JSON data files. IBAN generation uses country-specific algorithms conforming to ISO 13616 with MOD-97 check digits.

All public generation methods have both synchronous and asynchronous variants. The asynchronous (a-prefixed) methods run their synchronous counterparts on the default executor via asyncio.to_thread(), so they integrate cleanly with any asyncio framework without blocking the event loop.

data

Mapping of lowercase ISO alpha-2 country code to the list of address dictionaries loaded from the bundled JSON files.

Type:

dict[str, list[dict]]

Example:

from smartfaker import Faker

faker = Faker()
addr = faker.address("us")
iban = faker.iban("DE")
countries()

Return the sorted list of countries available for address generation.

Returns:

list[dict] – Each item has "country_code" (ISO alpha-2, e.g. "US") and "country_name" (e.g. "United States"), sorted alphabetically by country name.

Example:

faker = Faker()
for c in faker.countries():
    print(c["country_code"], c["country_name"])
iban_countries()

Return the sorted list of countries supported for IBAN generation.

Returns:

list[dict] – Each item has "country_code" and "country_name", sorted alphabetically by country name.

Example:

for c in faker.iban_countries():
    print(c["country_code"], c["country_name"])
address(country_code, amount=1, fields=None, locale=None)

Generate one or more fake addresses for a given country (synchronous).

Parameters:

  • country_code – ISO 3166-1 alpha-2 country code (case-insensitive), e.g. "us", "GB", "fr".

  • amount – Number of addresses to generate. Defaults to 1. Capped at the number of records available for the country.

  • fields – If given, only these keys are kept in each returned address dictionary.

  • locale – If given, prefixes the person_name field with "<locale>_".

Returns:

A single address dict when amount=1, otherwise a list of address dicts. Every dict carries api_owner, api_updates and country_flag metadata.

Raises:

ValueError – If country_code is empty, unknown, or has no bundled records.

Example:

addr = faker.address("us")
five = faker.address("fr", amount=5, fields=["city", "zip"])
async aaddress(country_code, amount=1, fields=None, locale=None)

Asynchronous variant of address().

Identical contract to address(); the call is dispatched to a worker thread so it never blocks the event loop.

Example:

addr = await faker.aaddress("us")
batch_addresses(country_codes, amount=1, fields=None, locale=None)

Generate addresses for multiple countries in one call (synchronous).

Invalid or unsupported country codes are silently skipped.

Parameters:

  • country_codes – List of ISO 3166-1 alpha-2 codes.

  • amount – Addresses per country. Defaults to 1.

  • fields – Subset of fields to include in each address dictionary.

  • locale – Locale prefix for person_name.

Returns:

dict – Mapping of uppercase country code to the address result(s) for that country. Countries that fail are omitted.

Raises:

ValueError – If country_codes is empty or None.

Example:

results = faker.batch_addresses(["us", "gb", "de"])
us_addr = results["US"]
async abatch_addresses(country_codes, amount=1, fields=None, locale=None)

Asynchronous variant of batch_addresses().

Example:

results = await faker.abatch_addresses(["us", "gb"])
iban(country_code, amount=1)

Generate one or more valid fake IBANs for a given country (synchronous).

Uses the country-specific BBAN generator and the MOD-97 check-digit algorithm to produce structurally valid IBANs. Generated IBANs are re-validated before being returned.

Parameters:

  • country_code – ISO 3166-1 alpha-2 country code (uppercase), e.g. "DE", "GB", "US".

  • amount – Number of IBANs to generate. Defaults to 1.

Returns:

A single result dict when amount=1, otherwise a list of result dicts. Each dict contains:

  • iban: full IBAN string

  • country: country code

  • valid: always True

  • length: total length of the IBAN

  • details: parsed BBAN fields (bank code, account number, …)

  • api_owner / api_updates: attribution

Raises:

ValueError – If country_code is empty, unsupported, or if the generated IBAN fails length or MOD-97 validation.

Example:

iban = faker.iban("DE")
ibans = faker.iban("GB", amount=3)
async aiban(country_code, amount=1)

Asynchronous variant of iban().

Example:

iban = await faker.aiban("DE")
address_sync(*args, **kwargs)

Deprecated alias for address() (kept for backwards compatibility).

iban_sync(*args, **kwargs)

Deprecated alias for iban() (kept for backwards compatibility).