1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
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
|
Migration from v2 to v3
-----------------------
Changes to Existing Methods
===========================
:py:func:`twitter.api.Api()`
++++++++++++++++++++++++++++
* ``shortner`` parameter has been removed. Please see `Issue
#298 <https://github.com/bear/python-twitter/issues/298>`_.
:py:func:`twitter.api.Api.CreateFavorite`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* kwarg param has been changed to ``status_id`` from ``id`` to be consistent
with other method calls and avoid shadowing builtin function ``id``.
:py:func:`twitter.api.Api.DestroyFavorite`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* kwarg param has been changed to ``status_id`` from ``id`` to be consistent
with other method calls and avoid shadowing builtin function ``id``.
:py:func:`twitter.api.Api.DestroyBlock`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Kwarg ``id`` has been changed to ``user_id`` in order to avoid shadowing
a builtin and be more descriptive.
:py:func:`twitter.api.Api.DestroyStatus`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* kwarg ``id`` has been changed to ``status_id`` in keeping with the rest of
the Api and to avoid shadowing a builtin.
:py:func:`twitter.api.Api.GetBlocks`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Method no longer accepts parameters ``user_id`` or ``screen_name`` as these are not honored by Twitter. The data returned will be for the authenticated user only.
* Parameter ``cursor`` is no longer accepted -- this method will return **all** users being blocked by the currently authenticated user. If you need paging, please use :py:func:`twitter.api.Api.GetBlocksPaged` instead.
:py:func:`twitter.api.Api.GetFollowers`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Method no longer honors a ``count`` or ``cursor`` parameter. These have been deprecated in favor of making this method explicitly a convenience function to return a list of every ``twitter.User`` who is following the specified or authenticated user. A warning will be raised if ``count`` or ``cursor`` is passed with the expectation that breaking behavior will be introduced in a later version.
* Method now takes an optional parameter of ``total_count``, which limits the number of users to return. If this is not set, the data returned will be all users following the specified user.
* The kwarg ``include_user_entities`` now defaults to ``True``. This was set to ``False`` previously, but would not be included in query parameters sent to Twitter. Without the query parameter in the URL, Twitter would default to returning user_entities, so this change makes this behavior explicit.
:py:func:`twitter.api.Api.GetFollowersPaged`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* The third value of the tuple returned by this method is now a list of twitter.User objects in accordance with its doc string rather than the raw data from API.
* The kwarg ``include_user_entities`` now defaults to ``True``. This was set to ``False`` previously, but would not be included in query parameters sent to Twitter. Without the query parameter in the URL, Twitter would default to returning user_entities, so this change makes this behavior explicit and consistent with the previously ambiguous behavior.
:py:func:`twitter.api.Api.GetFriends`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Method no longer honors a ``count`` or ``cursor`` parameter. These have been deprecated in favor of making this method explicitly a convenience function to return a list of every ``twitter.User`` who is followed by the specified or authenticated user. A warning will be raised if ``count`` or ``cursor`` is passed with the expectation that breaking behavior will be introduced in a later version.
* Method now takes an optional parameter of ``total_count``, which limits the number of users to return. If this is not set, the data returned will be all users followed by the specified user.
* The kwarg ``include_user_entities`` now defaults to ``True``. This was set to ``False`` previously, but would not be included in query parameters sent to Twitter. Without the query parameter in the URL, Twitter would default to returning user_entities, so this change makes this behavior explicit.
:py:func:`twitter.api.Api.GetFriendsPaged`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* The third value of the tuple returned by this method is now a list of twitter.User objects in accordance with its doc string rather than the raw data from API.
* The kwarg ``include_user_entities`` now defaults to ``True``. This was set to ``False`` previously, but would not be included in query parameters sent to Twitter. Without the query parameter in the URL, Twitter would default to returning user_entities, so this change makes this behavior explicit.
:py:func:`twitter.api.Api.GetListMembers`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* No longer accepts ``cursor`` parameter. If you require granular control over the paging of the twitter.list.List members, please user twitter.api.Api.GetListMembersPaged instead.
:py:func:`twitter.api.Api.GetStatus`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Kwarg ``id`` has been changed to ``status_id`` in keeping with the rest of
the Api and to avoid shadowing a builtin.
:py:func:`twitter.api.Api.GetStatusOembed`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Kwarg ``id`` has been changed to ``status_id`` in keeping with the rest of
the Api and to avoid shadowing a builtin.
:py:func:`twitter.api.Api.GetSearch`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Adds ``raw_query`` method. See :ref:`raw_queries` for more information.
:py:func:`twitter.api.Api.GetTrendsWoeid`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Kwarg ``id`` has been changed to ``woeid`` in order to avoid shadowing
a builtin and be more descriptive.
:py:func:`twitter.api.Api.GetUserStream`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Parameter 'stall_warning' is now 'stall_warnings' in line with GetStreamFilter and Twitter's naming convention. This should now actually return stall warnings, whereas it did not have any effect previously.
:py:func:`twitter.api.Api.LookupFriendship`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Method will now accept a list for either ``user_id`` or ``screen_name``. The list can contain either ints, strings, or :py:mod:`twitter.user.User` objects for either ``user_id`` or ``screen_name``.
* Return value is a list of :py:mod:`twitter.user.UserStatus` objects.
:py:func:`twitter.api.Api.PostUpdate`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Now accepts three new parameters: ``media``, ``media_additional_owners``, and ``media_category``. ``media`` can be a URL, a local file, or a file-like object (something with a ``read()`` method), or a list of any combination of the above.
* ``media_additional_owners`` should be a list of user ids representing Twitter users that should be able to use the uploaded media in their tweets. If you pass a list of media, then **additional owners will apply to each object.** If you need more granular control, please use the UploadMedia* methods.
* ``media_category``: Only for use with the AdsAPI. See https://dev.twitter.com/ads/creative/promoted-video-overview if this applies to your application.
:py:func:`twitter.api.Api.PostRetweet`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Kwarg ``original_id`` has been changed to ``status_id`` in order to avoid shadowing
a builtin and be more descriptive.
Deprecation
===========
:py:func:`twitter.api.Api.PostMedia`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* This endpoint is deprecated by Twitter. Python-twitter will throw a warning about using the method and advise you to use PostUpdate() instead. There is no schedule for when this will be removed from Twitter.
:py:func:`twitter.api.Api.PostMultipleMedia`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* This method should be replaced by passing a list of media objects (either URLs, local files, or file-like objects) to PostUpdate. You are limited to a maximum of 4 media files per tweet.
New Methods
===========
:py:func:`twitter.api.Api.GetBlocksIDs`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Returns **all** the users currently blocked by the authenticated user as user IDs. The user IDs will be integers.
:py:func:`twitter.api.Api.GetBlocksIDsPaged`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Returns one page, specified by the cursor parameter, of the users currently blocked by the authenticated user as user IDs.
:py:func:`twitter.api.Api.GetBlocksPaged`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Allows you to page through the currently authenticated user's blocked users. Method returns three values: the next cursor, the previous cursor, and a list of ``twitter.User`` instances representing the blocked users.
:py:func:`twitter.api.Api.GetListMembersPaged`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Allows you to page through a the members of a given twitter.list.List.
* ``cursor`` parameter operates as with other methods, denoting the page of members that you wish to retrieve.
* Returns ``next_cursor``, ``previous_cursor``, and a list containing the users that are members of the given twitter.list.List.
:py:func:`twitter.api.Api.GetListsPaged`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Much like :py:func:`twitter.api.Api.GetFriendsPaged` and similar methods, this allows you to retrieve an arbitrary page of :py:mod:`twitter.list.List` for either the currently authenticated user or a user specified by ``user_id`` or ``screen_name``.
* ``cursor`` should be ``-1`` for the first page.
* Returns the ``next_cursor``, ``previous_cursor``, and a list of :py:mod:`twitter.list.List` instances.
:py:func:`twitter.api.Api.UploadMediaChunked`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* API method allows chunked upload to upload.twitter.com. Similar to Api.PostMedia(), this method can take either a local filename (str), a URL (str), or a file-like object. The image or video type will be determined by ``mimetypes`` (see :py:func:`twitter.twitter_utils.parse_media_file` for details).
* Optionally, you can specify a chunk_size for uploads when instantiating the Api object. This should be given in bytes. The default is 1MB (that is, 1048576 bytes). Any chunk_size given below 16KB will result in a warning: Twitter will return an error if you try to upload more than 999 chunks of data; for example, if you are uploading a 15MB video, then a chunk_size lower than 15729 bytes will result in 1000 APPEND commands being sent to the API, so you'll get an error. 16KB seems like a reasonable lower bound, but if your use case is well-defined, then python-twitter will not enforce this behavior.
* Another thing to take into consideration: if you're working in a RAM-constrained environment, a very large chunk_size will increase your RAM usage when uploading media through this endpoint.
* The return value will be the ``media_id`` of the uploaded file.
:py:func:`twitter.api.Api.UploadMediaSimple`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Provides the ability to upload a single media file to Twitter without using the ChunkedUpload endpoint. This method should be used on smaller files and reduces the roundtrips from Twitter from three (for UploadMediaChunked) to one.
* Return value is the ``media_id`` of the uploaded file.
|
