diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 7c02f04ff..24b17465e 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,3 +1,11 @@ +Version 12.1.0 +-------------- + +- Methods ``gender_code()`` and ``gender_symbol()`` have been added for the ``Person`` provider. +- The methods ``gender()`` and ``sex()`` no longer accept arguments like ``iso5218`` and ``symbol``. Please use ``gender_code()`` and ``gender_symbol()`` instead. +- Added a stub for ``mimesis.providers.generic.py``, enabling type hints for ``Generic``. + + Version 12.0.0 -------------- diff --git a/mimesis/data/int/person.py b/mimesis/data/int/person.py index da5df69e4..a473df4c9 100644 --- a/mimesis/data/int/person.py +++ b/mimesis/data/int/person.py @@ -1,6 +1,5 @@ """Provides all the generic data related to the personal information.""" - BLOOD_GROUPS = ( "O+", "A+", @@ -12,11 +11,9 @@ "AB−", ) -GENDER_SYMBOLS = ( - "♂", - "♀", - "⚲", -) +GENDER_SYMBOLS = ("♂", "♀", "⚲") + +GENDER_CODES = (0, 1, 2, 9) USERNAMES = [ "aaa", diff --git a/mimesis/providers/person.py b/mimesis/providers/person.py index 92a4cfd9f..751a74cff 100644 --- a/mimesis/providers/person.py +++ b/mimesis/providers/person.py @@ -10,6 +10,7 @@ BLOOD_GROUPS, CALLING_CODES, EMAIL_DOMAINS, + GENDER_CODES, GENDER_SYMBOLS, USERNAMES, ) @@ -79,7 +80,7 @@ def name(self, gender: Gender | None = None) -> str: def first_name(self, gender: Gender | None = None) -> str: """Generates a random first name. - ..note: An alias for self.name(). + ..note: An alias for :meth:`~.name`. :param gender: Gender's enum object. :return: First name. @@ -107,7 +108,7 @@ def surname(self, gender: Gender | None = None) -> str: def last_name(self, gender: Gender | None = None) -> str: """Generates a random last name. - ..note: An alias for self.surname(). + ..note: An alias for :meth:`~.surname`. :param gender: Gender's enum object. :return: Last name. @@ -269,42 +270,44 @@ def email( return f"{name}{domain}" - def gender(self, iso5218: bool = False, symbol: bool = False) -> str | int: - """Generates a random gender. + def gender_symbol(self) -> str: + """Generate a random sex symbol. - Get a random title of gender code for the representation + :Example: + ♂ + """ + return self.random.choice(GENDER_SYMBOLS) + + def gender_code(self) -> int: + """Generate a random ISO/IEC 5218 gender code. + + Generate a random title of gender code for the representation of human sexes is an international standard that defines a representation of human sexes through a language-neutral single-digit code or symbol of gender. - :param iso5218: - Codes for the representation of human sexes is an international - standard (0 - not known, 1 - male, 2 - female, 9 - not applicable). - :param symbol: Symbol of gender. - :return: Title of gender. + Codes for the representation of human sexes is an international + standard (0 - not known, 1 - male, 2 - female, 9 - not applicable). - :Example: - Male + :return: """ - if iso5218: - return self.random.choice([0, 1, 2, 9]) + return self.random.choice(GENDER_CODES) - if symbol: - return self.random.choice(GENDER_SYMBOLS) + def gender(self) -> str: + """Generates a random gender title. + :Example: + Male + """ genders: list[str] = self._extract(["gender"]) return self.random.choice(genders) - def sex(self, *args: t.Any, **kwargs: t.Any) -> str | int: - """An alias for method self.gender(). - - See docstrings of method self.gender() for details. + def sex(self) -> str: + """An alias for method :meth:`~.gender`. - :param args: Positional arguments. - :param kwargs: Keyword arguments. - :return: Sex + :return: Sex. """ - return self.gender(*args, **kwargs) + return self.gender() def height(self, minimum: float = 1.5, maximum: float = 2.0) -> str: """Generates a random height in meters. @@ -455,7 +458,7 @@ def phone_number(self, mask: str = "", placeholder: str = "#") -> str: return self.random.generate_string_by_mask(mask=mask, digit=placeholder) def telephone(self, *args: t.Any, **kwargs: t.Any) -> str: - """An alias for method self.phone_number().""" + """An alias for :meth:`~.phone_number`.""" return self.phone_number(*args, **kwargs) def identifier(self, mask: str = "##-##/##") -> str: diff --git a/tests/test_providers/test_person.py b/tests/test_providers/test_person.py index 089a35988..251570edc 100644 --- a/tests/test_providers/test_person.py +++ b/tests/test_providers/test_person.py @@ -3,7 +3,7 @@ import pytest from mimesis import Person, random -from mimesis.data import BLOOD_GROUPS, GENDER_SYMBOLS +from mimesis.data import BLOOD_GROUPS, GENDER_CODES, GENDER_SYMBOLS from mimesis.enums import Gender, TitleType from mimesis.exceptions import NonEnumerableError @@ -250,32 +250,22 @@ def test_full_name(self, person, gender): with pytest.raises(NonEnumerableError): person.full_name(gender="nil") + def test_gender_code(self, _person): + code = _person.gender_code() + assert code in GENDER_CODES + + def test_gender_symbol(self, _person): + symbol = _person.gender_symbol() + assert symbol in GENDER_SYMBOLS + def test_gender(self, person): result = person.gender() assert result in person._data["gender"] - result = person.gender(symbol=True) - assert result in GENDER_SYMBOLS - - # The four codes specified in ISO/IEC 5218 are: - # 0 = not known, 1 = male, 2 = female, 9 = not applicable. - codes = [0, 1, 2, 9] - iso5218 = person.gender(iso5218=True) - assert iso5218 in codes - def test_sex(self, person): result = person.sex() assert result in person._data["gender"] - result = person.gender(symbol=True) - assert result in GENDER_SYMBOLS - - # The four codes specified in ISO/IEC 5218 are: - # 0 = not known, 1 = male, 2 = female, 9 = not applicable. - codes = [0, 1, 2, 9] - iso5218 = person.gender(iso5218=True) - assert iso5218 in codes - def test_profession(self, person): result = person.occupation() assert result in person._data["occupation"] @@ -420,15 +410,17 @@ def test_full_name(self, p1, p2): gender=Gender.FEMALE, reverse=True ) + def test_gender_code(self, p1, p2): + assert p1.gender_code() == p2.gender_code() + + def test_gender_symbol(self, p1, p2): + assert p1.gender_symbol() == p2.gender_symbol() + def test_gender(self, p1, p2): assert p1.gender() == p2.gender() - assert p1.gender(iso5218=True, symbol=True) == p2.gender( - iso5218=True, symbol=True - ) def test_sex(self, p1, p2): assert p1.sex() == p2.sex() - assert p1.sex(iso5218=True, symbol=True) == p2.sex(iso5218=True, symbol=True) def test_occupation(self, p1, p2): assert p1.occupation() == p2.occupation()