Documentation for mojang.api.auth.security

Pipfile

@@ -7,6 +7,7 @@ verify_ssl = true
 mkdocs = "*"
 mkdocs-material = "*"
 mkdocstrings = "*"
+pygments = "*"
 
 [packages]
 requests = "*"

docs/PyMojang/security.md

@@ -0,0 +1,13 @@
+Mojang Security
+===
+
+::: mojang.api.auth.security
+    handler: python
+    selection:
+      members:
+        - is_user_ip_secure
+        - get_user_challenges
+        - verify_user_ip
+    rendering:
+      show_root_heading: true
+      show_source: true

mkdocs.yml

@@ -7,6 +7,8 @@ theme:
 
 markdown_extensions:
   - admonition
+  - pymdownx.highlight
+  - pymdownx.superfences
 
 plugins:
   - search
@@ -25,7 +27,7 @@ nav:
 
   - PyMojang:
     - 'mojang.api.auth.yggdrasil': 'PyMojang/yggdrasil.md'
-    - 'mojang.api.auth.security': 'PyMojang/secuity.md'
+    - 'mojang.api.auth.security': 'PyMojang/security.md'
     - 'mojang.api.base': 'PyMojang/base.md'
     - 'mojang.api.session': 'PyMojang/session.md'
     - 'mojang.profile.UserProfile': 'PyMojang/UserProfile.md'

mojang/api/auth/security.py

@@ -4,6 +4,18 @@
 
 
 def is_user_ip_secure(access_token: str) -> bool:
+    """Check if authenticated user IP is secure
+
+    Args:
+        access_token (str): The session's access token
+
+    Returns:
+        True if IP is secure else False
+
+    Raises:
+        Unauthorized: If access token is invalid
+        PayloadError: If access token is not formated correctly
+    """
     try:
         web.auth_request('get', SECURITY_CHECK, access_token, exceptions=(PayloadError, Unauthorized, IPNotSecured))
     except IPNotSecured:
@@ -12,6 +24,30 @@ def is_user_ip_secure(access_token: str) -> bool:
         return True
 
 def get_user_challenges(access_token: str) -> list:
+    """Return a list of challenges to verify IP
+
+    Args:
+        access_token (str): The session's access token
+
+    Returns:
+        A list of tuples, each one contains the answer's id and the
+        question
+
+    Example:
+        
+        Example of challenges
+        ```python
+        [
+            (123, "What is your favorite pet's name?"),
+            (456, "What is your favorite movie?"),
+            (789, "What is your favorite author's last name?")
+        ]
+        ```
+
+    Raises:
+        Unauthorized: If access token is invalid
+        PayloadError: If access token is not formated correctly
+    """
     data = web.auth_request('get', SECURITY_CHALLENGES, access_token, exceptions=(PayloadError, Unauthorized))
     challenges = []
     if data:
@@ -22,6 +58,30 @@ def get_user_challenges(access_token: str) -> list:
         return challenges
 
 def verify_user_ip(access_token: str, answers: list) -> bool:
+    """Verify IP with the given answers
+
+    Args:
+        access_token (str): The session's access token
+        answers (list): The answers to the question
+    
+    Example:
+        
+        ```python
+        answers = [
+            (123, "foo"),
+            (456, "bar"),
+            (789, "baz")
+        ]
+        security.verify_user_ip(ACCESS_TOKEN, answers)
+        ```
+
+    Returns:
+        True if IP is secure else False
+
+    Raises:
+        Unauthorized: If access token is invalid
+        PayloadError: If access token is not formated correctly
+    """
     formatted_answers = []
     for answer in answers:
         formatted_answers.append({