|
| 1 | +Migration from v2 to v3 |
| 2 | +----------------------- |
| 3 | + |
| 4 | + |
1 | 5 | Changes to Existing Methods |
2 | 6 | =========================== |
3 | 7 |
|
4 | | -GetFollowers(): |
5 | | -* 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. |
6 | | -* 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. |
7 | | -* 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. |
| 8 | +GetSearch() |
| 9 | +++++++++++++++++++++++++++++ |
| 10 | +* Adds ``raw_query`` method. See :ref:`raw_queries` for more information. |
8 | 11 |
|
9 | | -GetFriends(): |
10 | | -* 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. |
11 | | -* 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. |
12 | | -* 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. |
| 12 | +GetFollowers() |
| 13 | +++++++++++++++++++++++++++++ |
| 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 | +* 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 | +* 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. |
13 | 17 |
|
14 | | -GetFriendsPaged(): |
15 | | -* 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. Closes #277 |
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. |
| 18 | +GetFriends() |
| 19 | +++++++++++++++++++++++++++++ |
| 20 | +* 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 | +* 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 | +* 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 | 23 |
|
18 | | -GetFollowersPaged(): |
19 | | -* 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. Closes #277 |
20 | | -* 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. |
| 24 | +GetFriendsPaged() |
| 25 | +++++++++++++++++++++++++++++ |
| 26 | +* 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 | +* 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. |
21 | 28 |
|
22 | | -GetSearch(): |
23 | | -* You can now specify a user for whom you wish to limit the search. For example, to only get tweets from the user `twitterapi`, you can call `GetSearch(who='twitterapi')` and only that account's tweets will be returned. |
| 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. |
24 | 33 |
|
25 | | -GetUserStream(): |
| 34 | +GetUserStream() |
| 35 | +++++++++++++++++++++++++++++ |
26 | 36 | * 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. |
27 | 37 |
|
| 38 | +PostUpdate() |
| 39 | +++++++++++++ |
| 40 | +* 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 | +* ``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 | +* ``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 | + |
28 | 44 |
|
29 | 45 | Deprecation |
30 | 46 | =========== |
31 | 47 |
|
32 | | -PostMedia(): |
| 48 | +PostMedia() |
| 49 | +++++++++++++++++++++++++++++ |
33 | 50 | * 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. |
34 | 51 |
|
| 52 | +PostMultipleMedia() |
| 53 | ++++++++++++++++++++ |
| 54 | +* 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. |
| 55 | + |
35 | 56 |
|
36 | 57 | New Methods |
37 | 58 | =========== |
38 | 59 |
|
39 | | -UploadMediaChunked(): |
40 | | -* 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 twitter/twitter_utils.py for details). |
| 60 | +UploadMediaChunked() |
| 61 | +++++++++++++++++++++++++++++ |
| 62 | +* 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). |
41 | 63 | * 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. |
42 | 64 | * 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. |
43 | | -* The return value will be the media_id of the uploaded file. |
| 65 | +* The return value will be the ``media_id`` of the uploaded file. |
44 | 66 |
|
45 | | -UploadMediaSimple(): |
| 67 | +UploadMediaSimple() |
| 68 | +++++++++++++++++++++++++++++ |
46 | 69 | * 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. |
47 | | -* Return value is the `media_id` of the uploaded file. |
| 70 | +* Return value is the ``media_id`` of the uploaded file. |
0 commit comments