diff --git a/allianceauth/framework/api/evecharacter.py b/allianceauth/framework/api/evecharacter.py new file mode 100644 index 00000000..f346fa59 --- /dev/null +++ b/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 diff --git a/docs/development/custom/aa-framework.md b/docs/development/custom/aa-framework.md index 071d9eb8..12084d2b 100644 --- a/docs/development/custom/aa-framework.md +++ b/docs/development/custom/aa-framework.md @@ -1,7 +1,12 @@ # AA Framework -To establish a unified style language throughout Alliance Auth and Community Apps, -Alliance Auth is providing its own CSS framework with a couple of CSS classes. +This section contains information about the Alliance Auth framework and how to use it. + +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 diff --git a/docs/development/custom/framework/api.md b/docs/development/custom/framework/api.md index a832a361..b182261b 100644 --- a/docs/development/custom/framework/api.md +++ b/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: