python-youtube

python-youtube (import name pyyoutube) is a Python wrapper around the YouTube Data API v3. It ships two parallel entry points: the newer Client, which exposes every API resource (channels, videos, playlists, search, comments, subscriptions, captions, and more) as a namespaced attribute backed by a shared Resource base class, and the older Api, kept for backward compatibility with existing code written against earlier versions of the library.

Authentication covers both of the YouTube Data API’s access modes: a plain API key for public read-only data, and a full OAuth2 authorization-code flow (via requests-oauthlib) for endpoints that require a signed-in user, including token exchange, refresh, and revocation helpers. Every API response is deserialized into a typed dataclass model (built on dataclasses-json) rather than a raw dict, though a return_json=True escape hatch is available on every resource method for callers who just want the parsed JSON.

The project has been maintained since 2019, has 13 tagged releases, and is tested across Python 3.9 through 3.14 in CI using responses to mock the YouTube API surface.

What You Get

• A Client class exposing every YouTube Data API v3 resource (channels, videos, playlists, playlistItems, search, comments, commentThreads, subscriptions, captions, members, membershipsLevels, i18nLanguages, i18nRegions, thumbnails, watermarks, channelBanners, channelSections, videoCategories, videoAbuseReportReasons, activities) as a namespaced attribute, e.g. client.channels.list(...)
• Both API-key and full OAuth2 authorization-code auth, including get_authorize_url(), generate_access_token(), and token refresh/revocation helpers
• Typed dataclass response models (via dataclasses-json) for every resource, with a return_json=True flag on every call for raw-dict access when preferred
• A legacy Api class retained for backward compatibility with code written against older versions of the library
• Media upload support (pyyoutube.media.Media / MediaUpload) for endpoints like video and channel-banner uploads, with resumable upload progress
• A PyYouTubeException that normalizes both this library’s own validation errors and YouTube’s raw API error payloads into one consistent shape

Common Use Cases

• Pulling channel or video statistics (views, likes, subscriber counts) for reporting or analytics dashboards
• Building a YouTube OAuth login/authorization flow for an app that needs to act on behalf of a signed-in channel owner
• Searching YouTube for videos, channels, or playlists matching a query, content-owner scope, or time window
• Automating playlist or comment moderation workflows (listing, inserting, updating comment threads and playlist items)
• Uploading videos or channel banner art programmatically as part of a publishing pipeline

Under The Hood

Architecture The library centers on a Client class (pyyoutube/client.py) that, via __new__ and inspect.getmembers, discovers every class attribute that is a Resource subclass (defined in pyyoutube/resources/) and rebinds a fresh instance of each to the client, wiring in a back-reference so every resource can reach client.access_token/client.api_key. Each resource (e.g. VideosResource in resources/videos.py) extends a thin Resource base (resources/base_resource.py) and implements REST-style methods (list, insert, update, delete) that build query parameters, call the shared HTTP session, and hand the JSON response to a matching dataclass model for parsing. A parallel, older Api class (api.py) is preserved for backward compatibility, so the codebase effectively maintains two façades over the same resource/model layer. This composition (client discovers resources, resources call models) keeps concerns cleanly separated: swapping the model layer or adding a new resource doesn’t touch the client’s auth/dispatch logic.

Tech Stack Built on Python 3.9+ with requests for HTTP and requests-oauthlib’s OAuth2Session for the OAuth2 authorization-code flow (auth URL generation, code exchange, token refresh, revocation). Response models are plain dataclasses mixed with dataclasses_json.DataClassJsonMixin (models/base.py), giving typed from_dict/to_dict conversion without a heavier validation library like Pydantic. isodate parses YouTube’s ISO 8601 durations, and packaging/dependency management runs through Poetry (pyproject.toml, poetry-core build backend). No async support — all calls are synchronous over requests.

Code Quality The repo carries an extensive test suite (62 test files under tests/, split into apis/, clients/, models/, and utils/ mirroring the source layout), using pytest with responses to mock YouTube API HTTP calls and pytest-cov for coverage, run across Python 3.9-3.14 in CI (.github/workflows/test.yaml). Formatting is enforced via black in a separate CI lint job. Error handling is explicit and centralized: PyYouTubeException (error.py) normalizes both the library’s own parameter-validation errors and YouTube’s raw JSON error payloads into one consistent status_code/message shape, rather than letting raw requests exceptions or malformed API errors leak to callers.

What Makes It Unique Rather than a single client shape, the library deliberately maintains two parallel APIs — the original Api class and the newer, more feature-rich Client — so existing integrations keep working across a major internal restructuring. Its resource auto-discovery mechanism (rebinding Resource subclasses at instantiation via inspect.getmembers) is a lightweight alternative to code-generating a full resource tree from YouTube’s API discovery document, trading some magic for less generated boilerplate. Beyond that, the design follows conventional REST-SDK patterns rather than introducing genuinely novel techniques.