ytstudio-cli 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. ytstudio_cli-0.1.0/.github/workflows/ci.yml +56 -0
  2. ytstudio_cli-0.1.0/.gitignore +14 -0
  3. ytstudio_cli-0.1.0/.pre-commit-config.yaml +16 -0
  4. ytstudio_cli-0.1.0/.python-version +1 -0
  5. ytstudio_cli-0.1.0/LICENSE +21 -0
  6. ytstudio_cli-0.1.0/PKG-INFO +80 -0
  7. ytstudio_cli-0.1.0/README.md +54 -0
  8. ytstudio_cli-0.1.0/demo.gif +0 -0
  9. ytstudio_cli-0.1.0/pyproject.toml +102 -0
  10. ytstudio_cli-0.1.0/src/ytstudio/__init__.py +0 -0
  11. ytstudio_cli-0.1.0/src/ytstudio/api.py +174 -0
  12. ytstudio_cli-0.1.0/src/ytstudio/commands/__init__.py +0 -0
  13. ytstudio_cli-0.1.0/src/ytstudio/commands/analytics.py +570 -0
  14. ytstudio_cli-0.1.0/src/ytstudio/commands/comments.py +176 -0
  15. ytstudio_cli-0.1.0/src/ytstudio/commands/videos.py +475 -0
  16. ytstudio_cli-0.1.0/src/ytstudio/config.py +74 -0
  17. ytstudio_cli-0.1.0/src/ytstudio/demo.py +189 -0
  18. ytstudio_cli-0.1.0/src/ytstudio/demo_data/analytics_metrics.json +103 -0
  19. ytstudio_cli-0.1.0/src/ytstudio/demo_data/channel.json +21 -0
  20. ytstudio_cli-0.1.0/src/ytstudio/demo_data/comments.json +284 -0
  21. ytstudio_cli-0.1.0/src/ytstudio/demo_data/playlist_items.json +26 -0
  22. ytstudio_cli-0.1.0/src/ytstudio/demo_data/videos.json +451 -0
  23. ytstudio_cli-0.1.0/src/ytstudio/main.py +80 -0
  24. ytstudio_cli-0.1.0/src/ytstudio/registry.py +440 -0
  25. ytstudio_cli-0.1.0/src/ytstudio/services.py +14 -0
  26. ytstudio_cli-0.1.0/src/ytstudio/ui.py +106 -0
  27. ytstudio_cli-0.1.0/src/ytstudio/version.py +78 -0
  28. ytstudio_cli-0.1.0/tests/__init__.py +1 -0
  29. ytstudio_cli-0.1.0/tests/conftest.py +159 -0
  30. ytstudio_cli-0.1.0/tests/test_analytics.py +267 -0
  31. ytstudio_cli-0.1.0/tests/test_api.py +60 -0
  32. ytstudio_cli-0.1.0/tests/test_comments.py +49 -0
  33. ytstudio_cli-0.1.0/tests/test_config.py +47 -0
  34. ytstudio_cli-0.1.0/tests/test_registry.py +110 -0
  35. ytstudio_cli-0.1.0/tests/test_videos.py +43 -0
  36. ytstudio_cli-0.1.0/uv.lock +857 -0
@@ -0,0 +1,56 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ tags: ["v*"]
7
+ pull_request:
8
+ branches: [main]
9
+
10
+ jobs:
11
+ test:
12
+ runs-on: ubuntu-latest
13
+ strategy:
14
+ matrix:
15
+ python-version: ["3.12", "3.13"]
16
+
17
+ steps:
18
+ - uses: actions/checkout@v6
19
+
20
+ - name: Install uv
21
+ uses: astral-sh/setup-uv@v7
22
+
23
+ - name: Set up Python ${{ matrix.python-version }}
24
+ run: uv python install ${{ matrix.python-version }}
25
+
26
+ - name: Install dependencies
27
+ run: uv sync --all-extras
28
+
29
+ - name: Lint with ruff
30
+ run: |
31
+ uv run ruff check src tests
32
+ uv run ruff format --check src tests
33
+
34
+ - name: Run tests
35
+ run: uv run pytest
36
+
37
+ publish:
38
+ needs: test
39
+ runs-on: ubuntu-latest
40
+ if: startsWith(github.ref, 'refs/tags/v')
41
+ environment: pypi
42
+
43
+ permissions:
44
+ id-token: write
45
+
46
+ steps:
47
+ - uses: actions/checkout@v6
48
+
49
+ - name: Install uv
50
+ uses: astral-sh/setup-uv@v7
51
+
52
+ - name: Build package
53
+ run: uv build
54
+
55
+ - name: Publish to PyPI
56
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,14 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ *.egg-info/
5
+ dist/
6
+ build/
7
+ .pytest_cache/
8
+ .coverage
9
+ coverage.xml
10
+ htmlcov/
11
+ .ruff_cache/
12
+ .idea/
13
+ .vscode/
14
+ .DS_Store
@@ -0,0 +1,16 @@
1
+ repos:
2
+ - repo: https://github.com/pre-commit/pre-commit-hooks
3
+ rev: v6.0.0
4
+ hooks:
5
+ - id: trailing-whitespace
6
+ - id: end-of-file-fixer
7
+ - id: check-yaml
8
+ - id: check-added-large-files
9
+ - id: check-merge-conflict
10
+
11
+ - repo: https://github.com/astral-sh/ruff-pre-commit
12
+ rev: v0.15.0
13
+ hooks:
14
+ - id: ruff
15
+ args: [--fix]
16
+ - id: ruff-format
@@ -0,0 +1 @@
1
+ 3.12
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jelmer de Wit
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,80 @@
1
+ Metadata-Version: 2.4
2
+ Name: ytstudio-cli
3
+ Version: 0.1.0
4
+ Summary: CLI tool to manage and analyze your YouTube channel from the terminal
5
+ Project-URL: Homepage, https://github.com/jdwit/ytstudio-cli
6
+ Project-URL: Repository, https://github.com/jdwit/ytstudio-cli
7
+ Author-email: Jelmer de Wit <1598297+jdwit@users.noreply.github.com>
8
+ License: MIT
9
+ License-File: LICENSE
10
+ Keywords: analytics,cli,creator,video,youtube,youtube-studio
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Requires-Python: >=3.12
19
+ Requires-Dist: google-api-python-client>=2.0.0
20
+ Requires-Dist: google-auth-oauthlib>=1.0.0
21
+ Requires-Dist: google-auth>=2.0.0
22
+ Requires-Dist: packaging>=21.0
23
+ Requires-Dist: rich>=13.0.0
24
+ Requires-Dist: typer>=0.9.0
25
+ Description-Content-Type: text/markdown
26
+
27
+ # YT Studio CLI
28
+
29
+ [![CI](https://github.com/jdwit/ytstudio/actions/workflows/ci.yml/badge.svg)](https://github.com/jdwit/ytstudio/actions/workflows/ci.yml)
30
+ [![PyPI](https://img.shields.io/pypi/v/ytstudio-cli)](https://pypi.org/project/ytstudio-cli/)
31
+ [![Python](https://img.shields.io/pypi/pyversions/ytstudio-cli)](https://pypi.org/project/ytstudio-cli/)
32
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
33
+
34
+ Manage and analyze your YouTube channel from the terminal. Ideal for automation and AI workflows.
35
+
36
+ ![demo](demo.gif)
37
+
38
+ ## Motivation
39
+
40
+ I built this because I needed to bulk update video titles for a YouTube channel I manage with 300+ videos. YouTube
41
+ Studio does not support bulk search-replace operations, which made it a tedious manual process. This tool uses the
42
+ YouTube Data API to perform bulk operations on video metadata. Furthermore, it provides features for analytics and
43
+ comment moderation, all accesible from the command line.
44
+
45
+ ## Installation
46
+
47
+ I recommend the excellent [uv](https://uv.io/) tool for installation:
48
+
49
+ ```bash
50
+ uv tool install ytstudio-cli
51
+ ```
52
+
53
+ ## Setup
54
+
55
+ 1. Create a [Google Cloud project](https://console.cloud.google.com/)
56
+ 2. Enable **YouTube Data API v3** and **YouTube Analytics API**
57
+ 3. Configure OAuth consent screen:
58
+ - Go to **APIs & Services** → **OAuth consent screen**
59
+ - Select **External** and create
60
+ - Fill in app name and your email
61
+ - Skip scopes, then add yourself as a test user
62
+ - Leave the app in "Testing" mode (no verification needed)
63
+ 4. Create OAuth credentials:
64
+ - Go to **APIs & Services** → **Credentials**
65
+ - Click **Create Credentials** → **OAuth client ID**
66
+ - Select **Desktop app** as application type
67
+ - Download the JSON file
68
+ 5. Configure ytstudio:
69
+
70
+ ```bash
71
+ ytstudio init --client-secrets path/to/client_secret_<id>.json
72
+ ytstudio login
73
+ ```
74
+
75
+ Credentials stored in `~/.config/ytstudio/`.
76
+
77
+ ## Disclaimer
78
+
79
+ This project is not affiliated with or endorsed by Google. YouTube and YouTube Studio are trademarks of Google.
80
+ All channel data is accessed exclusively through the official [YouTube Data API](https://developers.google.com/youtube/v3) and [YouTube Analytics API](https://developers.google.com/youtube/analytics).
@@ -0,0 +1,54 @@
1
+ # YT Studio CLI
2
+
3
+ [![CI](https://github.com/jdwit/ytstudio/actions/workflows/ci.yml/badge.svg)](https://github.com/jdwit/ytstudio/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/ytstudio-cli)](https://pypi.org/project/ytstudio-cli/)
5
+ [![Python](https://img.shields.io/pypi/pyversions/ytstudio-cli)](https://pypi.org/project/ytstudio-cli/)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
+
8
+ Manage and analyze your YouTube channel from the terminal. Ideal for automation and AI workflows.
9
+
10
+ ![demo](demo.gif)
11
+
12
+ ## Motivation
13
+
14
+ I built this because I needed to bulk update video titles for a YouTube channel I manage with 300+ videos. YouTube
15
+ Studio does not support bulk search-replace operations, which made it a tedious manual process. This tool uses the
16
+ YouTube Data API to perform bulk operations on video metadata. Furthermore, it provides features for analytics and
17
+ comment moderation, all accesible from the command line.
18
+
19
+ ## Installation
20
+
21
+ I recommend the excellent [uv](https://uv.io/) tool for installation:
22
+
23
+ ```bash
24
+ uv tool install ytstudio-cli
25
+ ```
26
+
27
+ ## Setup
28
+
29
+ 1. Create a [Google Cloud project](https://console.cloud.google.com/)
30
+ 2. Enable **YouTube Data API v3** and **YouTube Analytics API**
31
+ 3. Configure OAuth consent screen:
32
+ - Go to **APIs & Services** → **OAuth consent screen**
33
+ - Select **External** and create
34
+ - Fill in app name and your email
35
+ - Skip scopes, then add yourself as a test user
36
+ - Leave the app in "Testing" mode (no verification needed)
37
+ 4. Create OAuth credentials:
38
+ - Go to **APIs & Services** → **Credentials**
39
+ - Click **Create Credentials** → **OAuth client ID**
40
+ - Select **Desktop app** as application type
41
+ - Download the JSON file
42
+ 5. Configure ytstudio:
43
+
44
+ ```bash
45
+ ytstudio init --client-secrets path/to/client_secret_<id>.json
46
+ ytstudio login
47
+ ```
48
+
49
+ Credentials stored in `~/.config/ytstudio/`.
50
+
51
+ ## Disclaimer
52
+
53
+ This project is not affiliated with or endorsed by Google. YouTube and YouTube Studio are trademarks of Google.
54
+ All channel data is accessed exclusively through the official [YouTube Data API](https://developers.google.com/youtube/v3) and [YouTube Analytics API](https://developers.google.com/youtube/analytics).
Binary file
@@ -0,0 +1,102 @@
1
+ [project]
2
+ name = "ytstudio-cli"
3
+ version = "0.1.0"
4
+ description = "CLI tool to manage and analyze your YouTube channel from the terminal"
5
+ readme = "README.md"
6
+ license = { text = "MIT" }
7
+ requires-python = ">=3.12"
8
+ authors = [
9
+ { name = "Jelmer de Wit", email = "1598297+jdwit@users.noreply.github.com" }
10
+ ]
11
+ keywords = ["youtube", "youtube-studio", "cli", "analytics", "creator", "video"]
12
+ classifiers = [
13
+ "Development Status :: 3 - Alpha",
14
+ "Environment :: Console",
15
+ "Intended Audience :: Developers",
16
+ "License :: OSI Approved :: MIT License",
17
+ "Programming Language :: Python :: 3",
18
+ "Programming Language :: Python :: 3.12",
19
+ "Programming Language :: Python :: 3.13",
20
+ ]
21
+
22
+ dependencies = [
23
+ "typer>=0.9.0",
24
+ "rich>=13.0.0",
25
+ "google-auth>=2.0.0",
26
+ "google-auth-oauthlib>=1.0.0",
27
+ "google-api-python-client>=2.0.0",
28
+ "packaging>=21.0",
29
+ ]
30
+
31
+ [dependency-groups]
32
+ dev = [
33
+ "pytest>=7.0.0",
34
+ "pytest-cov>=4.0.0",
35
+ "pytest-mock>=3.12.0",
36
+ "ruff>=0.15.0",
37
+ "pre-commit>=3.0.0",
38
+ ]
39
+
40
+ [tool.pytest.ini_options]
41
+ testpaths = ["tests"]
42
+ pythonpath = ["src"]
43
+ addopts = "--cov=ytstudio --cov-report=term-missing --cov-report=xml"
44
+
45
+ [tool.coverage.run]
46
+ source = ["src/ytstudio"]
47
+ branch = true
48
+
49
+ [tool.coverage.report]
50
+ exclude_lines = [
51
+ "pragma: no cover",
52
+ "if TYPE_CHECKING:",
53
+ "raise NotImplementedError",
54
+ ]
55
+
56
+ [project.scripts]
57
+ ytstudio = "ytstudio.main:app"
58
+
59
+ [project.urls]
60
+ Homepage = "https://github.com/jdwit/ytstudio-cli"
61
+ Repository = "https://github.com/jdwit/ytstudio-cli"
62
+
63
+ [build-system]
64
+ requires = ["hatchling"]
65
+ build-backend = "hatchling.build"
66
+
67
+ [tool.hatch.build.targets.wheel]
68
+ packages = ["src/ytstudio"]
69
+
70
+ [tool.ruff]
71
+ line-length = 100
72
+ target-version = "py312"
73
+ src = ["src", "tests"]
74
+
75
+ [tool.ruff.lint]
76
+ select = [
77
+ "E", # pycodestyle errors
78
+ "F", # pyflakes
79
+ "I", # isort
80
+ "W", # pycodestyle warnings
81
+ "UP", # pyupgrade
82
+ "B", # flake8-bugbear
83
+ "SIM", # flake8-simplify
84
+ "RUF", # ruff-specific
85
+ "PTH", # pathlib
86
+ "ERA", # commented-out code
87
+ "PL", # pylint
88
+ ]
89
+ ignore = [
90
+ "E501", # line too long (handled by formatter)
91
+ "B008", # function call in default argument (typer pattern)
92
+ "PLR0913", # too many arguments
93
+ "PLR0912", # too many branches
94
+ "PLR0915", # too many statements
95
+ "PLR2004", # magic value comparison
96
+ ]
97
+
98
+ [tool.ruff.lint.per-file-ignores]
99
+ "tests/*" = ["ERA001"] # allow section comments in test fixtures
100
+
101
+ [tool.ruff.lint.isort]
102
+ known-first-party = ["ytstudio"]
File without changes
@@ -0,0 +1,174 @@
1
+ import typer
2
+ from google.auth.exceptions import RefreshError
3
+ from google.auth.transport.requests import Request
4
+ from google.oauth2.credentials import Credentials
5
+ from google_auth_oauthlib.flow import InstalledAppFlow
6
+ from googleapiclient.discovery import build
7
+ from googleapiclient.errors import HttpError
8
+
9
+ from ytstudio.config import (
10
+ CLIENT_SECRETS_FILE,
11
+ clear_credentials,
12
+ load_credentials,
13
+ save_credentials,
14
+ )
15
+ from ytstudio.ui import console, success_message
16
+
17
+
18
+ def handle_api_error(error: HttpError) -> None:
19
+ if error.resp.status == 403:
20
+ error_details = error.error_details[0] if error.error_details else {}
21
+ reason = error_details.get("reason", "")
22
+
23
+ if reason == "quotaExceeded":
24
+ console.print(
25
+ "[red]Daily YouTube API quota exceeded.[/red] "
26
+ "Quota resets at midnight Pacific Time (PT).\n"
27
+ "See: https://developers.google.com/youtube/v3/guides/quota_and_compliance_audits"
28
+ )
29
+ raise SystemExit(1) from None
30
+
31
+ if reason == "forbidden":
32
+ console.print("[red]Access denied. You may not have permission for this action.[/red]")
33
+ raise SystemExit(1) from None
34
+
35
+ # Re-raise for other errors
36
+ raise error
37
+
38
+
39
+ def api(request):
40
+ """Execute an API request with automatic error handling.
41
+
42
+ Usage:
43
+ response = api(service.videos().list(part="snippet", id=video_id))
44
+ """
45
+ try:
46
+ return request.execute()
47
+ except HttpError as e:
48
+ handle_api_error(e)
49
+ except RefreshError:
50
+ console.print(
51
+ "[red]Session expired or revoked.[/red] Run [bold]ytstudio login[/bold] to re-authenticate."
52
+ )
53
+ raise SystemExit(1) from None
54
+
55
+
56
+ # YouTube API scopes
57
+ SCOPES = [
58
+ "https://www.googleapis.com/auth/youtube.readonly",
59
+ "https://www.googleapis.com/auth/youtube.force-ssl",
60
+ "https://www.googleapis.com/auth/yt-analytics.readonly",
61
+ ]
62
+
63
+
64
+ def authenticate() -> None:
65
+ if not CLIENT_SECRETS_FILE.exists():
66
+ console.print("[red]No client secrets found. Run 'ytstudio init' first.[/red]")
67
+ raise SystemExit(1) from None
68
+
69
+ console.print("[bold]Authenticating with YouTube...[/bold]\n")
70
+
71
+ flow = InstalledAppFlow.from_client_secrets_file(
72
+ str(CLIENT_SECRETS_FILE),
73
+ scopes=SCOPES,
74
+ )
75
+
76
+ # Run local server for OAuth callback
77
+ credentials = flow.run_local_server(
78
+ port=9876,
79
+ prompt="consent",
80
+ open_browser=True,
81
+ )
82
+
83
+ # Save credentials
84
+ creds_data = {
85
+ "token": credentials.token,
86
+ "refresh_token": credentials.refresh_token,
87
+ "token_uri": credentials.token_uri,
88
+ "client_id": credentials.client_id,
89
+ "client_secret": credentials.client_secret,
90
+ "scopes": credentials.scopes,
91
+ }
92
+ save_credentials(creds_data)
93
+
94
+ # Get channel info
95
+ service = build("youtube", "v3", credentials=credentials)
96
+ response = service.channels().list(part="snippet", mine=True).execute()
97
+
98
+ console.print()
99
+ if response.get("items"):
100
+ channel = response["items"][0]["snippet"]
101
+ success_message(f"Logged in as: {channel['title']}")
102
+ else:
103
+ success_message("Authentication successful")
104
+
105
+
106
+ def get_credentials() -> Credentials | None:
107
+ creds_data = load_credentials()
108
+ if not creds_data:
109
+ return None
110
+
111
+ credentials = Credentials(
112
+ token=creds_data.get("token"),
113
+ refresh_token=creds_data.get("refresh_token"),
114
+ token_uri=creds_data.get("token_uri"),
115
+ client_id=creds_data.get("client_id"),
116
+ client_secret=creds_data.get("client_secret"),
117
+ scopes=creds_data.get("scopes"),
118
+ )
119
+
120
+ if credentials.expired and credentials.refresh_token:
121
+ try:
122
+ credentials.refresh(Request())
123
+ except RefreshError:
124
+ console.print(
125
+ "[red]Session expired or revoked.[/red] Run [bold]ytstudio login[/bold] to re-authenticate."
126
+ )
127
+ raise SystemExit(1) from None
128
+ # Save refreshed credentials
129
+ creds_data["token"] = credentials.token
130
+ save_credentials(creds_data)
131
+
132
+ return credentials
133
+
134
+
135
+ def get_authenticated_service(api_name: str = "youtube", version: str = "v3"):
136
+ credentials = get_credentials()
137
+ if not credentials:
138
+ console.print("[red]Not authenticated. Run 'ytstudio login' first.[/red]")
139
+ raise typer.Exit(1)
140
+ return build(api_name, version, credentials=credentials)
141
+
142
+
143
+ def get_status() -> None:
144
+ creds_data = load_credentials()
145
+
146
+ if not creds_data:
147
+ console.print("[yellow]Not authenticated. Run 'ytstudio login' to authenticate.[/yellow]")
148
+ return
149
+
150
+ credentials = get_credentials()
151
+ if not credentials or not credentials.valid:
152
+ console.print(
153
+ "[yellow]Credentials expired. Run 'ytstudio login' to re-authenticate.[/yellow]"
154
+ )
155
+ return
156
+
157
+ # Get channel info
158
+ service = build("youtube", "v3", credentials=credentials)
159
+ response = api(service.channels().list(part="snippet,statistics", mine=True))
160
+
161
+ if response.get("items"):
162
+ channel = response["items"][0]
163
+ snippet = channel["snippet"]
164
+ stats = channel["statistics"]
165
+
166
+ success_message("Authenticated")
167
+ console.print(f" Channel: [bold]{snippet['title']}[/bold]")
168
+ console.print(f" Subscribers: {stats.get('subscriberCount', 'N/A')}")
169
+ console.print(f" Videos: {stats.get('videoCount', 'N/A')}")
170
+
171
+
172
+ def logout() -> None:
173
+ clear_credentials()
174
+ success_message("Logged out successfully")
File without changes