[CHANGE] Improve get_all_characters_from_user

### Added

- `main_first` option to move the main character to the first position of the character list

### Changed

- Character list sorted alphabetically

allianceauth/framework/api/user.py

@@ -10,23 +10,38 @@ from allianceauth.authentication.models import CharacterOwnership
 from allianceauth.eveonline.models import EveCharacter
 
 
-def get_all_characters_from_user(user: User) -> list:
+def get_all_characters_from_user(user: User, main_first: bool = False) -> list:
     """
-    Get all characters from a user or an empty list
+    Get all characters from a user
-    when no characters are found for the user or the user is None
+    This function retrieves all characters associated with a given user, optionally ordering them
+    with the main character first.
+    If the user is None, an empty list is returned.
 
-    :param user:
+    :param user: The user whose characters are to be retrieved
-    :type user:
+    :type user: User
-    :return:
+    :param main_first: If True, the main character will be listed first
-    :rtype:
+    :type main_first: bool
+    :return: A list of EveCharacter objects associated with the user
+    :rtype: list[EveCharacter]
     """
 
     if user is None:
         return []
 
     try:
+        if main_first:
             characters = [
-            char.character for char in CharacterOwnership.objects.filter(user=user)
+                char.character
+                for char in CharacterOwnership.objects.filter(user=user).order_by(
+                    "-character__userprofile", "character__character_name"
+                )
+            ]
+        else:
+            characters = [
+                char.character
+                for char in CharacterOwnership.objects.filter(user=user).order_by(
+                    "character__character_name"
+                )
             ]
     except AttributeError:
         return []

docs/development/custom/framework/api.md

@@ -43,7 +43,7 @@ if the `EveCharacter` has no user.
 
 ### get_all_characters_from_user
 
-This is to get all character objects (`EveCharacter`) of a user.
+This is to get all character objects (`EveCharacter`) of a user (alphabetically sorted).
 
 Given we have a `User` object called `my_user` and we want to get all characters:
 
@@ -51,12 +51,16 @@ Given we have a `User` object called `my_user` and we want to get all characters
 # Alliance Auth
 from allianceauth.framework.api.user import get_all_characters_from_user
 
-characters = get_all_characters_from_user(user=my_user)
+characters = get_all_characters_from_user(user=my_user, main_first=False)
 ```
 
 Now, `characters` is a `list` containing all `EveCharacter` objects of the user.
 If the user is `None`, an empty `list` will be returned.
 
+The second parameter `main_first` is optional and defaults to `False`.
+If set to `True`, the function will return the main character as the first
+item in the list of characters.
+
 ### get_main_character_from_user
 
 This is to get the main character object (`EveCharacter`) of a user.