allianceauth/docs/development/custom/framework/api.md

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:

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

# 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) if the EveCharacter has no user.

User API

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

# Alliance Auth
from allianceauth.framework.api.user import get_all_characters_from_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.

Given we have a User object called my_user and we want to get the main character:

# Alliance Auth
from allianceauth.framework.api.user import get_main_character_from_user

main_character = get_main_character_from_user(user=my_user)

Now, main_character is an EveCharacter object, or None if the user has no main character or the user is None.

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

# Alliance Auth
from allianceauth.framework.api.user import get_main_character_name_from_user

main_character = get_main_character_name_from_user(user=my_user)

Now, main_character is a string containing the user's main character name. If the user has no main character, the username will be returned. If the user is None, the sentinel username (see get_sentinel_user) will be returned.

get_sentinel_user

This function is useful in models when using User model-objects as foreign keys. Django needs to know what should happen to those relations when the user is being deleted. To keep the data, you can have Django map this to the sentinel user.

Import:

# Alliance Auth
from allianceauth.framework.api.user import get_sentinel_user

And later in your model:

creator = models.ForeignKey(
    to=User,
    on_delete=models.SET(get_sentinel_user),
)