Progression API Models

DestinyFactionProgression

Bases: BaseModel

Mostly for historical purposes, we segregate Faction progressions from other progressions. This is just a DestinyProgression with a shortcut for finding the DestinyFactionDefinition of the faction related to the progression.

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
current_progress	int	This is the total amount of progress obtained overall for this progression (for instance, the total amount of Character Level experience earned)
current_reset_count	int	The number of resets of this progression you've executed this season, if applicable to this progression.
daily_limit	int	If this progression has a daily limit, this is that limit.
daily_progress	int	The amount of progress earned today for this progression.
faction_hash	int	The hash identifier of the Faction related to this progression. Use it to look up the DestinyFactionDefinition for more rendering info.
faction_vendor_index	int	The index of the Faction vendor that is currently available. Will be set to -1 if no vendors are available.
level	int	This is the level of the progression (for instance, the Character Level).
level_cap	int	This is the maximum possible level you can achieve for this progression (for example, the maximum character level obtainable)
next_level_at	int	The total amount of progression (i.e. "Experience") needed in order to reach the next level.
progress_to_next_level	int	The amount of progression (i.e. "Experience") needed to reach the next level of this Progression. Jeez, progression is such an overloaded word.
progression_hash	int	The hash identifier of the Progression in question. Use it to look up the DestinyProgressionDefinition in static data.
reward_item_socket_override_states	dict[int, DestinyProgressionRewardItemSocketOverrideState]	Information about items stats and states that have socket overrides, if there is any data for it.
reward_item_states	list[Union[DestinyProgressionRewardItemState, int]]	Information about historical rewards for this progression, if there is any data for it.
season_resets	list[DestinyProgressionResetEntry]	Information about historical resets of this progression, if there is any data for it.
step_index	int	Progressions define their levels in "steps". Since the last step may be repeatable, the user may be at a higher level than the actual Step achieved in the progression. Not necessarily useful, but potentially interesting for those cruising the API. Relate this to the "steps" property of the DestinyProgression to see which step the user is on, if you care about that. (Note that this is Content Version dependent since it refers to indexes.)
weekly_limit	int	If this progression has a weekly limit, this is that limit.
weekly_progress	int	The amount of progress earned toward this progression in the current week.
manifest_faction_hash	Optional[DestinyFactionDefinition]	Manifest information for faction_hash
manifest_progression_hash	Optional[DestinyProgressionDefinition]	Manifest information for progression_hash

Source code in src/bungio/models/bungie/destiny/progression.py

@custom_define()
class DestinyFactionProgression(BaseModel):
    """
    Mostly for historical purposes, we segregate Faction progressions from other progressions. This is just a DestinyProgression with a shortcut for finding the DestinyFactionDefinition of the faction related to the progression.

    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:
        current_progress: This is the total amount of progress obtained overall for this progression (for instance, the total amount of Character Level experience earned)
        current_reset_count: The number of resets of this progression you've executed this season, if applicable to this progression.
        daily_limit: If this progression has a daily limit, this is that limit.
        daily_progress: The amount of progress earned today for this progression.
        faction_hash: The hash identifier of the Faction related to this progression. Use it to look up the DestinyFactionDefinition for more rendering info.
        faction_vendor_index: The index of the Faction vendor that is currently available. Will be set to -1 if no vendors are available.
        level: This is the level of the progression (for instance, the Character Level).
        level_cap: This is the maximum possible level you can achieve for this progression (for example, the maximum character level obtainable)
        next_level_at: The total amount of progression (i.e. "Experience") needed in order to reach the next level.
        progress_to_next_level: The amount of progression (i.e. "Experience") needed to reach the next level of this Progression. Jeez, progression is such an overloaded word.
        progression_hash: The hash identifier of the Progression in question. Use it to look up the DestinyProgressionDefinition in static data.
        reward_item_socket_override_states: Information about items stats and states that have socket overrides, if there is any data for it.
        reward_item_states: Information about historical rewards for this progression, if there is any data for it.
        season_resets: Information about historical resets of this progression, if there is any data for it.
        step_index: Progressions define their levels in "steps". Since the last step may be repeatable, the user may be at a higher level than the actual Step achieved in the progression. Not necessarily useful, but potentially interesting for those cruising the API. Relate this to the "steps" property of the DestinyProgression to see which step the user is on, if you care about that. (Note that this is Content Version dependent since it refers to indexes.)
        weekly_limit: If this progression has a weekly limit, this is that limit.
        weekly_progress: The amount of progress earned toward this progression in the current week.
        manifest_faction_hash: Manifest information for `faction_hash`
        manifest_progression_hash: Manifest information for `progression_hash`
    """

    current_progress: int = custom_field()
    current_reset_count: int = custom_field()
    daily_limit: int = custom_field()
    daily_progress: int = custom_field()
    faction_hash: int = custom_field()
    faction_vendor_index: int = custom_field()
    level: int = custom_field()
    level_cap: int = custom_field()
    next_level_at: int = custom_field()
    progress_to_next_level: int = custom_field()
    progression_hash: int = custom_field()
    reward_item_socket_override_states: dict[int, "DestinyProgressionRewardItemSocketOverrideState"] = custom_field(
        metadata={"type": """dict[int, DestinyProgressionRewardItemSocketOverrideState]"""}
    )
    reward_item_states: list[Union["DestinyProgressionRewardItemState", int]] = custom_field(
        converter=enum_converter("DestinyProgressionRewardItemState")
    )
    season_resets: list["DestinyProgressionResetEntry"] = custom_field(
        metadata={"type": """list[DestinyProgressionResetEntry]"""}
    )
    step_index: int = custom_field()
    weekly_limit: int = custom_field()
    weekly_progress: int = custom_field()
    manifest_faction_hash: Optional["DestinyFactionDefinition"] = custom_field(default=None)
    manifest_progression_hash: Optional["DestinyProgressionDefinition"] = 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