Tweepy API verify_credentials() unclearly returns a V1 API User

[curtiscook]

Hi,

Overall your SDK is really straightforward, but I found myself running into documentation issues and wanted to share.

TL;DR
tweepy.API returns a V1 API, whereas tweepy.Client returns an incomplete V2 API, which is not immediately clear in the documentation

If you run API.verify_credentials, you do in fact get a "User" object as described in the docstrings, however, this model that you receive is not the obvious User import at tweepy.user.py (a V2 implementation) -- it's actually this one (a V1 implementation). This is an issue for fields such as username, which was FKA screen_name

I don't think it would continue to be an issue if either
a) it was well documented
b) the models didn't share the same name
c) v1 vs v2 endpoints didn't share the same subpackage.

Thanks :)

    @payload('user')
    def verify_credentials(self, **kwargs):
        """verify_credentials(*, include_entities, skip_status, include_email)

        Verify the supplied user credentials are valid.

        :param include_entities: |include_entities|
        :param skip_status: |skip_status|
        :param include_email: When set to true email will be returned in the
                              user objects as a string.

        :rtype: :class:`User` object if credentials are valid, otherwise False

[Harmon758]

It should be clear from the documentation that API is for v1.1 of the API, whereas Client is for v2, since the former is denoted as "Twitter API v1.1 Reference" and the latter as "Twitter API v2 Reference", with the latter also described as the "Twitter API v2 Client".

Client should be feature complete for API v2, besides the new endpoints that were just introduced under two days ago. API v2 streaming likely will not be through Client and probably won't be part of Tweepy v4.0. If you think there's other functionality for API v2 that's missing, feel free to comment on #1472.

It should also be clear from the Models Reference, which models are for which API version.

However, you are correct that the documentation for API.verify_credentials still links to tweepy.User rather than tweepy.models.User. This is because the documentation for API hasn't been updated since #1535 was merged, where Client and the v2 API models were added and the v1.1 API models were replaced in the package namespace. I plan on updating the documentation for API prior to releasing Tweepy v4.0.

the models didn't share the same name

The v1.1 API User model has existed since the first commit almost 12 years ago.
Every other v2 API model is named the same as how Twitter's API refers to them.
Changing only User would be inconsistent and poor design.
This was considered at the time Client and the v2 API models were added in #1535, and keeping it this way was an explicit design decision, so this will not be changing.

v1 vs v2 endpoints didn't share the same subpackage

Both API and Client are in the package namespace, not a subpackage. If you are proposing moving one or both to its own subpackage, this would be less than ideal. Not only would this unnecessarily complicate imports, but API has been in the package namespace since the initial commit as well. Having Client in its own subpackage would also be inconsistent and poor design, when API is in the package namespace and Client will possibly replace API at some point, when Twitter API v2 replaces API v1.1. Again, this will not be changing.

[curtiscook]

Hi, was trying to lightly suggest a few possible ideas to increase clarity. I don't think you need to change your package structure, but I do think it would be very helpful to add some more color in the documentation? Things that appear obvious to people who have been using this package and grown with it aren't going to be obvious to someone setting up a fresh integration. Either way, thanks for your work!

[Harmon758]

Resolved by 5241ab0, 52af990, etc.