Fix docstrings

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
 --------------
 

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",

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:

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()