Checklists API Models

DestinyChecklistDefinition

Bases: ManifestModel, HashObject

By public demand, Checklists are loose sets of "things to do/things you have done" in Destiny that we were actually able to track. They include easter eggs you find in the world, unique chests you unlock, and other such data where the first time you do it is significant enough to be tracked, and you have the potential to "get them all". These may be account-wide, or may be per character. The status of these will be returned in related "Checklist" data coming down from API requests such as GetProfile or GetCharacter. Generally speaking, the items in a checklist can be completed in any order: we return an ordered list which only implies the way we are showing them in our own UI, and you can feel free to alter it as you wish. Note that, in the future, there will be something resembling the old D1 Record Books in at least some vague form. When that is created, it may be that it will supercede much or all of this Checklist data. It remains to be seen if that will be the case, so for now assume that the Checklists will still exist even after the release of D2: Forsaken.

None Attributes: display_properties: No description given by bungie. entries: The individual checklist items. Gotta catch 'em all. hash: The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally. When entities refer to each other in Destiny content, it is this hash that they are referring to. index: The index of the entity as it was found in the investment tables. redacted: If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry! scope: Indicates whether you will find this checklist on the Profile or Character components. view_action_string: A localized string prompting you to view the checklist.

Source code in src/bungio/models/bungie/destiny/definitions/checklists.py

@custom_define()
class DestinyChecklistDefinition(ManifestModel, HashObject):
    """
    By public demand, Checklists are loose sets of "things to do/things you have done" in Destiny that we were actually able to track. They include easter eggs you find in the world, unique chests you unlock, and other such data where the first time you do it is significant enough to be tracked, and you have the potential to "get them all". These may be account-wide, or may be per character. The status of these will be returned in related "Checklist" data coming down from API requests such as GetProfile or GetCharacter. Generally speaking, the items in a checklist can be completed in any order: we return an ordered list which only implies the way we are showing them in our own UI, and you can feel free to alter it as you wish. Note that, in the future, there will be something resembling the old D1 Record Books in at least some vague form. When that is created, it may be that it will supercede much or all of this Checklist data. It remains to be seen if that will be the case, so for now assume that the Checklists will still exist even after the release of D2: Forsaken.

    None
    Attributes:
        display_properties: _No description given by bungie._
        entries: The individual checklist items. Gotta catch 'em all.
        hash: The unique identifier for this entity. Guaranteed to be unique for the type of entity, but not globally. When entities refer to each other in Destiny content, it is this hash that they are referring to.
        index: The index of the entity as it was found in the investment tables.
        redacted: If this is true, then there is an entity with this identifier/type combination, but BNet is not yet allowed to show it. Sorry!
        scope: Indicates whether you will find this checklist on the Profile or Character components.
        view_action_string: A localized string prompting you to view the checklist.
    """

    display_properties: "DestinyDisplayPropertiesDefinition" = custom_field()
    entries: list["DestinyChecklistEntryDefinition"] = custom_field(
        metadata={"type": """list[DestinyChecklistEntryDefinition]"""}
    )
    index: int = custom_field()
    redacted: bool = custom_field()
    scope: Union["DestinyScope", int] = custom_field(converter=enum_converter("DestinyScope"))
    view_action_string: str = custom_field()

_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

DestinyChecklistEntryDefinition

Bases: BaseModel, HashObject

The properties of an individual checklist item. Note that almost everything is optional: it is highly variable what kind of data we'll actually be able to return: at times we may have no other relationships to entities at all. Whatever UI you build, do it with the knowledge that any given entry might not actually be able to be associated with some other Destiny entity.

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
activity_hash	int	No description given by bungie.
bubble_hash	int	Note that a Bubble's hash doesn't uniquely identify a "top level" entity in Destiny. Only the combination of location and bubble can uniquely identify a place in the world of Destiny: so if bubbleHash is populated, locationHash must too be populated for it to have any meaning. You can use this property if it is populated to look up the DestinyLocationDefinition's associated .locationReleases[].activityBubbleName property.
destination_hash	int	No description given by bungie.
display_properties	DestinyDisplayPropertiesDefinition	Even if no other associations exist, we will give you something for display properties. In cases where we have no associated entities, it may be as simple as a numerical identifier.
hash	int	The identifier for this Checklist entry. Guaranteed unique only within this Checklist Definition, and not globally/for all checklists.
item_hash	int	No description given by bungie.
location_hash	int	No description given by bungie.
scope	Union[DestinyScope, int]	The scope at which this specific entry can be computed.
vendor_hash	int	No description given by bungie.
vendor_interaction_index	int	No description given by bungie.
manifest_activity_hash	Optional[DestinyActivityDefinition]	Manifest information for activity_hash
manifest_destination_hash	Optional[DestinyDestinationDefinition]	Manifest information for destination_hash
manifest_item_hash	Optional[DestinyInventoryItemDefinition]	Manifest information for item_hash
manifest_location_hash	Optional[DestinyLocationDefinition]	Manifest information for location_hash
manifest_vendor_hash	Optional[DestinyVendorDefinition]	Manifest information for vendor_hash

Source code in src/bungio/models/bungie/destiny/definitions/checklists.py

@custom_define()
class DestinyChecklistEntryDefinition(BaseModel, HashObject):
    """
    The properties of an individual checklist item. Note that almost everything is optional: it is *highly* variable what kind of data we'll actually be able to return: at times we may have no other relationships to entities at all. Whatever UI you build, do it with the knowledge that any given entry might not actually be able to be associated with some other Destiny entity.

    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:
        activity_hash: _No description given by bungie._
        bubble_hash: Note that a Bubble's hash doesn't uniquely identify a "top level" entity in Destiny. Only the combination of location and bubble can uniquely identify a place in the world of Destiny: so if bubbleHash is populated, locationHash must too be populated for it to have any meaning. You can use this property if it is populated to look up the DestinyLocationDefinition's associated .locationReleases[].activityBubbleName property.
        destination_hash: _No description given by bungie._
        display_properties: Even if no other associations exist, we will give you *something* for display properties. In cases where we have no associated entities, it may be as simple as a numerical identifier.
        hash: The identifier for this Checklist entry. Guaranteed unique only within this Checklist Definition, and not globally/for all checklists.
        item_hash: _No description given by bungie._
        location_hash: _No description given by bungie._
        scope: The scope at which this specific entry can be computed.
        vendor_hash: _No description given by bungie._
        vendor_interaction_index: _No description given by bungie._
        manifest_activity_hash: Manifest information for `activity_hash`
        manifest_destination_hash: Manifest information for `destination_hash`
        manifest_item_hash: Manifest information for `item_hash`
        manifest_location_hash: Manifest information for `location_hash`
        manifest_vendor_hash: Manifest information for `vendor_hash`
    """

    activity_hash: int = custom_field()
    bubble_hash: int = custom_field()
    destination_hash: int = custom_field()
    display_properties: "DestinyDisplayPropertiesDefinition" = custom_field()
    item_hash: int = custom_field()
    location_hash: int = custom_field()
    scope: Union["DestinyScope", int] = custom_field(converter=enum_converter("DestinyScope"))
    vendor_hash: int = custom_field()
    vendor_interaction_index: int = custom_field()
    manifest_activity_hash: Optional["DestinyActivityDefinition"] = custom_field(default=None)
    manifest_destination_hash: Optional["DestinyDestinationDefinition"] = custom_field(default=None)
    manifest_item_hash: Optional["DestinyInventoryItemDefinition"] = custom_field(default=None)
    manifest_location_hash: Optional["DestinyLocationDefinition"] = custom_field(default=None)
    manifest_vendor_hash: Optional["DestinyVendorDefinition"] = 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