[ADD] Evecharacter API functions

allianceauth/framework/api/evecharacter.py

@@ -0,0 +1,57 @@
+"""
+Alliance Auth Evecharacter API
+"""
+
+from typing import Optional
+
+from django.contrib.auth.models import User
+
+from allianceauth.authentication.models import CharacterOwnership
+from allianceauth.eveonline.models import EveCharacter
+from allianceauth.framework.api.user import get_sentinel_user
+
+
+def get_main_character_from_evecharacter(
+    character: EveCharacter,
+) -> Optional[EveCharacter]:
+    """
+    Get the main character for a given Evecharacter or None when no main character is set
+
+    :param character:
+    :type character:
+    :return:
+    :rtype:
+    """
+
+    try:
+        userprofile = character.character_ownership.user.profile
+    except (
+        AttributeError,
+        EveCharacter.character_ownership.RelatedObjectDoesNotExist,
+        CharacterOwnership.user.RelatedObjectDoesNotExist,
+    ):
+        return None
+
+    return userprofile.main_character
+
+
+def get_user_from_evecharacter(character: EveCharacter) -> User:
+    """
+    Get the user for an Evecharacter or the sentinel user when no user is found
+
+    :param character:
+    :type character:
+    :return:
+    :rtype:
+    """
+
+    try:
+        userprofile = character.character_ownership.user.profile
+    except (
+        AttributeError,
+        EveCharacter.character_ownership.RelatedObjectDoesNotExist,
+        CharacterOwnership.user.RelatedObjectDoesNotExist,
+    ):
+        return get_sentinel_user()
+
+    return userprofile.user

docs/development/custom/aa-framework.md

@@ -1,7 +1,12 @@
 # AA Framework
 
-To establish a unified style language throughout Alliance Auth and Community Apps,
+This section contains information about the Alliance Auth framework and how to use it.
-Alliance Auth is providing its own CSS framework with a couple of CSS classes.
+
+The Alliance Auth framework is a collection of reusable Python code as well as CSS classes
+that are used throughout Alliance Auth. It is designed to be used by developers of community apps
+to make their lives easier.
+
+The Alliance Auth framework is split into several submodules, each of which is documented in its own section.
 
 :::{toctree}
 :maxdepth: 1

docs/development/custom/framework/api.md

@@ -1,5 +1,44 @@
 # Alliance Auth Helper-Functions API
 
+The following helper-functions are available in the `allianceauth.framework.api` module.
+They are intended to be used in Alliance Auth itself as well as in the community apps.
+
+These functions are intended to make the life of our community apps developer a little
+easier, so they don't have to reinvent the wheel all the time.
+
+## Evecharacter API
+
+### get_main_character_from_evecharacter
+
+This is to get the main character object (`EveCharacter`) of an `EveCharacter` object.
+
+Given we have an `EveCharacter` object called `my_evecharacter` and we want to get the main character:
+
+```python
+# Alliance Auth
+from allianceauth.framework.api.evecharacter import get_main_character_from_evecharacter
+
+main_character = get_main_character_from_evecharacter(character=my_evecharacter)
+```
+
+Now, `main_character` is an `EveCharacter` object, or `None` if the `EveCharacter` has no main character.
+
+### get_user_from_evecharacter
+
+This is to get the user object (`User`) of an `EveCharacter` object.
+
+Given we have an `EveCharacter` object called `my_evecharacter` and we want to get the user:
+
+```python
+# Alliance Auth
+from allianceauth.framework.api.evecharacter import get_user_from_evecharacter
+
+user = get_user_from_evecharacter(character=my_evecharacter)
+```
+
+Now, `user` is a `User` object, or the sentinel username (see [get_sentinel_user](#get-sentinel-user))
+if the `EveCharacter` has no user.
+
 ## User API
 
 ### get_main_character_from_user
@@ -20,7 +59,7 @@ character or the user is `None`.
 
 ### get_main_character_name_from_user
 
-This is to get the name of the main character of a user.
+This is to get the name of the main character from a user.
 
 Given we have a `User` object called `my_user` and we want to get the main character name: