Source code for mimesis.providers.address

"""Address module.

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

import typing as t

from mimesis.data import (
    CALLING_CODES,
    CONTINENT_CODES,
    COUNTRY_CODES,
    SHORTENED_ADDRESS_FMT,
)
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: """Convert 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: """Generate a random street number. :param maximum: Maximum value. :return: Street number. """ return str(self.random.randint(1, maximum))
[docs] def street_name(self) -> str: """Get a random street name. :return: Street name. """ street_names: t.List[str] = self.extract(["street", "name"]) return self.random.choice(street_names)
[docs] def street_suffix(self) -> str: """Get a random street suffix. :return: Street suffix. """ suffixes: t.List[str] = self.extract(["street", "suffix"]) return self.random.choice(suffixes)
[docs] def address(self) -> str: """Generate 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 list of random integers # in amount of 3, from 1 to 100. *self.random.randints(amount=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: """Get a random administrative district of country. :param abbr: Return ISO 3166-2 code. :return: Administrative district. """ key = "abbr" if abbr else "name" states: t.List[str] = self.extract(["state", key]) return self.random.choice(states)
[docs] def region(self, *args: t.Any, **kwargs: t.Any) -> str: """Get a random region. An alias for :meth:`~Address.state()`. """ return self.state(*args, **kwargs)
[docs] def province(self, *args: t.Any, **kwargs: t.Any) -> str: """Get a random province. An alias for :meth:`~Address.state()`. """ return self.state(*args, **kwargs)
[docs] def federal_subject(self, *args: t.Any, **kwargs: t.Any) -> str: """Get a random region. An alias for :meth:`~Address.state()`. """ return self.state(*args, **kwargs)
[docs] def prefecture(self, *args: t.Any, **kwargs: t.Any) -> str: """Get a random prefecture. An alias for :meth:`~Address.state()`. """ return self.state(*args, **kwargs)
[docs] def postal_code(self) -> str: """Generate a postal code for current locale. :return: Postal code. """ return self.random.custom_code(self.extract(["postal_code_fmt"]))
[docs] def zip_code(self) -> str: """Generate a zip code. An alias for :meth:`~Address.postal_code()`. :return: Zip code. """ return self.postal_code()
[docs] def country_code(self, code: t.Optional[CountryCode] = CountryCode.A2) -> str: """Get a random code of country. Default format is :attr:`~enums.CountryCode.A2` (ISO 3166-1-alpha2), you can change it by passing parameter ``fmt`` with enum object :class:`~enums.CountryCode`. :param code: Enum object CountryCode. :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 default_country(self) -> str: """Get 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: """Get a random country. :return: The Country. """ countries: t.List[str] = self.extract(["country", "name"]) return self.random.choice(countries)
[docs] def city(self) -> str: """Get a random city. :return: City name. """ cities: t.List[str] = self.extract(["city"]) return self.random.choice(cities)
def _get_fs(self, key: str, dms: bool = False) -> t.Union[str, float]: """Get float number. :param key: Key (`lt` or `lg`). :param dms: DMS format. :return: Float number """ # Default range is a range of longitude. 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) -> t.Union[str, float]: """Generate 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) -> t.Union[str, float]: """Generate 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) -> t.Dict[str, t.Union[str, float]]: """Generate 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: """Get a random continent name or continent code. :param code: Return code of continent. :return: Continent name. """ codes: t.List[str] = self.extract(["continent"]) if code: codes = CONTINENT_CODES return self.random.choice(codes)
[docs] def calling_code(self) -> str: """Get a random calling code of random country. :return: Calling code. """ return self.random.choice(CALLING_CODES)