API Reference
If the API reference does not have the documentation for any method. See the source code, since all methods do have docstrings that you can use.
Submodules
sponsorblock.client module
The client module provides a Client for the SponsorBlock API.
Module for the client class.
- class sponsorblock.client.Client(*args, **kwargs)
Bases:
object
A client for making requests to the sponsorblock server.
- add_skip_segments(video_id: str, *, segment: Segment | None = None, segments: List[Segment] | None = None, service: str = 'YouTube') None
Add a skip segment to the server.
- Parameters:
video_id (str) – The id of the video to add the skip segment to, can be a video url too.
segment (Segment) – The skip segment to add
segments (List[Segment]) – The list of skip segments to add
service (str) – The service to use, default is ‘YouTube’. See https://wiki.sponsor.ajay.app/w/Types#service.
- Raises:
ValueError – No segments were specified
ValueError – The video id is invalid
InvalidJSONException – The server returned invalid JSON
BadRequest – The server returned a 400 error, most likely because your inputs are wrong/impossible
Forbidden – The server returned a 403 error, most likely because you are not allowed to add skip segments
RateLimitException – The server returned a 429 error, most likely because you are making too many requests
DuplicateException – The server returned a 409 error, most likely because the skip segment already exists
ServerException – The server returned a 500 error, most likely because the server is down
UnexpectedException – The server returned a response code that is not handled
Examples
>>> """Adding new segments to a YouTube video (Note: this is a example and don't try this yourself)""" >>> import sponsorblock as sb >>> client = sb.Client() >>> client.add_skip_segments( "https://www.youtube.com/watch?v=kJQP7kiw5Fk", segment=sb.Segment(category="music_offtopic", start=0, end=21.808434, action_type="skip") )
- get_saved_days_formatted()
- get_saved_time_for_user()
- get_segment_info()
- get_skip_segments()
- get_skip_segments_with_hash()
- get_top_users()
- get_total_stats()
- get_user_info()
- get_user_name()
- get_views_for_user()
- post_viewed_video_sponsor_time(uuid: Segment | str)
Notifies the server that a segment has been skipped.
- Parameters:
uuid (Union[Segment, str]) – The uuid of the segment that was skipped
- Raises:
BadRequest – The server returned a 400 error, most likely because your inputs are wrong/impossible
ServerException – The server returned a 500 error, most likely because the server is down
UnexpectedException – The server returned a response that was not 200, 400, or 500
Examples
>>> import sponsorblock as sb >>> client = sb.Client() >>> segments = client.get_skip_segments("https://www.youtube.com/watch?v=kJQP7kiw5Fk") >>> client.post_viewed_video_sponsor_time(segments[1])
- search_for_user()
- set_user_name(user_name: str)
Sets the user name for the current user.
- Parameters:
user_name (str) – The user name to set for the current user.
- Raises:
BadRequest – The server returned a 400 error, most likely because your inputs are wrong/impossible
ServerException – The server returned a 500 error, most likely because the server is down
UnexpectedException – The server returned a response that was not 200, 400, or 500
Examples
>>> import sponsorblock as sb >>> client = sb.Client("your local user id") >>> client.set_user_name("NoobMaster69")
- vote_skip_segment(uuid: Segment | str, *, vote: str | int | bool | None = None, category: Literal['sponsor', 'selfpromo', 'interaction', 'intro', 'outro', 'preview', 'music_offtopic', 'poi_highlight', 'filler'] | None = None) None
Votes on a skip segment.
- Parameters:
uuid (Union[Segment, str]) – segment or uuid of the segment being voted on
vote (Union[str, int, bool], optional) – The vote to vote on the skip segment. Can be any of
yes
,upvote
,up
,good
,1
,True
for upvoting,no
,downvote
,down
,bad
,0
,False
for downvoting, andundo
for undoing a given votecategory (Category, optional) – The category of the skip segment. This can be used as an alternative to the vote parameter, by default None
- Raises:
ValueError – You passed both vote and category.
BadRequest – The server returned a 400 error, most likely because your inputs are wrong/impossible
Forbidden – The server returned a 403 error, most likely because you are not allowed to vote on the skip segment
ServerException – The server returned a error, most likely because the server is down
UnexpectedException – The server returned a response that was not 200, 400, 403, 429, 409, or 500
Examples
>>> import sponsorblock as sb >>> client = sb.Client() >>> segments = client.get_skip_segments("https://www.youtube.com/watch?v=kJQP7kiw5Fk") >>> client.vote_skip_segment(segments[0], 'yes')
- sponsorblock.client.raise_request_exception(response: Response)
If the server returns a status code, which is not 200, it needs to raise an exception:
Every exception inherits from HTTPException
- Parameters:
response –
- Returns:
sponsorblock.models module
- class sponsorblock.models.SearchedUser(data)
Bases:
object
A user gotten by searching for his name
Warning
You should not make a instance of this yourself, this should only be created by the libray
- class sponsorblock.models.Segment(category: Literal['sponsor', 'selfpromo', 'interaction', 'intro', 'outro', 'preview', 'music_offtopic', 'poi_highlight', 'filler'], start: float | timedelta, end: float | timedelta, uuid: str | None = None, duration: timedelta | None = None, action_type: str | None = None, *, data: dict | None = None)
Bases:
object
A skip segment
- category
The category of the segment
- Type:
Category
- duration
The duration of the segment, by default None
- Type:
Optional[timedelta], optional
- data
The raw data that was used to create the segment, can be None if the segment was created manually
- Type:
Optional[dict], optional
Note
While creating your own instance you should only pass the category, start and end time. The other attributes won’t do anything, those are only useful for segments gotten from the API.
- class sponsorblock.models.SegmentInfo(data)
Bases:
object
A class representing the segment info
- time_submitted
The time the segment was submitted
- Type:
Warning
You should not make a instance of this yourself, this should only be created by the libray
- class sponsorblock.models.TopUser(user_name: str, view_count: int, total_submissions: int, minutes_saved: float)
Bases:
object
A top user.
Warning
You should not make a instance of this yourself, this should only be created by the libray
- class sponsorblock.models.TotalStats(data)
Bases:
object
The total stats
- minutes_saved
The total amount of time saved
Warning
You should not make a instance of this yourself, this should only be created by the libray
sponsorblock.errors module
- exception sponsorblock.errors.BadRequest(message, response: Response)
Bases:
HTTPException
Raised when the status code is 400.
- exception sponsorblock.errors.DuplicateException(message, response: Response)
Bases:
HTTPException
Raised when the status code is 409.
- exception sponsorblock.errors.Forbidden(message, response: Response)
Bases:
HTTPException
Raised when the status code is 403.
- exception sponsorblock.errors.HTTPException(message, response: Response)
Bases:
Exception
Raised when the server returns an error code
- exception sponsorblock.errors.InvalidJSONException(message, response)
Bases:
Exception
Raised when the JSON gotten from the server is invalid
- exception sponsorblock.errors.NotFoundException(message, response: Response)
Bases:
HTTPException
Raised when the status code is 404.
- exception sponsorblock.errors.RateLimitException(message, response: Response)
Bases:
HTTPException
Raised when the status code is 429.
- exception sponsorblock.errors.ServerException(message, response: Response)
Bases:
HTTPException
Raised if the status code is bigger than 500.
- exception sponsorblock.errors.UnexpectedException(message, response: Response)
Bases:
HTTPException
Raised when an unknown error has occurred.
sponsorblock.utils module
- class sponsorblock.utils.SortType(value)
Bases:
Enum
0 for by minutes saved, 1 for by view count, 2 for by total submissions
See also
sponsorblock.client.Client.get_top_users
Should be used with the SortType
- MINUTES_SAVED = 0
- TOTAL_SUBMISSIONS = 2
- VIEW_COUNT = 1
- sponsorblock.utils.cache(**kwargs)
Custom cache implementation taken from https://stackoverflow.com/a/67555155/13123877.
- Parameters:
ttl (timedelta, optional) – The time to live for the cache. Defaults to max time supported by the platform.
max_entries (int) – The maximum number of entries to store in the cache..