Source code for mimesis.providers.address

"""Address module.

This module contains provider Address() and other utils which represent
data related to location, such as street name, city etc.

import typing as t

from mimesis.datasets import (
from mimesis.enums import CountryCode
from mimesis.providers.base import BaseDataProvider

__all__ = ["Address"]

[docs] class Address(BaseDataProvider): """Class for generate fake address data. This object provides all the data related to geographical location. """ class Meta: name = "address" datafile = f"{name}.json" @staticmethod def _dd_to_dms(num: float, _type: str) -> str: """Converts decimal number to DMS format. :param num: Decimal number. :param _type: Type of number. :return: Number in DMS format. """ direction = "" if _type == "lg": direction = "W" if num < 0 else "E" elif _type == "lt": direction = "S" if num < 0 else "N" num = abs(num) degrees = int(num) part = num - degrees minutes = int(part * 60) seconds = 3600 * part - 60 * minutes seconds = round(seconds, 3) return f"{degrees}ยบ{minutes}'{seconds:.3f}\"{direction}"
[docs] def street_number(self, maximum: int = 1400) -> str: """Generates a random street number. :param maximum: Maximum value. :return: Street number. """ return str(self.random.randint(1, maximum))
[docs] def street_name(self) -> str: """Generates a random street name. :return: Street name. """ street_names: list[str] = self._extract(["street", "name"]) return self.random.choice(street_names)
[docs] def street_suffix(self) -> str: """Generates a random street suffix. :return: Street suffix. """ suffixes: list[str] = self._extract(["street", "suffix"]) return self.random.choice(suffixes)
[docs] def address(self) -> str: """Generates a random full address. :return: Full address. """ fmt: str = self._extract(["address_fmt"]) st_num = self.street_number() st_name = self.street_name() if self.locale in SHORTENED_ADDRESS_FMT: return fmt.format( st_num=st_num, st_name=st_name, ) if self.locale == "ja": return fmt.format( self.random.choice(self._extract(["city"])), # Generate a list of random integers # in n of 3, from 1 to 100. *self.random.randints(n=3, a=1, b=100), ) return fmt.format( st_num=st_num, st_name=st_name, st_sfx=self.street_suffix(), )
[docs] def state(self, abbr: bool = False) -> str: """Generates a random administrative district of the country. :param abbr: Return ISO 3166-2 code. :return: Administrative district. """ key = "abbr" if abbr else "name" states: list[str] = self._extract(["state", key]) return self.random.choice(states)
[docs] def region(self, *args: t.Any, **kwargs: t.Any) -> str: """Generates a random region. An alias for :meth:`~.state()`. """ return self.state(*args, **kwargs)
[docs] def province(self, *args: t.Any, **kwargs: t.Any) -> str: """Generates a random province. An alias for :meth:`~.state()`. """ return self.state(*args, **kwargs)
[docs] def federal_subject(self, *args: t.Any, **kwargs: t.Any) -> str: """Generates a random federal_subject (Russia). An alias for :meth:`~.state()`. """ return self.state(*args, **kwargs)
[docs] def prefecture(self, *args: t.Any, **kwargs: t.Any) -> str: """Generates a random prefecture. An alias for :meth:`~.state()`. """ return self.state(*args, **kwargs)
[docs] def postal_code(self) -> str: """Generates a postal code for current locale. :return: Postal code. """ return self.random.generate_string_by_mask(self._extract(["postal_code_fmt"]))
[docs] def zip_code(self) -> str: """Generates a zip code. An alias for :meth:`~.postal_code()`. :return: Zip code. """ return self.postal_code()
[docs] def country_code(self, code: CountryCode | None = CountryCode.A2) -> str: """Generates a random code of country. Default format is :attr:`~enums.CountryCode.A2` (ISO 3166-1-alpha2), you can change it by passing parameter ``fmt``. :param code: Country code. :return: Country code in selected format. :raises KeyError: if fmt is not supported. """ key = self.validate_enum(code, CountryCode) return self.random.choice(COUNTRY_CODES[key])
[docs] def country_emoji_flag(self) -> str: """Generates a randomly chosen country emoji flag. :example: ๐Ÿ‡น๐Ÿ‡ท :return: Flag emoji. """ code = self.country_code( code=CountryCode.A2, ) offset = ord("๐Ÿ‡ฆ") - ord("A") first = ord(code[0]) + offset second = ord(code[1]) + offset return chr(first) + chr(second)
[docs] def default_country(self) -> str: """Returns the country associated with the current locale. :return: The country associated with current locale. """ country: str = self._extract(["country", "current_locale"]) return country
[docs] def country(self) -> str: """Generates a random country. :return: The Country. """ countries: list[str] = self._extract(["country", "name"]) return self.random.choice(countries)
[docs] def city(self) -> str: """Generates a random city. :return: City name. """ cities: list[str] = self._extract(["city"]) return self.random.choice(cities)
def _get_fs(self, key: str, dms: bool = False) -> str | float: """Get float number. :param key: Key (`lt` or `lg`). :param dms: DMS format. :return: Float number """ # The default range is a range of longitudes. rng = (-90, 90) if key == "lt" else (-180, 180) result = self.random.uniform(*rng, precision=6) if dms: return self._dd_to_dms(result, key) return result
[docs] def latitude(self, dms: bool = False) -> str | float: """Generates a random value of latitude. :param dms: DMS format. :return: Value of longitude. """ return self._get_fs("lt", dms)
[docs] def longitude(self, dms: bool = False) -> str | float: """Generates a random value of longitude. :param dms: DMS format. :return: Value of longitude. """ return self._get_fs("lg", dms)
[docs] def coordinates(self, dms: bool = False) -> dict[str, str | float]: """Generates random geo coordinates. :param dms: DMS format. :return: Dict with coordinates. """ return { "longitude": self._get_fs("lg", dms), "latitude": self._get_fs("lt", dms), }
[docs] def continent(self, code: bool = False) -> str: """Returns a random continent name or continent code. :param code: Return code of a continent. :return: Continent name. """ codes: list[str] = self._extract(["continent"]) if code: codes = CONTINENT_CODES return self.random.choice(codes)
[docs] def calling_code(self) -> str: """Generates a random calling code of random country. :return: Calling code. """ return self.random.choice(CALLING_CODES)
[docs] def isd_code(self) -> str: """Generates a random ISD code. An alias for :meth:`~Address.calling_code()`. """ return self.calling_code()