supadata/youtube.py (1)

433-479: _Video class largely duplicates the top-level video method logic.

Consider removing the older YouTube.video() method or consolidating them to limit code duplication and ensure a single source of truth.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

supadata/youtube.py (3)

632-679: Well-implemented translate method.

The translate method in the _Transcript class properly handles translation requests and error cases, with good defaults for missing fields.

Note that this duplicates the top-level translate method logic, which was previously flagged in reviews. Consider having one implementation call the other to avoid future maintenance issues.

---

203-216: ⚠️ Potential issue

Name conflict with existing video method.

The property video conflicts with the existing method of the same name at line 127. This was previously flagged and marked as addressed in commit 07076bc, but still appears in the code.

- @property
- def video(self) -> "_Video":
+ @property
+ def video_ops(self) -> "_Video":

🧰 Tools

🪛 Ruff (0.8.2)

203-203: Redefinition of unused video from line 127

(F811)

---

219-232: ⚠️ Potential issue

Name conflict with existing transcript method.

The property transcript conflicts with the existing method of the same name at line 85. This was previously flagged and marked as addressed in commit 07076bc, but still appears in the code.

- @property
- def transcript(self) -> "_Transcript":
+ @property
+ def transcript_ops(self) -> "_Transcript":

🧰 Tools

🪛 Ruff (0.8.2)

219-219: Redefinition of unused transcript from line 85

(F811)

supadata/youtube.py (1)

460-544: Comprehensive _Video class implementation.

The _Video class is well-implemented with:

• Proper initialization
• Duplicate functionality of the top-level video method in call
• A new batch method for batch operations
• Good docstrings and error handling

However, note that the call method duplicates logic from the top-level video method. While this works, it creates maintenance overhead if one changes and the other doesn't.

Consider having the top-level video method call this implementation to maintain a single source of truth:

def video(self, id: str) -> YoutubeVideo:
-    response: dict = self._request("GET", "/youtube/video", params={"id": id})
-    
-    # Safely convert upload_date with fallback
-    try:
-        uploaded_time = datetime.fromisoformat(response.pop("upload_date", datetime.now().isoformat()))
-    except (ValueError, TypeError):
-        uploaded_time = datetime.now()
-    
-    # Ensure all required fields have defaults
-    defaults = {
-        "id": id,
-        "title": "",
-        "description": "",
-        "duration": 0,
-        "channel": {"id": "", "name": ""},
-        "tags": [],
-        "thumbnail": "",
-        "view_count": 0,
-        "like_count": 0,
-        "transcript_languages": [],
-    }
-    
-    # Apply defaults for any missing fields
-    for key, default_value in defaults.items():
-        if key not in response:
-            response[key] = default_value
-        elif key == "channel" and not isinstance(response[key], dict):
-            response[key] = defaults[key]
-
-    return YoutubeVideo(**response, uploaded_date=uploaded_time)
+    # Delegate to the _Video class
+    if self._video_instance is None:
+        self._video_instance = self._Video(self)
+    return self._video_instance(id)

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

supadata/youtube.py (3)

315-319: Fix non‑PEP‑8 indentation inside _Transcript.translate

Line 317 starts with 13 spaces, breaking the 4‑space convention and causing mismatched‑indent visuals in many editors.

-             processed_content = [
+            processed_content = [

(Only whitespace changed.)

---

511-561: Cache helper namespace objects to reduce repeated allocations

Each access to properties like .channel, .video, .transcript, … returns a new helper object.
For hot paths (e.g. polling in a tight loop) this Needlessly creates dozens of identical objects.

A lightweight memoisation keeps the ergonomic property API while avoiding churn:

 class YouTube:
@@
-    @property
-    def channel(self) -> _Channel:
+    @property
+    def channel(self) -> _Channel:
         ...
-        return _Channel(self) # Return a new instance each time
+        if not hasattr(self, "_chan"):
+            self._chan = _Channel(self)
+        return self._chan

Apply the same pattern to the other namespace properties.

---

456-460: Surface API errors early by validating expected keys in BatchJob payload

_create_batch_job blindly forwards the entire JSON into BatchJob(**response).
If the backend ever changes field names, you’ll get a cryptic TypeError: __init__() got an unexpected keyword argument ....

Quick guard:

 def _create_batch_job(...):
     response = self._request("POST", endpoint, json=payload)
-    return BatchJob(**response)
+    try:
+        return BatchJob(**response)
+    except TypeError as exc:
+        raise SupadataError(
+            error="invalid-response",
+            message="Unexpected batch job schema",
+            details=str(exc),
+        ) from exc

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

supadata/youtube.py (2)

19-21: ⚠️ Potential issue

Fix YouTube class forward declaration to prevent redefinition error.

The current forward declaration creates a second YouTube class at runtime that is later redefined, triggering the Ruff F811 warning. This can potentially break isinstance()/issubclass() checks.

Use a proper type-checking-only forward declaration:

-from typing import Any, Callable, Dict, List, Optional, Literal
+from typing import Any, Callable, Dict, List, Optional, Literal, TYPE_CHECKING

-# Forward declare YouTube for type hints in private classes
-class YouTube:
-    pass
+# Forward declaration for static type checkers only
+if TYPE_CHECKING:
+    class YouTube: ...

---

443-451: 🛠️ Refactor suggestion

Explicitly handle limit parameter when video_ids is provided.

Currently, when only video_ids is provided with a limit, the limit is silently ignored. This diverges from how limit is handled with playlist_id or channel_id and could lead to unexpected behavior.

Consider either enforcing the limit or raising an error for clarity:

 if playlist_id or channel_id:
     payload["limit"] = limit
 elif video_ids and limit is not None:
-    # Optionally warn or ignore limit if only video_ids are provided?
-    # Current behavior: limit is ignored by API if only video_ids are sent.
-    pass
+    # Option 1: Enforce the limit by slicing video_ids
+    payload["videoIds"] = video_ids[:limit]
+    
+    # Option 2: Alternatively, raise an error for clarity
+    # raise SupadataError(
+    #    error="invalid-request", 
+    #    message="Limit cannot be used with video_ids directly.",
+    #    details="Either paginate via playlist/channel or omit the limit parameter."
+    # )

supadata/youtube.py (1)

510-596: Fix docstring examples to match actual function signatures.

The docstring examples show function calls with named arguments (e.g., supadata.youtube.channel(id="UC_...")) while the actual functions use positional parameters (e.g., def __call__(self, id: str)).

Update the examples to match the actual function signatures:

- channel_info = supadata.youtube.channel(id="UC_...")
+ channel_info = supadata.youtube.channel("UC_...")

- videos = supadata.youtube.channel.videos(id="UC_...")
+ videos = supadata.youtube.channel.videos("UC_...")

- batch_job = supadata.youtube.channel.batch(channel_id="UC_...")
+ batch_job = supadata.youtube.channel.batch(channel_id="UC_...")

- playlist_info = supadata.youtube.playlist(id="PL_...")
+ playlist_info = supadata.youtube.playlist("PL_...")

- videos = supadata.youtube.playlist.videos(id="PL_...")
+ videos = supadata.youtube.playlist.videos("PL_...")

- video_info = supadata.youtube.video(id="dQw4w9WgXcQ")
+ video_info = supadata.youtube.video("dQw4w9WgXcQ")

- transcript = supadata.youtube.transcript(video_id="dQw4w9WgXcQ")
+ transcript = supadata.youtube.transcript("dQw4w9WgXcQ")

Note that batch methods correctly use named parameters in the examples.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro