|
| 1 | +"""Activity class containing all logic for reading activity streams.""" |
| 2 | + |
| 3 | +import logging |
| 4 | +from collections.abc import Sequence |
| 5 | +from typing import Any, Optional |
| 6 | + |
| 7 | +from hdx.api.configuration import Configuration |
| 8 | +from hdx.data.hdxobject import HDXError, HDXObject |
| 9 | + |
| 10 | +logger = logging.getLogger(__name__) |
| 11 | + |
| 12 | + |
| 13 | +class Activity(HDXObject): |
| 14 | + """Activity class containing all logic for reading activity streams. Activities |
| 15 | + are read only. |
| 16 | +
|
| 17 | + Args: |
| 18 | + initial_data: Initial activity metadata dictionary. Defaults to None. |
| 19 | + configuration: HDX configuration. Defaults to global configuration. |
| 20 | + """ |
| 21 | + |
| 22 | + def __init__( |
| 23 | + self, |
| 24 | + initial_data: dict | None = None, |
| 25 | + configuration: Configuration | None = None, |
| 26 | + ) -> None: |
| 27 | + if not initial_data: |
| 28 | + initial_data = {} |
| 29 | + super().__init__(initial_data, configuration=configuration) |
| 30 | + |
| 31 | + @staticmethod |
| 32 | + def actions() -> dict[str, str]: |
| 33 | + """Dictionary of actions that can be performed on object |
| 34 | +
|
| 35 | + Returns: |
| 36 | + Dictionary of actions that can be performed on object |
| 37 | + """ |
| 38 | + return { |
| 39 | + "show": "activity_show", |
| 40 | + "data_show": "activity_data_show", |
| 41 | + "diff": "activity_diff", |
| 42 | + "package_list": "package_activity_list", |
| 43 | + "organization_list": "organization_activity_list", |
| 44 | + "group_list": "group_activity_list", |
| 45 | + "user_list": "user_activity_list", |
| 46 | + "recently_changed_packages": "recently_changed_packages_activity_list", |
| 47 | + } |
| 48 | + |
| 49 | + @classmethod |
| 50 | + def read_from_hdx( |
| 51 | + cls, identifier: str, configuration: Configuration | None = None |
| 52 | + ) -> Optional["Activity"]: |
| 53 | + """Reads the activity given by identifier from HDX and returns Activity object. |
| 54 | + HDX requires permission to edit the object the activity relates to. |
| 55 | +
|
| 56 | + Args: |
| 57 | + identifier: Identifier of activity |
| 58 | + configuration: HDX configuration. Defaults to global configuration. |
| 59 | +
|
| 60 | + Returns: |
| 61 | + Activity object if successful read, None if not |
| 62 | + """ |
| 63 | + return cls._read_from_hdx_class("activity", identifier, configuration) |
| 64 | + |
| 65 | + def get_object_type(self) -> str: |
| 66 | + """Get the CKAN object type the activity relates to eg. package, |
| 67 | + organization, group or user. This is the last word of the activity type |
| 68 | + (eg. "changed package") with "dataset" (from "follow dataset") mapped to |
| 69 | + "package". |
| 70 | +
|
| 71 | + Returns: |
| 72 | + Object type |
| 73 | + """ |
| 74 | + object_type = self.data["activity_type"].split(" ")[-1] |
| 75 | + if object_type == "dataset": |
| 76 | + return "package" |
| 77 | + return object_type |
| 78 | + |
| 79 | + def get_data(self) -> dict: |
| 80 | + """Get the data of the activity which includes a snapshot of the object |
| 81 | + at the time of the activity. HDX requires permission to edit the object |
| 82 | + the activity relates to. |
| 83 | +
|
| 84 | + Returns: |
| 85 | + Activity data |
| 86 | + """ |
| 87 | + return self._write_to_hdx("data_show", {"id": self.data["id"]}, "id") |
| 88 | + |
| 89 | + def get_diff(self, diff_type: str = "unified") -> dict: |
| 90 | + """Get a diff of the object compared to its previous version. HDX requires |
| 91 | + permission to edit the object the activity relates to. |
| 92 | +
|
| 93 | + Args: |
| 94 | + diff_type: One of unified, context or html. Defaults to unified. |
| 95 | +
|
| 96 | + Returns: |
| 97 | + Activity diff |
| 98 | + """ |
| 99 | + data = { |
| 100 | + "id": self.data["id"], |
| 101 | + "object_type": self.get_object_type(), |
| 102 | + "diff_type": diff_type, |
| 103 | + } |
| 104 | + return self._write_to_hdx("diff", data, "id") |
| 105 | + |
| 106 | + @classmethod |
| 107 | + def _get_list( |
| 108 | + cls, |
| 109 | + action: str, |
| 110 | + data: dict, |
| 111 | + configuration: Configuration | None = None, |
| 112 | + all_pages: bool = False, |
| 113 | + max_activities: int | None = None, |
| 114 | + ) -> list["Activity"]: |
| 115 | + """Helper method to get a list of activities from HDX |
| 116 | +
|
| 117 | + Args: |
| 118 | + action: Action to perform |
| 119 | + data: Data to pass to CKAN including any offset and limit |
| 120 | + configuration: HDX configuration. Defaults to global configuration. |
| 121 | + all_pages: Whether to get all pages of results. Defaults to False. |
| 122 | + max_activities: Maximum number of activities if all_pages is True. Defaults to None (no maximum). |
| 123 | +
|
| 124 | + Returns: |
| 125 | + List of Activity objects |
| 126 | + """ |
| 127 | + activity = cls(configuration=configuration) |
| 128 | + if not all_pages: |
| 129 | + result = activity._write_to_hdx(action, data) |
| 130 | + return [cls(x, configuration=configuration) for x in result] |
| 131 | + data = dict(data) |
| 132 | + limit = data.setdefault("limit", 100) |
| 133 | + offset = data.get("offset", 0) |
| 134 | + activities = [] |
| 135 | + while True: |
| 136 | + data["offset"] = offset |
| 137 | + result = activity._write_to_hdx(action, data) |
| 138 | + activities.extend(cls(x, configuration=configuration) for x in result) |
| 139 | + if max_activities is not None and len(activities) >= max_activities: |
| 140 | + return activities[:max_activities] |
| 141 | + if len(result) < limit: |
| 142 | + return activities |
| 143 | + offset += limit |
| 144 | + |
| 145 | + @classmethod |
| 146 | + def get_activities( |
| 147 | + cls, |
| 148 | + object_type: str, |
| 149 | + identifier: str, |
| 150 | + configuration: Configuration | None = None, |
| 151 | + all_pages: bool = False, |
| 152 | + **kwargs: Any, |
| 153 | + ) -> list["Activity"]: |
| 154 | + """Get the activity stream of a CKAN object. One page of results (whose |
| 155 | + size is given by limit) is returned unless all_pages is True. |
| 156 | +
|
| 157 | + Args: |
| 158 | + object_type: One of package, organization, group or user |
| 159 | + identifier: Id or name of object |
| 160 | + configuration: HDX configuration. Defaults to global configuration. |
| 161 | + all_pages: Whether to get all pages of results. Defaults to False. |
| 162 | + **kwargs: See below |
| 163 | + offset (int): Where to start getting activity items from. Defaults to 0. |
| 164 | + limit (int): Maximum number of activities per page. Defaults to 31 (HDX maximum 100) or 100 if all_pages is True. |
| 165 | + after (int | str): Only activities after this timestamp (package and user only) |
| 166 | + before (int | str): Only activities before this timestamp (package and user only) |
| 167 | + include_hidden_activity (bool): Include hidden activity, sysadmins only (package, organization and group only) |
| 168 | + activity_types (list): Activity types to include (package only) |
| 169 | + exclude_activity_types (list): Activity types to exclude (package only) |
| 170 | +
|
| 171 | + Returns: |
| 172 | + List of Activity objects |
| 173 | + """ |
| 174 | + if not identifier: |
| 175 | + raise HDXError(f"No id or name for {object_type} to get activities!") |
| 176 | + data = {"id": identifier} |
| 177 | + data.update(kwargs) |
| 178 | + return cls._get_list(f"{object_type}_list", data, configuration, all_pages) |
| 179 | + |
| 180 | + @classmethod |
| 181 | + def get_recently_changed_packages( |
| 182 | + cls, |
| 183 | + configuration: Configuration | None = None, |
| 184 | + all_pages: bool = False, |
| 185 | + max_activities: int | None = 1000, |
| 186 | + **kwargs: Any, |
| 187 | + ) -> list["Activity"]: |
| 188 | + """Get the activity stream of all recently added or changed datasets. |
| 189 | + One page of results (whose size is given by limit) is returned unless |
| 190 | + all_pages is True. all_pages is capped by max_activities because the |
| 191 | + stream covers the whole history of HDX. |
| 192 | +
|
| 193 | + Args: |
| 194 | + configuration: HDX configuration. Defaults to global configuration. |
| 195 | + all_pages: Whether to get all pages of results. Defaults to False. |
| 196 | + max_activities: Maximum number of activities if all_pages is True. Defaults to 1000. None means no maximum (very slow). |
| 197 | + **kwargs: See below |
| 198 | + offset (int): Where to start getting activity items from. Defaults to 0. |
| 199 | + limit (int): Maximum number of activities per page. Defaults to 31 (HDX maximum 100) or 100 if all_pages is True. |
| 200 | +
|
| 201 | + Returns: |
| 202 | + List of Activity objects |
| 203 | + """ |
| 204 | + return cls._get_list( |
| 205 | + "recently_changed_packages", |
| 206 | + kwargs, |
| 207 | + configuration, |
| 208 | + all_pages, |
| 209 | + max_activities, |
| 210 | + ) |
| 211 | + |
| 212 | + def check_required_fields(self, ignore_fields: Sequence[str] = ()) -> None: |
| 213 | + """Activities are read only so this raises an exception |
| 214 | +
|
| 215 | + Args: |
| 216 | + ignore_fields: Fields to ignore. Default is (). |
| 217 | +
|
| 218 | + Returns: |
| 219 | + None |
| 220 | + """ |
| 221 | + raise HDXError("Activities are read only!") |
| 222 | + |
| 223 | + def update_in_hdx(self, **kwargs: Any) -> None: |
| 224 | + """Activities are read only so this raises an exception |
| 225 | +
|
| 226 | + Returns: |
| 227 | + None |
| 228 | + """ |
| 229 | + raise HDXError("Activities are read only!") |
| 230 | + |
| 231 | + def create_in_hdx(self, **kwargs: Any) -> None: |
| 232 | + """Activities are read only so this raises an exception |
| 233 | +
|
| 234 | + Returns: |
| 235 | + None |
| 236 | + """ |
| 237 | + raise HDXError("Activities are read only!") |
| 238 | + |
| 239 | + def delete_from_hdx(self) -> None: |
| 240 | + """Activities are read only so this raises an exception |
| 241 | +
|
| 242 | + Returns: |
| 243 | + None |
| 244 | + """ |
| 245 | + raise HDXError("Activities are read only!") |
0 commit comments