[ADD] get_all_characters_from_user function to User API

allianceauth/framework/api/evecharacter.py

@@ -15,7 +15,7 @@ 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
+    Get the main character for a given EveCharacter or None when no main character is set
 
     :param character:
     :type character:
@@ -37,7 +37,7 @@ def get_main_character_from_evecharacter(
 
 def get_user_from_evecharacter(character: EveCharacter) -> User:
     """
-    Get the user for an Evecharacter or the sentinel user when no user is found
+    Get the user for an EveCharacter or the sentinel user when no user is found
 
     :param character:
     :type character:

allianceauth/framework/api/user.py

@@ -6,17 +6,33 @@ from typing import Optional
 
 from django.contrib.auth.models import User
 
+from allianceauth.authentication.models import CharacterOwnership
 from allianceauth.eveonline.models import EveCharacter
 
 
-def get_sentinel_user() -> User:
+def get_all_characters_from_user(user: User) -> list[EveCharacter]:
     """
-    Get the sentinel user or create one
+    Get all characters from a user or an empty list
+    when no characters are found for the user or the user is None
 
+    :param user:
+    :type user:
     :return:
+    :rtype:
     """
 
-    return User.objects.get_or_create(username="deleted")[0]
+    if user is None:
+        return []
+
+    try:
+        characters = [
+            char.character for char in CharacterOwnership.objects.filter(user=User)
+        ]
+    except AttributeError:
+        return []
+
+    return characters
+
 
 def get_main_character_from_user(user: User) -> Optional[EveCharacter]:
     """
@@ -62,3 +78,13 @@ def get_main_character_name_from_user(user: User) -> str:
         return str(user)
 
     return username
+
+
+def get_sentinel_user() -> User:
+    """
+    Get the sentinel user or create one
+
+    :return:
+    """
+
+    return User.objects.get_or_create(username="deleted")[0]

docs/development/custom/framework/api.md

@@ -6,7 +6,7 @@ They are intended to be used in Alliance Auth itself as well as in the community
 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
+## EveCharacter API
 
 ### get_main_character_from_evecharacter
 
@@ -41,6 +41,22 @@ if the `EveCharacter` has no user.
 
 ## User API
 
+### get_all_characters_from_user
+
+This is to get all character objects (`EveCharacter`) of a user.
+
+Given we have a `User` object called `my_user` and we want to get all characters:
+
+```python
+# Alliance Auth
+from allianceauth.framework.api.user import get_all_characters_from_user
+
+characters = get_all_characters_from_user(user=my_user)
+```
+
+Now, `characters` is a `list` containing all `EveCharacter` objects of the user.
+If the user is `None`, an empty `list` will be returned.
+
 ### get_main_character_from_user
 
 This is to get the main character object (`EveCharacter`) of a user.