ytstudio-cli 0.1.0__py3-none-any.whl

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.
ytstudio/registry.py ADDED
@@ -0,0 +1,440 @@
1
+ # Reference: https://developers.google.com/youtube/analytics/metrics
2
+ # https://developers.google.com/youtube/analytics/dimensions
3
+
4
+ from dataclasses import dataclass
5
+ from enum import StrEnum
6
+
7
+
8
+ class MetricName(StrEnum):
9
+ # View metrics
10
+ VIEWS = "views"
11
+ ENGAGED_VIEWS = "engagedViews"
12
+ RED_VIEWS = "redViews"
13
+ VIEWER_PERCENTAGE = "viewerPercentage"
14
+ # Reach metrics
15
+ VIDEO_THUMBNAIL_IMPRESSIONS = "videoThumbnailImpressions"
16
+ VIDEO_THUMBNAIL_IMPRESSIONS_CLICK_RATE = "videoThumbnailImpressionsClickRate"
17
+ # Watch time metrics
18
+ ESTIMATED_MINUTES_WATCHED = "estimatedMinutesWatched"
19
+ ESTIMATED_RED_MINUTES_WATCHED = "estimatedRedMinutesWatched"
20
+ AVERAGE_VIEW_DURATION = "averageViewDuration"
21
+ AVERAGE_VIEW_PERCENTAGE = "averageViewPercentage"
22
+ # Engagement metrics
23
+ LIKES = "likes"
24
+ DISLIKES = "dislikes"
25
+ COMMENTS = "comments"
26
+ SHARES = "shares"
27
+ SUBSCRIBERS_GAINED = "subscribersGained"
28
+ SUBSCRIBERS_LOST = "subscribersLost"
29
+ VIDEOS_ADDED_TO_PLAYLISTS = "videosAddedToPlaylists"
30
+ VIDEOS_REMOVED_FROM_PLAYLISTS = "videosRemovedFromPlaylists"
31
+ # Card metrics
32
+ CARD_IMPRESSIONS = "cardImpressions"
33
+ CARD_CLICKS = "cardClicks"
34
+ CARD_CLICK_RATE = "cardClickRate"
35
+ CARD_TEASER_IMPRESSIONS = "cardTeaserImpressions"
36
+ CARD_TEASER_CLICKS = "cardTeaserClicks"
37
+ CARD_TEASER_CLICK_RATE = "cardTeaserClickRate"
38
+ # Annotation metrics
39
+ ANNOTATION_IMPRESSIONS = "annotationImpressions"
40
+ ANNOTATION_CLICKS = "annotationClicks"
41
+ ANNOTATION_CLICK_THROUGH_RATE = "annotationClickThroughRate"
42
+ ANNOTATION_CLOSABLE_IMPRESSIONS = "annotationClosableImpressions"
43
+ ANNOTATION_CLOSES = "annotationCloses"
44
+ ANNOTATION_CLOSE_RATE = "annotationCloseRate"
45
+ ANNOTATION_CLICKABLE_IMPRESSIONS = "annotationClickableImpressions"
46
+ # Revenue metrics
47
+ ESTIMATED_REVENUE = "estimatedRevenue"
48
+ ESTIMATED_AD_REVENUE = "estimatedAdRevenue"
49
+ GROSS_REVENUE = "grossRevenue"
50
+ ESTIMATED_RED_PARTNER_REVENUE = "estimatedRedPartnerRevenue"
51
+ MONETIZED_PLAYBACKS = "monetizedPlaybacks"
52
+ PLAYBACK_BASED_CPM = "playbackBasedCpm"
53
+ AD_IMPRESSIONS = "adImpressions"
54
+ CPM = "cpm"
55
+ # Playlist metrics (in-playlist)
56
+ PLAYLIST_VIEWS = "playlistViews"
57
+ PLAYLIST_STARTS = "playlistStarts"
58
+ VIEWS_PER_PLAYLIST_START = "viewsPerPlaylistStart"
59
+ AVERAGE_TIME_IN_PLAYLIST = "averageTimeInPlaylist"
60
+ PLAYLIST_SAVES = "playlistSaves"
61
+ PLAYLIST_ESTIMATED_MINUTES_WATCHED = "playlistEstimatedMinutesWatched"
62
+ PLAYLIST_AVERAGE_VIEW_DURATION = "playlistAverageViewDuration"
63
+ # Unique viewers
64
+ UNIQUES = "uniques"
65
+
66
+
67
+ class DimensionName(StrEnum):
68
+ # Time
69
+ DAY = "day"
70
+ MONTH = "month"
71
+ # Geographic
72
+ COUNTRY = "country"
73
+ PROVINCE = "province"
74
+ CITY = "city"
75
+ CONTINENT = "continent"
76
+ SUB_CONTINENT = "subContinent"
77
+ DMA = "dma"
78
+ # Content
79
+ VIDEO = "video"
80
+ PLAYLIST = "playlist"
81
+ GROUP = "group"
82
+ CREATOR_CONTENT_TYPE = "creatorContentType"
83
+ # Traffic sources
84
+ INSIGHT_TRAFFIC_SOURCE_TYPE = "insightTrafficSourceType"
85
+ INSIGHT_TRAFFIC_SOURCE_DETAIL = "insightTrafficSourceDetail"
86
+ # Playback
87
+ PLAYBACK_LOCATION_TYPE = "playbackLocationType"
88
+ LIVE_OR_ON_DEMAND = "liveOrOnDemand"
89
+ # Device
90
+ DEVICE_TYPE = "deviceType"
91
+ OPERATING_SYSTEM = "operatingSystem"
92
+ # Audience
93
+ AGE_GROUP = "ageGroup"
94
+ GENDER = "gender"
95
+ SUBSCRIBED_STATUS = "subscribedStatus"
96
+ YOUTUBE_PRODUCT = "youtubeProduct"
97
+ # Sharing
98
+ SHARING_SERVICE = "sharingService"
99
+ # Ads
100
+ AD_TYPE = "adType"
101
+
102
+
103
+ @dataclass(frozen=True)
104
+ class Metric:
105
+ name: MetricName
106
+ description: str
107
+ group: str
108
+ core: bool = False
109
+ monetary: bool = False # requires yt-analytics-monetary.readonly scope
110
+
111
+
112
+ @dataclass(frozen=True)
113
+ class Dimension:
114
+ name: DimensionName
115
+ description: str
116
+ group: str
117
+ filter_only: bool = False # can only be used as filter, not as dimension
118
+
119
+
120
+ # --- Metrics ---
121
+
122
+ METRICS: dict[MetricName, Metric] = {
123
+ m.name: m
124
+ for m in [
125
+ # View metrics
126
+ Metric(MetricName.VIEWS, "Number of times videos were viewed", "views", core=True),
127
+ Metric(MetricName.ENGAGED_VIEWS, "Views past the initial seconds", "views", core=True),
128
+ Metric(MetricName.RED_VIEWS, "Views by YouTube Premium members", "views"),
129
+ Metric(MetricName.VIEWER_PERCENTAGE, "Percentage of logged-in viewers", "views", core=True),
130
+ # Reach metrics
131
+ Metric(
132
+ MetricName.VIDEO_THUMBNAIL_IMPRESSIONS,
133
+ "Times thumbnails were shown to viewers",
134
+ "reach",
135
+ ),
136
+ Metric(
137
+ MetricName.VIDEO_THUMBNAIL_IMPRESSIONS_CLICK_RATE,
138
+ "Percentage of impressions that became views (CTR)",
139
+ "reach",
140
+ ),
141
+ # Watch time metrics
142
+ Metric(
143
+ MetricName.ESTIMATED_MINUTES_WATCHED,
144
+ "Total minutes watched",
145
+ "watch_time",
146
+ core=True,
147
+ ),
148
+ Metric(
149
+ MetricName.ESTIMATED_RED_MINUTES_WATCHED,
150
+ "Minutes watched by YouTube Premium members",
151
+ "watch_time",
152
+ ),
153
+ Metric(
154
+ MetricName.AVERAGE_VIEW_DURATION,
155
+ "Average playback length in seconds",
156
+ "watch_time",
157
+ core=True,
158
+ ),
159
+ Metric(
160
+ MetricName.AVERAGE_VIEW_PERCENTAGE,
161
+ "Average percentage of video watched",
162
+ "watch_time",
163
+ ),
164
+ # Engagement metrics
165
+ Metric(MetricName.LIKES, "Number of likes", "engagement", core=True),
166
+ Metric(MetricName.DISLIKES, "Number of dislikes", "engagement", core=True),
167
+ Metric(MetricName.COMMENTS, "Number of comments", "engagement", core=True),
168
+ Metric(MetricName.SHARES, "Number of shares via the Share button", "engagement", core=True),
169
+ Metric(MetricName.SUBSCRIBERS_GAINED, "New subscribers gained", "engagement", core=True),
170
+ Metric(MetricName.SUBSCRIBERS_LOST, "Subscribers lost", "engagement", core=True),
171
+ Metric(
172
+ MetricName.VIDEOS_ADDED_TO_PLAYLISTS,
173
+ "Times videos were added to any playlist",
174
+ "engagement",
175
+ ),
176
+ Metric(
177
+ MetricName.VIDEOS_REMOVED_FROM_PLAYLISTS,
178
+ "Times videos were removed from any playlist",
179
+ "engagement",
180
+ ),
181
+ # Card metrics
182
+ Metric(MetricName.CARD_IMPRESSIONS, "Number of card impressions", "cards"),
183
+ Metric(MetricName.CARD_CLICKS, "Number of card clicks", "cards"),
184
+ Metric(MetricName.CARD_CLICK_RATE, "Card click-through rate", "cards"),
185
+ Metric(MetricName.CARD_TEASER_IMPRESSIONS, "Number of card teaser impressions", "cards"),
186
+ Metric(MetricName.CARD_TEASER_CLICKS, "Number of card teaser clicks", "cards"),
187
+ Metric(MetricName.CARD_TEASER_CLICK_RATE, "Card teaser click-through rate", "cards"),
188
+ # Annotation metrics
189
+ Metric(MetricName.ANNOTATION_IMPRESSIONS, "Total annotation impressions", "annotations"),
190
+ Metric(MetricName.ANNOTATION_CLICKS, "Number of annotation clicks", "annotations"),
191
+ Metric(
192
+ MetricName.ANNOTATION_CLICK_THROUGH_RATE,
193
+ "Annotation click-through rate",
194
+ "annotations",
195
+ core=True,
196
+ ),
197
+ Metric(
198
+ MetricName.ANNOTATION_CLOSABLE_IMPRESSIONS,
199
+ "Closable annotation impressions",
200
+ "annotations",
201
+ ),
202
+ Metric(MetricName.ANNOTATION_CLOSES, "Number of annotation closes", "annotations"),
203
+ Metric(MetricName.ANNOTATION_CLOSE_RATE, "Annotation close rate", "annotations", core=True),
204
+ Metric(
205
+ MetricName.ANNOTATION_CLICKABLE_IMPRESSIONS,
206
+ "Clickable annotation impressions",
207
+ "annotations",
208
+ ),
209
+ # Revenue metrics
210
+ Metric(
211
+ MetricName.ESTIMATED_REVENUE,
212
+ "Estimated total net revenue",
213
+ "revenue",
214
+ core=True,
215
+ monetary=True,
216
+ ),
217
+ Metric(
218
+ MetricName.ESTIMATED_AD_REVENUE,
219
+ "Estimated ad net revenue",
220
+ "revenue",
221
+ monetary=True,
222
+ ),
223
+ Metric(
224
+ MetricName.GROSS_REVENUE,
225
+ "Estimated gross revenue from ads",
226
+ "revenue",
227
+ monetary=True,
228
+ ),
229
+ Metric(
230
+ MetricName.ESTIMATED_RED_PARTNER_REVENUE,
231
+ "Estimated YouTube Premium revenue",
232
+ "revenue",
233
+ monetary=True,
234
+ ),
235
+ Metric(
236
+ MetricName.MONETIZED_PLAYBACKS,
237
+ "Playbacks that showed at least one ad",
238
+ "revenue",
239
+ monetary=True,
240
+ ),
241
+ Metric(
242
+ MetricName.PLAYBACK_BASED_CPM,
243
+ "Estimated gross revenue per 1000 playbacks",
244
+ "revenue",
245
+ monetary=True,
246
+ ),
247
+ Metric(
248
+ MetricName.AD_IMPRESSIONS,
249
+ "Number of verified ad impressions",
250
+ "revenue",
251
+ monetary=True,
252
+ ),
253
+ Metric(
254
+ MetricName.CPM,
255
+ "Estimated gross revenue per 1000 ad impressions",
256
+ "revenue",
257
+ monetary=True,
258
+ ),
259
+ # Playlist metrics (in-playlist)
260
+ Metric(MetricName.PLAYLIST_VIEWS, "Video views in the context of a playlist", "playlist"),
261
+ Metric(
262
+ MetricName.PLAYLIST_STARTS,
263
+ "Number of times playlist playback was initiated",
264
+ "playlist",
265
+ ),
266
+ Metric(
267
+ MetricName.VIEWS_PER_PLAYLIST_START,
268
+ "Average views per playlist start",
269
+ "playlist",
270
+ ),
271
+ Metric(
272
+ MetricName.AVERAGE_TIME_IN_PLAYLIST,
273
+ "Average time (min) viewers spent in playlist",
274
+ "playlist",
275
+ ),
276
+ Metric(MetricName.PLAYLIST_SAVES, "Net number of playlist saves", "playlist"),
277
+ Metric(
278
+ MetricName.PLAYLIST_ESTIMATED_MINUTES_WATCHED,
279
+ "Minutes watched in playlist context",
280
+ "playlist",
281
+ ),
282
+ Metric(
283
+ MetricName.PLAYLIST_AVERAGE_VIEW_DURATION,
284
+ "Average video view length in playlist context",
285
+ "playlist",
286
+ ),
287
+ # Unique viewers
288
+ Metric(MetricName.UNIQUES, "Estimated unique viewers", "audience"),
289
+ ]
290
+ }
291
+
292
+ # --- Dimensions ---
293
+
294
+ DIMENSIONS: dict[DimensionName, Dimension] = {
295
+ d.name: d
296
+ for d in [
297
+ # Time
298
+ Dimension(DimensionName.DAY, "Date in YYYY-MM-DD format", "time"),
299
+ Dimension(DimensionName.MONTH, "Month in YYYY-MM format", "time"),
300
+ # Geographic
301
+ Dimension(DimensionName.COUNTRY, "Two-letter ISO 3166-1 country code", "geographic"),
302
+ Dimension(
303
+ DimensionName.PROVINCE,
304
+ "US state (ISO 3166-2, requires country==US filter)",
305
+ "geographic",
306
+ ),
307
+ Dimension(DimensionName.CITY, "Estimated city (available from 2022-01-01)", "geographic"),
308
+ Dimension(
309
+ DimensionName.CONTINENT, "UN statistical region code", "geographic", filter_only=True
310
+ ),
311
+ Dimension(
312
+ DimensionName.SUB_CONTINENT, "UN sub-region code", "geographic", filter_only=True
313
+ ),
314
+ Dimension(DimensionName.DMA, "Nielsen Designated Market Area (3-digit)", "geographic"),
315
+ # Content
316
+ Dimension(DimensionName.VIDEO, "YouTube video ID", "content"),
317
+ Dimension(DimensionName.PLAYLIST, "YouTube playlist ID", "content"),
318
+ Dimension(DimensionName.GROUP, "YouTube Analytics group ID", "content", filter_only=True),
319
+ Dimension(
320
+ DimensionName.CREATOR_CONTENT_TYPE,
321
+ "Content type: shorts, videos, or live",
322
+ "content",
323
+ ),
324
+ # Traffic sources
325
+ Dimension(DimensionName.INSIGHT_TRAFFIC_SOURCE_TYPE, "Traffic source category", "traffic"),
326
+ Dimension(
327
+ DimensionName.INSIGHT_TRAFFIC_SOURCE_DETAIL,
328
+ "Specific traffic source (search term, URL)",
329
+ "traffic",
330
+ ),
331
+ # Playback
332
+ Dimension(
333
+ DimensionName.PLAYBACK_LOCATION_TYPE,
334
+ "Where the video was played (watch page, embed, etc)",
335
+ "playback",
336
+ ),
337
+ Dimension(
338
+ DimensionName.LIVE_OR_ON_DEMAND,
339
+ "Whether content was live or on-demand",
340
+ "playback",
341
+ ),
342
+ # Device
343
+ Dimension(
344
+ DimensionName.DEVICE_TYPE,
345
+ "Device type (mobile, desktop, tablet, tv, etc)",
346
+ "device",
347
+ ),
348
+ Dimension(DimensionName.OPERATING_SYSTEM, "Operating system", "device"),
349
+ # Audience
350
+ Dimension(DimensionName.AGE_GROUP, "Viewer age group", "audience"),
351
+ Dimension(DimensionName.GENDER, "Viewer gender", "audience"),
352
+ Dimension(DimensionName.SUBSCRIBED_STATUS, "Whether viewer is subscribed", "audience"),
353
+ Dimension(
354
+ DimensionName.YOUTUBE_PRODUCT,
355
+ "YouTube product (main, shorts, music, etc)",
356
+ "audience",
357
+ ),
358
+ # Sharing
359
+ Dimension(
360
+ DimensionName.SHARING_SERVICE,
361
+ "Service used to share (whatsapp, twitter, etc)",
362
+ "sharing",
363
+ ),
364
+ # Ads
365
+ Dimension(DimensionName.AD_TYPE, "Type of ad that ran during playback", "ads"),
366
+ ]
367
+ }
368
+
369
+ METRIC_GROUPS = sorted({m.group for m in METRICS.values()})
370
+ DIMENSION_GROUPS = sorted({d.group for d in DIMENSIONS.values()})
371
+
372
+
373
+ def find_closest_metric(name: str, max_distance: int = 3) -> str | None:
374
+ """Find the closest matching metric name for typo suggestions."""
375
+ return _find_closest(name, list(METRICS.keys()), max_distance)
376
+
377
+
378
+ def find_closest_dimension(name: str, max_distance: int = 3) -> str | None:
379
+ """Find the closest matching dimension name for typo suggestions."""
380
+ return _find_closest(name, list(DIMENSIONS.keys()), max_distance)
381
+
382
+
383
+ def _find_closest(name: str, candidates: list[str], max_distance: int) -> str | None:
384
+ """Simple Levenshtein-based closest match."""
385
+ best = None
386
+ best_dist = max_distance + 1
387
+
388
+ for candidate in candidates:
389
+ dist = _levenshtein(name.lower(), candidate.lower())
390
+ if dist < best_dist:
391
+ best_dist = dist
392
+ best = candidate
393
+
394
+ return best if best_dist <= max_distance else None
395
+
396
+
397
+ def _levenshtein(s1: str, s2: str) -> int:
398
+ if len(s1) < len(s2):
399
+ return _levenshtein(s2, s1)
400
+
401
+ if len(s2) == 0:
402
+ return len(s1)
403
+
404
+ prev_row = range(len(s2) + 1)
405
+ for i, c1 in enumerate(s1):
406
+ curr_row = [i + 1]
407
+ for j, c2 in enumerate(s2):
408
+ insertions = prev_row[j + 1] + 1
409
+ deletions = curr_row[j] + 1
410
+ substitutions = prev_row[j] + (c1 != c2)
411
+ curr_row.append(min(insertions, deletions, substitutions))
412
+ prev_row = curr_row
413
+
414
+ return prev_row[-1]
415
+
416
+
417
+ def validate_metrics(names: list[str]) -> list[str]:
418
+ """Validate metric names, return list of errors."""
419
+ errors = []
420
+ for name in names:
421
+ if name not in METRICS:
422
+ suggestion = find_closest_metric(name)
423
+ msg = f"Unknown metric '{name}'."
424
+ if suggestion:
425
+ msg += f" Did you mean '{suggestion}'?"
426
+ errors.append(msg)
427
+ return errors
428
+
429
+
430
+ def validate_dimensions(names: list[str]) -> list[str]:
431
+ """Validate dimension names, return list of errors."""
432
+ errors = []
433
+ for name in names:
434
+ if name not in DIMENSIONS:
435
+ suggestion = find_closest_dimension(name)
436
+ msg = f"Unknown dimension '{name}'."
437
+ if suggestion:
438
+ msg += f" Did you mean '{suggestion}'?"
439
+ errors.append(msg)
440
+ return errors
ytstudio/services.py ADDED
@@ -0,0 +1,14 @@
1
+ from ytstudio.api import get_authenticated_service
2
+ from ytstudio.demo import DemoAnalyticsService, DemoDataService, is_demo_mode
3
+
4
+
5
+ def get_data_service():
6
+ if is_demo_mode():
7
+ return DemoDataService()
8
+ return get_authenticated_service("youtube", "v3")
9
+
10
+
11
+ def get_analytics_service():
12
+ if is_demo_mode():
13
+ return DemoAnalyticsService()
14
+ return get_authenticated_service("youtubeAnalytics", "v2")
ytstudio/ui.py ADDED
@@ -0,0 +1,106 @@
1
+ from datetime import UTC, datetime
2
+
3
+ from rich.console import Console
4
+ from rich.table import Table
5
+
6
+ console = Console()
7
+
8
+
9
+ def create_table(title: str | None = None, show_header: bool = True) -> Table:
10
+ return Table(
11
+ title=title,
12
+ box=None,
13
+ show_header=show_header,
14
+ pad_edge=False,
15
+ collapse_padding=True,
16
+ header_style="dim",
17
+ )
18
+
19
+
20
+ def create_kv_table() -> Table:
21
+ return Table(
22
+ box=None,
23
+ show_header=False,
24
+ pad_edge=False,
25
+ collapse_padding=True,
26
+ padding=(0, 2, 0, 0),
27
+ )
28
+
29
+
30
+ _state = {"raw": False}
31
+
32
+
33
+ def set_raw_output(value: bool):
34
+ _state["raw"] = value
35
+
36
+
37
+ def format_number(n: int) -> str:
38
+ if _state["raw"]:
39
+ return str(n)
40
+ if n >= 1_000_000:
41
+ return f"{n / 1_000_000:.1f}M"
42
+ if n >= 1_000:
43
+ return f"{n / 1_000:.1f}K"
44
+ return str(n)
45
+
46
+
47
+ def time_ago(iso_timestamp: str) -> str:
48
+ """Format ISO timestamp as relative time (2h ago, 3d ago)"""
49
+ dt = datetime.fromisoformat(iso_timestamp.replace("Z", "+00:00"))
50
+ delta = datetime.now(UTC) - dt
51
+
52
+ if delta.days > 365:
53
+ return f"{delta.days // 365}y ago"
54
+ if delta.days > 30:
55
+ return f"{delta.days // 30}mo ago"
56
+ if delta.days > 0:
57
+ return f"{delta.days}d ago"
58
+ if delta.seconds > 3600:
59
+ return f"{delta.seconds // 3600}h ago"
60
+ return "recently"
61
+
62
+
63
+ def dim(text: str) -> str:
64
+ return f"[dim]{text}[/dim]"
65
+
66
+
67
+ def muted(text: str) -> str:
68
+ return f"[dim]{text}[/dim]"
69
+
70
+
71
+ def id_style(text: str) -> str:
72
+ return f"[yellow]{text}[/yellow]"
73
+
74
+
75
+ def cyan(text: str) -> str:
76
+ return f"[cyan]{text}[/cyan]"
77
+
78
+
79
+ def bold(text: str) -> str:
80
+ return f"[bold]{text}[/bold]"
81
+
82
+
83
+ def success(text: str) -> str:
84
+ return f"[green]{text}[/green]"
85
+
86
+
87
+ def success_message(text: str) -> None:
88
+ console.print(f"[green]✓ {text}[/green]")
89
+
90
+
91
+ def error(text: str) -> str:
92
+ return f"[red]{text}[/red]"
93
+
94
+
95
+ def warning(text: str) -> str:
96
+ return f"[yellow]{text}[/yellow]"
97
+
98
+
99
+ def link(text: str, url: str) -> str:
100
+ return f"[cyan][link={url}]{text}[/link][/cyan]"
101
+
102
+
103
+ def truncate(text: str, length: int = 60) -> str:
104
+ if len(text) > length:
105
+ return text[:length] + "..."
106
+ return text
ytstudio/version.py ADDED
@@ -0,0 +1,78 @@
1
+ import json
2
+ import urllib.request
3
+ from datetime import datetime, timedelta
4
+ from importlib.metadata import version
5
+
6
+ from packaging.version import Version
7
+
8
+ from ytstudio.config import CONFIG_DIR
9
+
10
+ VERSION_CACHE_FILE = CONFIG_DIR / "version_check.json"
11
+ PYPI_URL = "https://pypi.org/pypi/ytstudio-cli/json"
12
+ CACHE_DURATION = timedelta(days=1)
13
+
14
+
15
+ def get_current_version() -> str:
16
+ return version("ytstudio-cli")
17
+
18
+
19
+ def check_pypi_version() -> str | None:
20
+ """Fetch the latest version from PyPI, returns None on failure"""
21
+ try:
22
+ with urllib.request.urlopen(PYPI_URL, timeout=5) as response:
23
+ data = json.loads(response.read().decode())
24
+ return data["info"]["version"]
25
+ except Exception:
26
+ return None
27
+
28
+
29
+ def _load_cache() -> dict | None:
30
+ if not VERSION_CACHE_FILE.exists():
31
+ return None
32
+ try:
33
+ return json.loads(VERSION_CACHE_FILE.read_text())
34
+ except Exception:
35
+ return None
36
+
37
+
38
+ def _save_cache(latest_version: str) -> None:
39
+ CONFIG_DIR.mkdir(parents=True, exist_ok=True)
40
+ cache = {
41
+ "latest_version": latest_version,
42
+ "checked_at": datetime.now().isoformat(),
43
+ }
44
+ VERSION_CACHE_FILE.write_text(json.dumps(cache))
45
+
46
+
47
+ def _is_cache_valid(cache: dict) -> bool:
48
+ try:
49
+ checked_at = datetime.fromisoformat(cache["checked_at"])
50
+ return datetime.now() - checked_at < CACHE_DURATION
51
+ except Exception:
52
+ return False
53
+
54
+
55
+ def get_latest_version(use_cache: bool = True) -> str | None:
56
+ """Get latest version, using cache if available and valid"""
57
+ if use_cache:
58
+ cache = _load_cache()
59
+ if cache and _is_cache_valid(cache):
60
+ return cache.get("latest_version")
61
+
62
+ latest = check_pypi_version()
63
+ if latest:
64
+ _save_cache(latest)
65
+ return latest
66
+
67
+
68
+ def is_update_available() -> tuple[bool, str | None]:
69
+ """Check if an update is available. Returns (is_available, latest_version)"""
70
+ latest = get_latest_version()
71
+ if not latest:
72
+ return False, None
73
+
74
+ current = get_current_version()
75
+ try:
76
+ return Version(latest) > Version(current), latest
77
+ except Exception:
78
+ return False, None