Skip to content

groups

Group interfaces for analytix.

You should never need to create any of these yourself.

Group dataclass

Bases: _Resource

A group.

Parameters:

Name Type Description Default
kind str

The kind of resource this is. This will always be "youtube#group".

 required
etag Optional[str]

The Etag of this resource.

 required
id str

The ID that YouTube uses to uniquely identify the group.

 required
published_at datetime

The date and time that the group was created.

 required
title str

The group name.

 required
item_count int

The number of items in the group.

 required
item_type str

The type of resources that the group contains.

 required
shard Shard

The shard instance used to fetch this group.

 required
Source code in analytix/groups/groups.py 
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
@dataclass(frozen=True)
class Group(_Resource):
    """A group.

    Parameters
    ----------
    kind
        The kind of resource this is. This will always be
        "youtube#group".
    etag
        The Etag of this resource.
    id
        The ID that YouTube uses to uniquely identify the group.
    published_at
        The date and time that the group was created.
    title
        The group name.
    item_count
        The number of items in the group.
    item_type
        The type of resources that the group contains.
    shard
        The shard instance used to fetch this group.
    """

    __slots__ = ("id", "published_at", "title", "item_count", "item_type", "shard")

    id: str
    published_at: dt.datetime
    title: str
    item_count: int
    item_type: str
    shard: "Shard"

    @classmethod
    def from_json(cls, shard: "Shard", data: Dict[str, Any]) -> "Group":
        """Create a new `Group` instance from JSON data.

        ???+ note "Changed in version 5.0"
            This now takes the shard instance used to fetch the data.

        Parameters
        ----------
        shard
            The shard instance used to fetch the data.
        data
            The raw JSON data from the API.

        Returns
        -------
        Group
            The newly created instance.
        """
        return cls(
            data["kind"],
            data["etag"],
            data["id"],
            dt.datetime.fromisoformat(
                data["snippet"]["publishedAt"].replace("Z", "+00:00"),
            ),
            data["snippet"]["title"],
            int(data["contentDetails"]["itemCount"]),
            data["contentDetails"]["itemType"],
            shard,
        )

    @property
    def data(self) -> Dict[str, Any]:
        """The raw data for this group in JSON format.

        Returns
        -------
        Dict[str, Any]
            The response data.
        """
        return {
            "kind": self.kind,
            "etag": self.etag,
            "id": self.id,
            "snippet": {
                "publishedAt": (
                    self.published_at.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
                ),
                "title": self.title,
            },
            "contentDetails": {
                "itemCount": str(self.item_count),
                "itemType": self.item_type,
            },
        }

    def fetch_items(self) -> "GroupItemList":
        """Fetch a list of all items within this group.

        !!! note "New in version 5.0"

        Returns
        -------
        GroupItemList
            An object containing the list of group items and the next
            page token.

        Raises
        ------
        BadRequest
            Your request was invalid.
        Unauthorised
            Your access token is invalid.
        Forbidden
            You tried to access data you're not allowed to access. If
            your channel is not partnered, this is raised when you try
            to access monetary data.
        """
        return self.shard.fetch_group_items(self.id)

data property 

data: Dict[str, Any]

The raw data for this group in JSON format.

Returns:

Type Description
Dict[str, Any]

The response data.

fetch_items 

fetch_items() -> GroupItemList

Fetch a list of all items within this group.

New in version 5.0

Returns:

Type Description
GroupItemList

An object containing the list of group items and the next page token.

Raises:

Type Description
BadRequest

Your request was invalid.
Unauthorised

Your access token is invalid.
Forbidden

You tried to access data you're not allowed to access. If your channel is not partnered, this is raised when you try to access monetary data.
Source code in analytix/groups/groups.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def fetch_items(self) -> "GroupItemList":
    """Fetch a list of all items within this group.

    !!! note "New in version 5.0"

    Returns
    -------
    GroupItemList
        An object containing the list of group items and the next
        page token.

    Raises
    ------
    BadRequest
        Your request was invalid.
    Unauthorised
        Your access token is invalid.
    Forbidden
        You tried to access data you're not allowed to access. If
        your channel is not partnered, this is raised when you try
        to access monetary data.
    """
    return self.shard.fetch_group_items(self.id)

from_json classmethod 

from_json(shard: Shard, data: Dict[str, Any]) -> Group

Create a new Group instance from JSON data.

Changed in version 5.0

This now takes the shard instance used to fetch the data.

Parameters:

Name Type Description Default
shard Shard

The shard instance used to fetch the data.

 required
data Dict[str, Any]

The raw JSON data from the API.

 required

Returns:

Type Description
Group

The newly created instance.
Source code in analytix/groups/groups.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
@classmethod
def from_json(cls, shard: "Shard", data: Dict[str, Any]) -> "Group":
    """Create a new `Group` instance from JSON data.

    ???+ note "Changed in version 5.0"
        This now takes the shard instance used to fetch the data.

    Parameters
    ----------
    shard
        The shard instance used to fetch the data.
    data
        The raw JSON data from the API.

    Returns
    -------
    Group
        The newly created instance.
    """
    return cls(
        data["kind"],
        data["etag"],
        data["id"],
        dt.datetime.fromisoformat(
            data["snippet"]["publishedAt"].replace("Z", "+00:00"),
        ),
        data["snippet"]["title"],
        int(data["contentDetails"]["itemCount"]),
        data["contentDetails"]["itemType"],
        shard,
    )

GroupItem dataclass

Bases: _Resource

A group item.

Parameters:

Name Type Description Default
kind str

The kind of resource this is. This will always be "youtube#groupItem".

 required
etag Optional[str]

The Etag of this resource.

 required
id str

The ID that YouTube uses to uniquely identify the channel, video, playlist, or asset resource that is included in the group.

 required
resource GroupItemResource

The resource object contains information that identifies the item being added to the group.

 required
Notes

The id parameter does NOT refer to the actual ID of the channel, video, playlist, or asset, but instead an ID related to its inclusion within the group.

To get the actual ID of the resource, use resource.id.

Source code in analytix/groups/groups.py 
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
@dataclass(frozen=True)
class GroupItem(_Resource):
    """A group item.

    Parameters
    ----------
    kind
        The kind of resource this is. This will always be
        "youtube#groupItem".
    etag
        The Etag of this resource.
    id
        The ID that YouTube uses to uniquely identify the channel,
        video, playlist, or asset resource that is included in the
        group.
    resource
        The resource object contains information that identifies the
        item being added to the group.

    Notes
    -----
    The `id` parameter does NOT refer to the actual ID of the channel,
    video, playlist, or asset, but instead an ID related to its
    inclusion within the group.

    To get the actual ID of the resource, use `resource.id`.
    """

    __slots__ = ("id", "group_id", "resource")

    id: str
    group_id: str
    resource: "GroupItemResource"

    @classmethod
    def from_json(cls, data: Dict[str, Any]) -> "GroupItem":
        """Create a new `GroupItem` instance from JSON data.

        Parameters
        ----------
        data
            The raw JSON data from the API.

        Returns
        -------
        GroupItem
            The newly created instance.
        """
        return cls(
            data["kind"],
            data["etag"],
            data["id"],
            data["groupId"],
            GroupItemResource(
                data["resource"]["kind"],
                data["resource"]["id"],
            ),
        )

    @property
    def data(self) -> Dict[str, Any]:
        """The raw data for this group in JSON format.

        Returns
        -------
        Dict[str, Any]
            The response data.
        """
        return {
            "kind": self.kind,
            "etag": self.etag,
            "id": self.id,
            "groupId": self.group_id,
            "resource": {
                "kind": self.resource.kind,
                "id": self.resource.id,
            },
        }

data property 

data: Dict[str, Any]

The raw data for this group in JSON format.

Returns:

Type Description
Dict[str, Any]

The response data.

from_json classmethod 

from_json(data: Dict[str, Any]) -> GroupItem

Create a new GroupItem instance from JSON data.

Parameters:

Name Type Description Default
data Dict[str, Any]

The raw JSON data from the API.

 required

Returns:

Type Description
GroupItem

The newly created instance.
Source code in analytix/groups/groups.py 
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
@classmethod
def from_json(cls, data: Dict[str, Any]) -> "GroupItem":
    """Create a new `GroupItem` instance from JSON data.

    Parameters
    ----------
    data
        The raw JSON data from the API.

    Returns
    -------
    GroupItem
        The newly created instance.
    """
    return cls(
        data["kind"],
        data["etag"],
        data["id"],
        data["groupId"],
        GroupItemResource(
            data["resource"]["kind"],
            data["resource"]["id"],
        ),
    )

GroupItemList dataclass

Bases: _Resource

A list of group items.

Parameters:

Name Type Description Default
kind str

The kind of resource this is. This will always be "youtube#groupListResponse".

 required
etag Optional[str]

The Etag of this resource.

 required
items List[GroupItem]

A list of items that the group contains. Each item in the list represents a groupItem resource.

 required
Source code in analytix/groups/groups.py 
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
@dataclass(frozen=True)
class GroupItemList(_Resource):
    """A list of group items.

    Parameters
    ----------
    kind
        The kind of resource this is. This will always be
        "youtube#groupListResponse".
    etag
        The Etag of this resource.
    items
        A list of items that the group contains. Each item in the list
        represents a groupItem resource.
    """

    __slots__ = "items"

    items: List["GroupItem"]

    def __getitem__(self, key: int) -> "GroupItem":
        return self.items[key]

    def __iter__(self) -> Iterator["GroupItem"]:
        return iter(self.items)

    @classmethod
    def from_json(cls, data: Dict[str, Any]) -> "GroupItemList":
        """Create a new `GroupItemList` instance from JSON data.

        Parameters
        ----------
        data
            The raw JSON data from the API.

        Returns
        -------
        GroupItemList
            The newly created instance.
        """
        return cls(
            data["kind"],
            data["etag"],
            [GroupItem.from_json(item) for item in data["items"]],
        )

    @property
    def data(self) -> Dict[str, Any]:
        """The raw data for this group in JSON format.

        Returns
        -------
        Dict[str, Any]
            The response data.
        """
        return {
            "kind": self.kind,
            "etag": self.etag,
            "items": [g_item.data for g_item in self.items],
        }

data property 

data: Dict[str, Any]

The raw data for this group in JSON format.

Returns:

Type Description
Dict[str, Any]

The response data.

from_json classmethod 

from_json(data: Dict[str, Any]) -> GroupItemList

Create a new GroupItemList instance from JSON data.

Parameters:

Name Type Description Default
data Dict[str, Any]

The raw JSON data from the API.

 required

Returns:

Type Description
GroupItemList

The newly created instance.
Source code in analytix/groups/groups.py 
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
@classmethod
def from_json(cls, data: Dict[str, Any]) -> "GroupItemList":
    """Create a new `GroupItemList` instance from JSON data.

    Parameters
    ----------
    data
        The raw JSON data from the API.

    Returns
    -------
    GroupItemList
        The newly created instance.
    """
    return cls(
        data["kind"],
        data["etag"],
        [GroupItem.from_json(item) for item in data["items"]],
    )

GroupItemResource dataclass

A group item resource.

Parameters:

Name Type Description Default
kind str

Identifies the type of resource being added to the group.

 required
id str

The channel, video, playlist, or asset ID that YouTube uses to uniquely identify the item that is being added to the group.

 required
Source code in analytix/groups/groups.py 
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
@dataclass(frozen=True)
class GroupItemResource:
    """A group item resource.

    Parameters
    ----------
    kind
        Identifies the type of resource being added to the group.
    id
        The channel, video, playlist, or asset ID that YouTube uses to
        uniquely identify the item that is being added to the group.
    """

    __slots__ = ("kind", "id")

    kind: str
    id: str

GroupList dataclass

Bases: _Resource

A list of groups.

Parameters:

Name Type Description Default
kind str

The kind of resource this is. This will always be "youtube#groupListResponse".

 required
etag Optional[str]

The Etag of this resource.

 required
items List[Group]

A list of groups that match the API request parameters. Each item in the list represents a group resource.

 required
next_page_token Optional[str]

The token that can be used as the value of the pageToken parameter to retrieve the next page in the result set.

 required
Source code in analytix/groups/groups.py 
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
@dataclass(frozen=True)
class GroupList(_Resource):
    """A list of groups.

    Parameters
    ----------
    kind
        The kind of resource this is. This will always be
        "youtube#groupListResponse".
    etag
        The Etag of this resource.
    items
        A list of groups that match the API request parameters. Each
        item in the list represents a group resource.
    next_page_token
        The token that can be used as the value of the `pageToken`
        parameter to retrieve the next page in the result set.
    """

    __slots__ = ("items", "next_page_token")

    items: List["Group"]
    next_page_token: Optional[str]

    def __getitem__(self, key: int) -> "Group":
        return self.items[key]

    def __iter__(self) -> Iterator["Group"]:
        return iter(self.items)

    @classmethod
    def from_json(cls, shard: "Shard", data: Dict[str, Any]) -> "GroupList":
        """Create a new `GroupList` instance from JSON data.

        ???+ note "Changed in version 5.0"
            * This now takes the shard instance used to fetch the data
            * This will no longer raise an error if a channel has no
              groups

        Parameters
        ----------
        shard
            The shard instance used to fetch the data.
        data
            The raw JSON data from the API.

        Returns
        -------
        GroupList
            The newly created instance.
        """
        return cls(
            data["kind"],
            data.get("etag"),
            [Group.from_json(shard, item) for item in data["items"]],
            data.get("nextPageToken"),
        )

    @property
    def data(self) -> Dict[str, Any]:
        """The raw data for this group in JSON format.

        Returns
        -------
        Dict[str, Any]
            The response data.
        """
        return {
            "kind": self.kind,
            "etag": self.etag,
            "items": [group.data for group in self.items],
            "nextPageToken": self.next_page_token,
        }

data property 

data: Dict[str, Any]

The raw data for this group in JSON format.

Returns:

Type Description
Dict[str, Any]

The response data.

from_json classmethod 

from_json(shard: Shard, data: Dict[str, Any]) -> GroupList

Create a new GroupList instance from JSON data.

Changed in version 5.0
  • This now takes the shard instance used to fetch the data
  • This will no longer raise an error if a channel has no groups

Parameters:

Name Type Description Default
shard Shard

The shard instance used to fetch the data.

 required
data Dict[str, Any]

The raw JSON data from the API.

 required

Returns:

Type Description
GroupList

The newly created instance.
Source code in analytix/groups/groups.py 
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
@classmethod
def from_json(cls, shard: "Shard", data: Dict[str, Any]) -> "GroupList":
    """Create a new `GroupList` instance from JSON data.

    ???+ note "Changed in version 5.0"
        * This now takes the shard instance used to fetch the data
        * This will no longer raise an error if a channel has no
          groups

    Parameters
    ----------
    shard
        The shard instance used to fetch the data.
    data
        The raw JSON data from the API.

    Returns
    -------
    GroupList
        The newly created instance.
    """
    return cls(
        data["kind"],
        data.get("etag"),
        [Group.from_json(shard, item) for item in data["items"]],
        data.get("nextPageToken"),
    )