Profiles API Models

DestinyProfileComponent

Bases: BaseModel

The most essential summary information about a Profile (in Destiny 1, we called these "Accounts").

Manifest Information

This model has some attributes which can be filled with additional information found in the manifest (manifest_...). Without additional work, these attributes will be None, since they require additional requests and database lookups.

To fill the manifest dependent attributes, either:

• Run await ThisClass.fetch_manifest_information(), see here
• Set Client.always_return_manifest_information to True, see here

Attributes:

Name	Type	Description
active_event_card_hash	int	If populated, this is a reference to the event card that is currently active.
character_ids	list[int]	A list of the character IDs, for further querying on your part.
current_guardian_rank	int	The 'current' Guardian Rank value, which starts at rank 1. This rank value will drop at the start of a new season to your 'renewed' rank from the previous season.
current_season_hash	int	If populated, this is a reference to the season that is currently active.
current_season_pass_hash	int	If populated, this is a reference to the season pass that is currently active.
current_season_reward_power_cap	int	If populated, this is the reward power cap for the current season.
date_last_played	datetime	The last time the user played with any character on this Profile.
event_card_hashes_owned	list[int]	A list of hashes for event cards that a profile owns. Unlike most values in versionsOwned, these stay with the profile across all platforms.
lifetime_highest_guardian_rank	int	The 'lifetime highest' Guardian Rank value, which starts at rank 1. This rank value should never go down.
renewed_guardian_rank	int	The seasonal 'renewed' Guardian Rank value. This rank value resets at the start of each new season to the highest-earned non-advanced rank.
season_hashes	list[int]	A list of seasons that this profile owns. Unlike versionsOwned, these stay with the profile across Platforms, and thus will be valid. It turns out that Stadia Pro subscriptions will give access to seasons but only while playing on Stadia and with an active subscription. So some users (users who have Stadia Pro but choose to play on some other platform) won't see these as available: it will be whatever seasons are available for the platform on which they last played.
season_pass_hashes	list[int]	A list of season passes aka reward passes that this profile owns. Unlike versionsOwned, these stay with the profile across Platforms, and thus will be valid.
user_info	UserInfoCard	If you need to render the Profile (their platform name, icon, etc...) somewhere, this property contains that information.
versions_owned	Union[DestinyGameVersions, int]	If you want to know what expansions they own, this will contain that data. IMPORTANT: This field may not return the data you're interested in for Cross-Saved users. It returns the last ownership data we saw for this account - which is to say, what they've purchased on the platform on which they last played, which now could be a different platform. If you don't care about per-platform ownership and only care about whatever platform it seems they are playing on most recently, then this should be "good enough." Otherwise, this should be considered deprecated. We do not have a good alternative to provide at this time with platform specific ownership data for DLC.
manifest_active_event_card_hash	Optional[DestinyEventCardDefinition]	Manifest information for active_event_card_hash
manifest_current_guardian_rank	Optional[DestinyGuardianRankDefinition]	Manifest information for current_guardian_rank
manifest_current_season_hash	Optional[DestinySeasonDefinition]	Manifest information for current_season_hash
manifest_current_season_pass_hash	Optional[DestinySeasonPassDefinition]	Manifest information for current_season_pass_hash
manifest_lifetime_highest_guardian_rank	Optional[DestinyGuardianRankDefinition]	Manifest information for lifetime_highest_guardian_rank
manifest_renewed_guardian_rank	Optional[DestinyGuardianRankDefinition]	Manifest information for renewed_guardian_rank

Source code in src/bungio/models/bungie/destiny/entities/profiles.py

@custom_define()
class DestinyProfileComponent(BaseModel):
    """
    The most essential summary information about a Profile (in Destiny 1, we called these "Accounts").

    Tip: Manifest Information
        This model has some attributes which can be filled with additional information found in the manifest (`manifest_...`).
        Without additional work, these attributes will be `None`, since they require additional requests and database lookups.

        To fill the manifest dependent attributes, either:

        - Run `await ThisClass.fetch_manifest_information()`, see [here](/API Reference/Models/base)
        - Set `Client.always_return_manifest_information` to `True`, see [here](/API Reference/client)

    Attributes:
        active_event_card_hash: If populated, this is a reference to the event card that is currently active.
        character_ids: A list of the character IDs, for further querying on your part.
        current_guardian_rank: The 'current' Guardian Rank value, which starts at rank 1. This rank value will drop at the start of a new season to your 'renewed' rank from the previous season.
        current_season_hash: If populated, this is a reference to the season that is currently active.
        current_season_pass_hash: If populated, this is a reference to the season pass that is currently active.
        current_season_reward_power_cap: If populated, this is the reward power cap for the current season.
        date_last_played: The last time the user played with any character on this Profile.
        event_card_hashes_owned: A list of hashes for event cards that a profile owns. Unlike most values in versionsOwned, these stay with the profile across all platforms.
        lifetime_highest_guardian_rank: The 'lifetime highest' Guardian Rank value, which starts at rank 1. This rank value should never go down.
        renewed_guardian_rank: The seasonal 'renewed' Guardian Rank value. This rank value resets at the start of each new season to the highest-earned non-advanced rank.
        season_hashes: A list of seasons that this profile owns. Unlike versionsOwned, these stay with the profile across Platforms, and thus will be valid.  It turns out that Stadia Pro subscriptions will give access to seasons but only while playing on Stadia and with an active subscription. So some users (users who have Stadia Pro but choose to play on some other platform) won't see these as available: it will be whatever seasons are available for the platform on which they last played.
        season_pass_hashes: A list of season passes aka reward passes that this profile owns. Unlike versionsOwned, these stay with the profile across Platforms, and thus will be valid.
        user_info: If you need to render the Profile (their platform name, icon, etc...) somewhere, this property contains that information.
        versions_owned: If you want to know what expansions they own, this will contain that data.  IMPORTANT: This field may not return the data you're interested in for Cross-Saved users. It returns the last ownership data we saw for this account - which is to say, what they've purchased on the platform on which they last played, which now could be a different platform.  If you don't care about per-platform ownership and only care about whatever platform it seems they are playing on most recently, then this should be "good enough." Otherwise, this should be considered deprecated. We do not have a good alternative to provide at this time with platform specific ownership data for DLC.
        manifest_active_event_card_hash: Manifest information for `active_event_card_hash`
        manifest_current_guardian_rank: Manifest information for `current_guardian_rank`
        manifest_current_season_hash: Manifest information for `current_season_hash`
        manifest_current_season_pass_hash: Manifest information for `current_season_pass_hash`
        manifest_lifetime_highest_guardian_rank: Manifest information for `lifetime_highest_guardian_rank`
        manifest_renewed_guardian_rank: Manifest information for `renewed_guardian_rank`
    """

    active_event_card_hash: int = custom_field()
    character_ids: list[int] = custom_field(metadata={"type": """list[int]"""})
    current_guardian_rank: int = custom_field()
    current_season_hash: int = custom_field()
    current_season_pass_hash: int = custom_field()
    current_season_reward_power_cap: int = custom_field()
    date_last_played: datetime = custom_field()
    event_card_hashes_owned: list[int] = custom_field(metadata={"type": """list[int]"""})
    lifetime_highest_guardian_rank: int = custom_field()
    renewed_guardian_rank: int = custom_field()
    season_hashes: list[int] = custom_field(metadata={"type": """list[int]"""})
    season_pass_hashes: list[int] = custom_field(metadata={"type": """list[int]"""})
    user_info: "UserInfoCard" = custom_field()
    versions_owned: Union["DestinyGameVersions", int] = custom_field(converter=enum_converter("DestinyGameVersions"))
    manifest_active_event_card_hash: Optional["DestinyEventCardDefinition"] = custom_field(default=None)
    manifest_current_guardian_rank: Optional["DestinyGuardianRankDefinition"] = custom_field(default=None)
    manifest_current_season_hash: Optional["DestinySeasonDefinition"] = custom_field(default=None)
    manifest_current_season_pass_hash: Optional["DestinySeasonPassDefinition"] = custom_field(default=None)
    manifest_lifetime_highest_guardian_rank: Optional["DestinyGuardianRankDefinition"] = custom_field(default=None)
    manifest_renewed_guardian_rank: Optional["DestinyGuardianRankDefinition"] = custom_field(default=None)

_convert_to_bungie_case(string) cached staticmethod

Convert a string to how it is represented by bungie: my_name_string -> myNameString

Parameters:

Name	Type	Description	Default
string	str	The og string	required

Returns:

Type	Description
str	The bungie string

Source code in src/bungio/models/base.py

@staticmethod
@functools.cache
def _convert_to_bungie_case(string: str) -> str:
    """
    Convert a string to how it is represented by bungie: my_name_string -> myNameString

    Args:
        string: The og string

    Returns:
        The bungie string
    """

    if "_" not in string:
        return string
    else:
        split = string.split("_")
        return "".join((split[0], *(s.capitalize() for s in split[1:])))

fetch_manifest_information(include=None, exclude=None, _cache=None) async

Fill the model in-place with information from the manifest.

Example

Fill every attribute

model: DestinyHistoricalStatsActivity
await model.fetch_manifest_information()
assert model.manifest_director_activity_hash is not None
assert model.manifest_reference_id is not None

Fill only some attribute

model: DestinyHistoricalStatsActivity
await model.fetch_manifest_information(include=["manifest_director_activity_hash"])
assert model.manifest_director_activity_hash is not None
assert model.manifest_reference_id is None

model: DestinyHistoricalStatsActivity
await model.fetch_manifest_information(exclude=["manifest_director_activity_hash"])
assert model.manifest_director_activity_hash is None
assert model.manifest_reference_id is not None

Parameters:

Name	Type	Description	Default
include	Optional[list[str]]	A list of attributes you want to include. Excludes everything not mentioned	None
exclude	Optional[list[str]]	A list of attributes you want to exclude. Includes everything not mentioned	None

Source code in src/bungio/models/base.py

async def fetch_manifest_information(
    self, include: Optional[list[str]] = None, exclude: Optional[list[str]] = None, _cache: Optional[dict] = None
):
    """
    Fill the model in-place with information from the manifest.

    Example:
        Fill every attribute
        ```py
        model: DestinyHistoricalStatsActivity
        await model.fetch_manifest_information()
        assert model.manifest_director_activity_hash is not None
        assert model.manifest_reference_id is not None
        ```

        Fill only some attribute
        ```py
        model: DestinyHistoricalStatsActivity
        await model.fetch_manifest_information(include=["manifest_director_activity_hash"])
        assert model.manifest_director_activity_hash is not None
        assert model.manifest_reference_id is None
        ```
        ```py
        model: DestinyHistoricalStatsActivity
        await model.fetch_manifest_information(exclude=["manifest_director_activity_hash"])
        assert model.manifest_director_activity_hash is None
        assert model.manifest_reference_id is not None
        ```

    Args:
        include: A list of attributes you want to include. Excludes everything not mentioned
        exclude:  A list of attributes you want to exclude. Includes everything not mentioned
    """

    if not isinstance(self._client.manifest_storage, AsyncEngine):
        raise ValueError("Client.manifest_storage must be set up to use this")

    if not _cache:
        _cache = {}

    class_definition = attrs.fields_dict(type(self))  # noqa

    # loop through the class attributes
    for name in self.__dir__():
        if name.startswith("__"):
            continue

        if include and name not in include:
            continue
        if exclude and name in exclude:
            continue

        # manifest entries
        if name.startswith("manifest_"):
            striped_name = name.removeprefix("manifest_")
            value = getattr(self, striped_name)

            if value is MISSING:
                return

            # check the cache to avoid infinite recursion
            if cached := _cache.get(value, None):
                manifest_value = cached

            else:
                attr_definition = class_definition[name]
                manifest_class_name = attr_definition.type.__str__().removesuffix("')]").split("'")[-1]
                manifest_value = await self._client.manifest.fetch(
                    manifest_class=getattr(models, manifest_class_name), value=value
                )

                _cache[value] = manifest_value

                # check if the model has manifest models itself
                if manifest_value:
                    await manifest_value.fetch_manifest_information(_cache=_cache)

            setattr(self, name, manifest_value)

        # sub models which may have manifest entries too
        elif hasattr((value := getattr(self, name)), "fetch_manifest_information"):
            await value.fetch_manifest_information(_cache=_cache)

from_dict(data, client, recursive=False, *args, **kwargs) async classmethod

Convert json data to this model

Parameters:

Name	Type	Description	Default
data	dict	The json representation of the model, usually received by bungie	required
client	'Client'	The client obj	required
recursive	bool	If this was called recursively	False

Returns:

Type	Description
BaseModel	The model

Source code in src/bungio/models/base.py

@classmethod
async def from_dict(cls, data: dict, client: "Client", recursive: bool = False, *args, **kwargs) -> BaseModel:
    """
    Convert json data to this model

    Args:
        data: The json representation of the model, usually received by bungie
        client: The client obj
        recursive: If this was called recursively

    Returns:
        The model
    """

    if isinstance(data, cls):
        return data

    if not isinstance(data, dict):
        raise ValueError

    if "Response" in data:
        data = data["Response"]

    # also use the kwargs as data
    data = kwargs | data
    data = cls.process_dict(data=data, client=client)

    prepared = {}
    for name, field in attrs.fields_dict(cls).items():
        if field.init and name != "_client":
            default = field.default

            # get the value we want. This also skips the manifest_... entries since they have no value and a default
            bungie_name = cls._convert_to_bungie_case(name)
            value = data.get(bungie_name, attrs.NOTHING)

            # bungie is veeery inconsistent and sometimes like to start their params with an upper case for some reason
            # only sometimes tho :)
            if value is attrs.NOTHING:
                value = data.get(f"{bungie_name[0].capitalize()}{bungie_name[1:]}", attrs.NOTHING)

            # sadly bungie sometimes does not return info without marking that fact in the api specs
            if value is attrs.NOTHING and default is attrs.NOTHING:
                default = MISSING

            if value is attrs.NOTHING:
                value = default

            else:
                value = await cls._convert_to_type(
                    field_type=field.type, field_metadata=field.metadata, value=value, client=client
                )

            # set the attr
            prepared[name] = value

    res = cls(**prepared)  # noqa

    # fill the manifest information
    if not recursive and res._client.always_return_manifest_information:
        await res.fetch_manifest_information()

    return res

process_dict(data, client, *args, **kwargs) staticmethod

Model specific cleanup

Parameters:

Name	Type	Description	Default
data	dict	The json representation of the model, usually received by bungie	required
client	'Client'	The client obj	required

Returns:

Type	Description
dict	Clean json

Source code in src/bungio/models/base.py

@staticmethod
def process_dict(data: dict, client: "Client", *args, **kwargs) -> dict:
    """
    Model specific cleanup

    Args:
        data: The json representation of the model, usually received by bungie
        client: The client obj

    Returns:
        Clean json
    """
    return data

to_dict(_return_to_bungie_case=True)

Convert the model into a dict representation bungie accepts

Returns:

Type	Description
dict	A dict which can be sent to bungie

Source code in src/bungio/models/base.py

def to_dict(self, _return_to_bungie_case: bool = True) -> dict:
    """
    Convert the model into a dict representation bungie accepts

    Returns:
        A dict which can be sent to bungie
    """

    result = {}

    for name, field in attrs.fields_dict(type(self)).items():
        if name.startswith("_") or name.startswith("manifest_"):
            continue

        value = getattr(self, name)
        if _return_to_bungie_case:
            name = self._convert_to_bungie_case(name)

        if inspect.ismethod(value) or inspect.isfunction(value):
            continue

        elif isinstance(value, dict):
            raise NotImplementedError(
                "Nested dict conversion is not currently implemented, since bungie does never require that info"
            )

        elif isinstance(value, list):
            list_results = []
            for entry in value:
                if hasattr(entry, "to_dict"):
                    list_results.append(entry.to_dict())
                else:
                    list_results.append(entry)

            result[name] = list_results

        else:
            if hasattr(value, "to_dict"):
                result[name] = value.to_dict()
            else:
                # convert to string if they are int64
                if field.metadata.get("int64", None) is True:
                    value = str(value)

                result[name] = value

    return result

DestinyVendorReceiptsComponent

Bases: BaseModel

For now, this isn't used for much: it's a record of the recent refundable purchases that the user has made. In the future, it could be used for providing refunds/buyback via the API. Wouldn't that be fun?

None Attributes: receipts: The receipts for refundable purchases made at a vendor.

Source code in src/bungio/models/bungie/destiny/entities/profiles.py

@custom_define()
class DestinyVendorReceiptsComponent(BaseModel):
    """
    For now, this isn't used for much: it's a record of the recent refundable purchases that the user has made. In the future, it could be used for providing refunds/buyback via the API. Wouldn't that be fun?

    None
    Attributes:
        receipts: The receipts for refundable purchases made at a vendor.
    """

    receipts: list["DestinyVendorReceipt"] = custom_field(metadata={"type": """list[DestinyVendorReceipt]"""})

_convert_to_bungie_case(string) cached staticmethod

Convert a string to how it is represented by bungie: my_name_string -> myNameString

Parameters:

Name	Type	Description	Default
string	str	The og string	required

Returns:

Type	Description
str	The bungie string

Source code in src/bungio/models/base.py

@staticmethod
@functools.cache
def _convert_to_bungie_case(string: str) -> str:
    """
    Convert a string to how it is represented by bungie: my_name_string -> myNameString

    Args:
        string: The og string

    Returns:
        The bungie string
    """

    if "_" not in string:
        return string
    else:
        split = string.split("_")
        return "".join((split[0], *(s.capitalize() for s in split[1:])))

fetch_manifest_information(include=None, exclude=None, _cache=None) async

Fill the model in-place with information from the manifest.

Example

Fill every attribute

model: DestinyHistoricalStatsActivity
await model.fetch_manifest_information()
assert model.manifest_director_activity_hash is not None
assert model.manifest_reference_id is not None

Fill only some attribute

model: DestinyHistoricalStatsActivity
await model.fetch_manifest_information(include=["manifest_director_activity_hash"])
assert model.manifest_director_activity_hash is not None
assert model.manifest_reference_id is None

model: DestinyHistoricalStatsActivity
await model.fetch_manifest_information(exclude=["manifest_director_activity_hash"])
assert model.manifest_director_activity_hash is None
assert model.manifest_reference_id is not None

Parameters:

Name	Type	Description	Default
include	Optional[list[str]]	A list of attributes you want to include. Excludes everything not mentioned	None
exclude	Optional[list[str]]	A list of attributes you want to exclude. Includes everything not mentioned	None

Source code in src/bungio/models/base.py

async def fetch_manifest_information(
    self, include: Optional[list[str]] = None, exclude: Optional[list[str]] = None, _cache: Optional[dict] = None
):
    """
    Fill the model in-place with information from the manifest.

    Example:
        Fill every attribute
        ```py
        model: DestinyHistoricalStatsActivity
        await model.fetch_manifest_information()
        assert model.manifest_director_activity_hash is not None
        assert model.manifest_reference_id is not None
        ```

        Fill only some attribute
        ```py
        model: DestinyHistoricalStatsActivity
        await model.fetch_manifest_information(include=["manifest_director_activity_hash"])
        assert model.manifest_director_activity_hash is not None
        assert model.manifest_reference_id is None
        ```
        ```py
        model: DestinyHistoricalStatsActivity
        await model.fetch_manifest_information(exclude=["manifest_director_activity_hash"])
        assert model.manifest_director_activity_hash is None
        assert model.manifest_reference_id is not None
        ```

    Args:
        include: A list of attributes you want to include. Excludes everything not mentioned
        exclude:  A list of attributes you want to exclude. Includes everything not mentioned
    """

    if not isinstance(self._client.manifest_storage, AsyncEngine):
        raise ValueError("Client.manifest_storage must be set up to use this")

    if not _cache:
        _cache = {}

    class_definition = attrs.fields_dict(type(self))  # noqa

    # loop through the class attributes
    for name in self.__dir__():
        if name.startswith("__"):
            continue

        if include and name not in include:
            continue
        if exclude and name in exclude:
            continue

        # manifest entries
        if name.startswith("manifest_"):
            striped_name = name.removeprefix("manifest_")
            value = getattr(self, striped_name)

            if value is MISSING:
                return

            # check the cache to avoid infinite recursion
            if cached := _cache.get(value, None):
                manifest_value = cached

            else:
                attr_definition = class_definition[name]
                manifest_class_name = attr_definition.type.__str__().removesuffix("')]").split("'")[-1]
                manifest_value = await self._client.manifest.fetch(
                    manifest_class=getattr(models, manifest_class_name), value=value
                )

                _cache[value] = manifest_value

                # check if the model has manifest models itself
                if manifest_value:
                    await manifest_value.fetch_manifest_information(_cache=_cache)

            setattr(self, name, manifest_value)

        # sub models which may have manifest entries too
        elif hasattr((value := getattr(self, name)), "fetch_manifest_information"):
            await value.fetch_manifest_information(_cache=_cache)

from_dict(data, client, recursive=False, *args, **kwargs) async classmethod

Convert json data to this model

Parameters:

Name	Type	Description	Default
data	dict	The json representation of the model, usually received by bungie	required
client	'Client'	The client obj	required
recursive	bool	If this was called recursively	False

Returns:

Type	Description
BaseModel	The model

Source code in src/bungio/models/base.py

@classmethod
async def from_dict(cls, data: dict, client: "Client", recursive: bool = False, *args, **kwargs) -> BaseModel:
    """
    Convert json data to this model

    Args:
        data: The json representation of the model, usually received by bungie
        client: The client obj
        recursive: If this was called recursively

    Returns:
        The model
    """

    if isinstance(data, cls):
        return data

    if not isinstance(data, dict):
        raise ValueError

    if "Response" in data:
        data = data["Response"]

    # also use the kwargs as data
    data = kwargs | data
    data = cls.process_dict(data=data, client=client)

    prepared = {}
    for name, field in attrs.fields_dict(cls).items():
        if field.init and name != "_client":
            default = field.default

            # get the value we want. This also skips the manifest_... entries since they have no value and a default
            bungie_name = cls._convert_to_bungie_case(name)
            value = data.get(bungie_name, attrs.NOTHING)

            # bungie is veeery inconsistent and sometimes like to start their params with an upper case for some reason
            # only sometimes tho :)
            if value is attrs.NOTHING:
                value = data.get(f"{bungie_name[0].capitalize()}{bungie_name[1:]}", attrs.NOTHING)

            # sadly bungie sometimes does not return info without marking that fact in the api specs
            if value is attrs.NOTHING and default is attrs.NOTHING:
                default = MISSING

            if value is attrs.NOTHING:
                value = default

            else:
                value = await cls._convert_to_type(
                    field_type=field.type, field_metadata=field.metadata, value=value, client=client
                )

            # set the attr
            prepared[name] = value

    res = cls(**prepared)  # noqa

    # fill the manifest information
    if not recursive and res._client.always_return_manifest_information:
        await res.fetch_manifest_information()

    return res

process_dict(data, client, *args, **kwargs) staticmethod

Model specific cleanup

Parameters:

Name	Type	Description	Default
data	dict	The json representation of the model, usually received by bungie	required
client	'Client'	The client obj	required

Returns:

Type	Description
dict	Clean json

Source code in src/bungio/models/base.py

@staticmethod
def process_dict(data: dict, client: "Client", *args, **kwargs) -> dict:
    """
    Model specific cleanup

    Args:
        data: The json representation of the model, usually received by bungie
        client: The client obj

    Returns:
        Clean json
    """
    return data

to_dict(_return_to_bungie_case=True)

Convert the model into a dict representation bungie accepts

Returns:

Type	Description
dict	A dict which can be sent to bungie

Source code in src/bungio/models/base.py

def to_dict(self, _return_to_bungie_case: bool = True) -> dict:
    """
    Convert the model into a dict representation bungie accepts

    Returns:
        A dict which can be sent to bungie
    """

    result = {}

    for name, field in attrs.fields_dict(type(self)).items():
        if name.startswith("_") or name.startswith("manifest_"):
            continue

        value = getattr(self, name)
        if _return_to_bungie_case:
            name = self._convert_to_bungie_case(name)

        if inspect.ismethod(value) or inspect.isfunction(value):
            continue

        elif isinstance(value, dict):
            raise NotImplementedError(
                "Nested dict conversion is not currently implemented, since bungie does never require that info"
            )

        elif isinstance(value, list):
            list_results = []
            for entry in value:
                if hasattr(entry, "to_dict"):
                    list_results.append(entry.to_dict())
                else:
                    list_results.append(entry)

            result[name] = list_results

        else:
            if hasattr(value, "to_dict"):
                result[name] = value.to_dict()
            else:
                # convert to string if they are int64
                if field.metadata.get("int64", None) is True:
                    value = str(value)

                result[name] = value

    return result