|
1 | 1 | Migration from v2 to v3 |
2 | 2 | ----------------------- |
3 | 3 |
|
4 | | - |
5 | 4 | Changes to Existing Methods |
6 | 5 | =========================== |
7 | 6 |
|
8 | | -GetSearch() |
9 | | -++++++++++++++++++++++++++++ |
10 | | -* Adds ``raw_query`` method. See :ref:`raw_queries` for more information. |
| 7 | +:py:func:`twitter.api.Api.GetBlocks` |
| 8 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 9 | +* 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. |
| 10 | +* 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. |
11 | 11 |
|
12 | | -GetFollowers() |
13 | | -++++++++++++++++++++++++++++ |
| 12 | +:py:func:`twitter.api.Api.GetFollowers` |
| 13 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
14 | 14 | * 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. |
15 | 15 | * 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. |
16 | 16 | * 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. |
17 | 17 |
|
18 | | -GetFriends() |
19 | | -++++++++++++++++++++++++++++ |
| 18 | +:py:func:`twitter.api.Api.GetFollowersPaged` |
| 19 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 20 | +* 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. |
| 21 | +* 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. |
| 22 | + |
| 23 | +:py:func:`twitter.api.Api.GetFriends` |
| 24 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
20 | 25 | * 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. |
21 | 26 | * 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. |
22 | 27 | * 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. |
23 | 28 |
|
24 | | -GetFriendsPaged() |
25 | | -++++++++++++++++++++++++++++ |
| 29 | +:py:func:`twitter.api.Api.GetFriendsPaged` |
| 30 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
26 | 31 | * 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. |
27 | 32 | * 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. |
28 | 33 |
|
29 | | -GetFollowersPaged() |
30 | | -++++++++++++++++++++++++++++ |
31 | | -* 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. |
32 | | -* 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. |
| 34 | +:py:func:`twitter.api.Api.GetListMembers` |
| 35 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 36 | +* 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. |
| 37 | + |
| 38 | + |
| 39 | +:py:func:`twitter.api.Api.GetSearch` |
| 40 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 41 | +* Adds ``raw_query`` method. See :ref:`raw_queries` for more information. |
33 | 42 |
|
34 | | -GetUserStream() |
35 | | -++++++++++++++++++++++++++++ |
| 43 | +:py:func:`twitter.api.Api.GetUserStream` |
| 44 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
36 | 45 | * 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. |
37 | 46 |
|
38 | | -PostUpdate() |
39 | | -++++++++++++ |
| 47 | +:py:func:`twitter.api.Api.PostUpdate` |
| 48 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
40 | 49 | * 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. |
41 | 50 | * ``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. |
42 | 51 | * ``media_category``: Only for use with the AdsAPI. See https://dev.twitter.com/ads/creative/promoted-video-overview if this applies to your application. |
43 | 52 |
|
44 | | -GetBlocks() |
45 | | -+++++++++++ |
46 | | -* 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. |
47 | | -* 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. |
48 | | - |
49 | 53 |
|
50 | 54 | Deprecation |
51 | 55 | =========== |
52 | 56 |
|
53 | | -PostMedia() |
54 | | -++++++++++++++++++++++++++++ |
| 57 | +:py:func:`twitter.api.Api.PostMedia` |
| 58 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
55 | 59 | * 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. |
56 | 60 |
|
57 | | -PostMultipleMedia() |
58 | | -+++++++++++++++++++ |
| 61 | +:py:func:`twitter.api.Api.PostMultipleMedia` |
| 62 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
59 | 63 | * 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. |
60 | 64 |
|
61 | 65 |
|
62 | 66 | New Methods |
63 | 67 | =========== |
64 | 68 |
|
65 | | -UploadMediaChunked() |
66 | | -++++++++++++++++++++++++++++ |
| 69 | +:py:func:`twitter.api.Api.GetBlocksIDs` |
| 70 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 71 | +* Returns **all** the users currently blocked by the authenticated user as user IDs. The user IDs will be integers. |
| 72 | + |
| 73 | +:py:func:`twitter.api.Api.GetBlocksIDsPaged` |
| 74 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 75 | +* Returns one page, specified by the cursor parameter, of the users currently blocked by the authenticated user as user IDs. |
| 76 | + |
| 77 | +:py:func:`twitter.api.Api.GetBlocksPaged` |
| 78 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 79 | +* 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. |
| 80 | + |
| 81 | +:py:func:`twitter.api.Api.GetListMembersPaged` |
| 82 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 83 | +* Allows you to page through a the members of a given twitter.list.List. |
| 84 | +* ``cursor`` parameter operates as with other methods, denoting the page of members that you wish to retrieve. |
| 85 | +* Returns ``next_cursor``, ``previous_cursor``, and a list containing the users that are members of the given twitter.list.List. |
| 86 | + |
| 87 | + |
| 88 | +:py:func:`twitter.api.Api.GetListsPaged` |
| 89 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 90 | +* 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``. |
| 91 | +* ``cursor`` should be ``-1`` for the first page. |
| 92 | +* Returns the ``next_cursor``, ``previous_cursor``, and a list of :py:mod:`twitter.list.List` instances. |
| 93 | + |
| 94 | +:py:func:`twitter.api.Api.UploadMediaChunked` |
| 95 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
67 | 96 | * 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). |
68 | 97 | * 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. |
69 | 98 | * 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. |
70 | 99 | * The return value will be the ``media_id`` of the uploaded file. |
71 | 100 |
|
72 | | -UploadMediaSimple() |
73 | | -++++++++++++++++++++++++++++ |
| 101 | +:py:func:`twitter.api.Api.UploadMediaSimple` |
| 102 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
74 | 103 | * 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. |
75 | 104 | * Return value is the ``media_id`` of the uploaded file. |
76 | | - |
77 | | -GetBlocksPaged() |
78 | | -++++++++++++++++ |
79 | | -* 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. |
80 | | - |
81 | | -GetBlocksIDs() |
82 | | -++++++++++++++ |
83 | | -* Returns **all** the users currently blocked by the authenticated user as user IDs. The user IDs will be integers. |
84 | | - |
85 | | -GetBlocksIDsPaged() |
86 | | -+++++++++++++++++++ |
87 | | -* Returns one page, specified by the cursor parameter, of the users currently blocked by the authenticated user as user IDs. |
|
0 commit comments