# Migration from v2 to v3

## Changes to Existing Methods

### `twitter.api.Api()`

- `shortner` parameter has been removed. Please see Issue #298.

### `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`.

### `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`.

### `twitter.api.Api.DestroyBlock()`

- Kwarg `id` has been changed to `user_id` in order to avoid shadowing a builtin and be more descriptive.

### `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.

### `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 `twitter.api.Api.GetBlocksPaged()` instead.

### `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.

### `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.

### `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.

### `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.

### `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.

### `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.

### `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.

### `twitter.api.Api.GetSearch()`

- Adds `raw_query` method. See Raw Queries for more information.

### `twitter.api.Api.GetTrendsWoeid()`

- Kwarg `id` has been changed to `woeid` in order to avoid shadowing a builtin and be more descriptive.

### `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.

### `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 `twitter.user.User` objects for either `user_id` or `screen_name`.
- Return value is a list of `twitter.user.UserStatus` objects.

### `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.

### `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

### `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.

### `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

### `twitter.api.Api.GetBlocksIDs()`

- Returns all the users currently blocked by the authenticated user as user IDs. The user IDs will be integers.

### `twitter.api.Api.GetBlocksIDsPaged()`

- Returns one page, specified by the cursor parameter, of the users currently blocked by the authenticated user as user IDs.

### `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.

### `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.

### `twitter.api.Api.GetListsPaged()`

- Much like `twitter.api.Api.GetFriendsPaged()` and similar methods, this allows you to retrieve an arbitrary page of `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 `twitter.list.List` instances.

### `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 `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.

### `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.