API objects¶

Here is a list of all API objects.

class phub.core.Client(email: str = None, password: str = None, *, language: 'en' | 'cn' | 'de' | 'fr' | 'it' | 'pt' | 'pl' | 'rt' | 'nl' | 'cz' | 'jp' = 'en', delay: int | float = 0, login: bool = True, bypass_geo_blocking: bool = False, change_title_language: bool = True, use_webmaster_api: bool = True)¶

Represents a client capable of handling requests with Pornhub.

_clear_granted_token() → None¶: Removes the current granted token stored, if any.

property _granted_token : str¶

Get a granted token for the account. Used internally for making API calls.

Raises:¶: AssertionError – If the client is not logged in

call(func: str, method: str = 'GET', data: dict = None, headers: dict = None, timeout: float = 30, throw: bool = True, silent: bool = False) → Response¶

Used internally to send a request or an API call.

Parameters:¶

func : str¶: URL or PH function to fetch or call.
method : str¶: Request method (GET, POST, PUT, …).
data : dict¶: Optional data to send to the server.
headers : dict¶: Additional request headers.
timeout : float¶: Request maximum response time.
throw : bool¶: Whether to raise an error when a request explicitly fails.
silent : bool¶: Whether to supress this call from logs.

Returns:¶

The fetched response.

Return type:¶

Response

Raises:¶

ConnectionError – If the request was blocked by Pornhub.
HTTPError – If the request failed, for any reason.

get(video: str | Video) → Video¶

Get a Pornhub video.

Parameters:¶

video : str | Video¶: Video URL or viewkey.

Returns:¶

The corresponding video object.

Return type:¶

Video

get_playlist(playlist: str | int | Playlist) → Playlist¶

Get a Pornhub playlist.

Parameters:¶

playlist : str | int | Playlist¶: The playlist url or id

Returns:¶

The corresponding playlist object.

Return type:¶

Playlist

Raises:¶

TypeError – If the playlist argument is invalid.

get_user(user: str | User) → User¶

Get a Pornhub user.

Parameters:¶

user : str | User¶: user URL or name.

Returns:¶

The corresponding user object.

Return type:¶

User

login(force: bool = False, throw: bool = True) → bool¶

Attempt to log in.

Parameters:¶

force : bool¶: Whether to force the login (used to reconnect).
throw : bool¶: Whether to raise an error if this fails.

Returns:¶

Whether the login was successful.

Return type:¶

bool

Raises:¶

ClientAlreadyLogged – If force was False and client was already logged.
LoginFailed – If the login failed, for a reason passed in the error body.

reset() → None¶: Reset the client requests session. This is useful if you are keeping the client running for a long time and can help with Pornhub rate limit.

Performs searching on Pornhub.

Parameters:¶

query : str¶: The query to search.
production : str¶: Production type.
category : str¶: A category the video is in.
exclude_category : str | list¶: One or more categories to exclude.
hd : bool¶: Whether to search only HD videos.
sort : str¶: Sorting type.
period : str¶: When using sort, specify the search period.

Returns:¶

Initialised query.

Return type:¶

Query

Raises:¶

AssertioneError – If the query is empty.
AssertioneError – If one or more filters don’t match their literals.

Perform searching on Pornhub using the HubTraffic API. It is condidered to be much faster but has less filters.

Parameters:¶

query : str¶: The query to search.
category : str¶: A category the video is in.
sort : str¶: Sorting type.
period : str¶: When using sort, specify the search period.

Returns:¶

Initialised query response.

Return type:¶

Query

Raises:¶

AssertionError – If one or more filters don’t match their literals.

Search for users in the community.

Parameters:¶

username : str¶: Filters users with a name query.
country : str¶: Filter users with a country.
city : str¶: Filters users with a city.
min_age : int¶: Filters users with a minimal age.
max_age : int¶: Filters users with a maximal age.
gender : gender¶: Filters users with a gender.
orientation : orientation¶: Filters users with an orientation.
offers : offers¶: Filters users with what content they do on their channel.
relation : relation¶: Filters users with their relation.
sort : sort_user¶: Response sort type.
is_online : bool¶: Get only online or offline users.
is_model : bool¶: Get only model users.
is_staff : bool¶: Get only Pornhub staff members.
has_avatar : bool¶: Get only users with a custom avatar.
has_videos : bool¶: Get only users that have posted videos.
has_photos : bool¶: Get only users that have posted photos.
has_playlists : bool¶: Get only users that have posted playlists.

Returns:¶

Initialised query.

Return type:¶

UserQuery

class phub.objects.Account(client: Client)¶

Represents a connected Ponhub account, capable of accessing account-only features. If the login fails, there will be None.

connect(data: dict) → None¶

Update account data once login was successful.

Parameters:¶

data : dict¶: Data fetched from the login request.

dictify(keys: 'all' | list[str] = 'all', recursive: bool = False) → dict¶

Convert the object to a dictionary.

Parameters:¶

keys : str¶: The data keys to include.
recursive : bool¶: Whether to allow other PHUB objects to dictify.

Returns:¶

Dict version of the object.

Return type:¶

dict

property feed : Feed¶: The account feed.

fix_recommendations() → None¶: Allow recommandations cookies.

property liked : queries.VideoQuery¶: Videos liked by the account.

property recommended : queries.VideoQuery¶: Videos recommended to the account.

refresh(refresh_login: bool = False) → None¶

Delete the object’s cache to allow items refreshing.

Parameters:¶

refresh_login : bool¶: Whether to also attempt to re-log in.

property subscriptions : Iterator[User]¶: Get the account subscriptions.

property watched : queries.VideoQuery¶: Account video history.

class phub.objects.Tag(name: str, count: int = None)¶

Video Tag representation.

dictify(keys: 'all' | list[str] = 'all', recursive: bool = False) → dict¶

Convert the object to a dictionary.

Parameters:¶

keys : str¶: The data keys to include.
recursive : bool¶: Whether to allow other PHUB objects to dictify.

Returns:¶

A dict version of the object.

Return type:¶

dict

class phub.objects.Like(up: int, down: int, ratings: float)¶

Represents video likes and their ratings.

dictify(keys: 'all' | list[str] = 'all', recursive: bool = False) → dict¶

Convert the object to a dictionary.

Parameters:¶

keys : str¶: The data keys to include.
recursive : bool¶: Whether to allow other PHUB objects to dictify.

Returns:¶

A dict version of the object.

Return type:¶

dict

class phub.objects.FeedItem(client: Client = None, raw: str = None, type: str = None)¶

Represent an element of the user feed.

property _soup : Soup¶: Item soup.

dictify(keys: 'all' | list[str] = 'all', recursive: bool = False) → dict¶

Convert the object to a dictionary.

Parameters:¶

keys : str¶: The data keys to include.
recursive : bool¶: Whether to allow other PHUB objects to dictify.

Returns:¶

A dict version of the object.

Return type:¶

dict

property header : str¶: Item header (language dependent).

property html : Soup¶: Item HTML content.

property item_type : str¶: Item type.

property user : User¶: Item target.

class phub.objects.Feed(client: Client)¶

Represents the account feed.

property feed : queries.FeedQuery¶: A feed query with no filters.

filter(section: literals.section = None, user: User | str = None) → queries.FeedQuery¶

Creates a Feed Query with specific filters.

Parameters:¶

section : str¶: Filter parameters.
user : User | str¶: User to filter feed with.

sample(max: int = 0, filter: Callable[[FeedItem], bool] = None) → Iterator[FeedItem]¶

Wraps sampling the global feed.

Parameters:¶

max : int¶: Maximum amount of items to fetch.
filter : Callable¶: A filter function that decides whether to keep each FeedItems.

Returns:¶

Response iterator containing FeedItems.

Return type:¶

Iterator

class phub.objects.Image(client: Client, url: str, servers: list[dict] = [], name: str = 'image')¶

Represents an image hosted on Pornhub. (user avatar, video thumbnail, etc.)

dictify(keys: 'all' | list[str] = 'all', recursive: bool = False) → dict¶

Convert the object to a dictionary.

Parameters:¶

keys : str¶: The data keys to include.
recursive : bool¶: Whether to allow other PHUB objects to dictify.

Returns:¶

A dict version of the object.

Return type:¶

dict

download(path: PathLike = '.') → str¶

Download the image in a certain quality.

Parameters:¶

path : str¶: The download path.

Returns:¶

The image path if modified.

Return type:¶

str

TODO - Handle multiple qualities/sizes

class phub.objects.Query(client: Client, func: str, args: dict[str] = {}, container_hint: consts.WrappedRegex | collections.abc.Callable = None, query_repr: str = None)¶

A Base query.

__iter__() → Iterator[Video | FeedItem | User]¶: Iterate through the query items.

_get_page(index: int) → list¶

Get split unparsed page items.

Parameters:¶

index : int¶: The page index:

Returns:¶

a semi-parsed representation of the page.

Return type:¶

list

_get_raw_page(index: int) → str¶

Get the raw page.

Parameters:¶

index : int¶: The page index.

Returns:¶

The raw page content.

Return type:¶

str

_iter_page(page: list[str]) → Iterator[Video | FeedItem | User]¶: Wraps and iterate a page items.

_parse_item(raw: Any) → Video | FeedItem | User¶

Get a single query item.

Parameters:¶

raw : Any¶: The unparsed item.

Returns:¶

The item object representation.

Return type:¶

QueryItem

_parse_page(raw: str) → list[Any]¶

Get a query page.

Parameters:¶

raw : str¶: The raw page container.

Returns:¶

A semi-parsed list representation.

Return type:¶

list

property pages : Pages¶: Iterate through the query pages.

Get a sample of the query.

Parameters:¶

max : int¶: Maximum amount of items to fetch.
filter : Callable¶: A filter function that decides whether to keep each QueryItems.
watched : bool¶: Whether videos should have been watched by the account or not.
free_premium : bool¶: Whether videos should be free premium or not.

Returns:¶

Response iterator containing QueryItems.

Return type:¶

Iterator

class phub.objects.User(client: Client, name: str, url: str, type: str = None)¶

Represents a Pornhub user.

property _page : str¶: The user page.

property _supports_queries : _QuerySupportIndex¶: Checks query support.

property avatar : Image¶: The user avatar.

property bio : str | None¶: The user bio.

dictify(keys: 'all' | list[str] = 'all', recursive: bool = False) → dict¶

Convert the object to a dictionary.

Parameters:¶

keys : str¶: The data keys to include.
recursive : bool¶: Whether to allow other PHUB objects to dictify.

Returns:¶

A dict version of the object.

Return type:¶

dict

classmethod from_video(video: Video) → User¶

Find the author of a video.

Parameters:¶

video : Video¶: A video object.

classmethod get(client: Client, user: str) → User¶

Fetch a user knowing its name or URL. Note - Using only a username makes the fetch between 1 and 3 times slower, you might prefer to use a direct URL.

Parameters:¶

client : Client¶: The parent client.
user : str¶: Username or URL.

property info : dict[str, str]¶

The user detailed infos.

[Experimental]

Warning: keys depend on the language.

refresh() → None¶: Refresh this instance cache.

property uploads : queries.VideoQuery¶: Attempt to get the list of videos uploaded by this user.

property videos : queries.VideoQuery¶: Get the list of videos published by this user.

class phub.objects.Video(client: Client, url: str, change_title_language: bool = False)¶

Represents a Pornhub video.

property _as_query : dict[str, str]¶

Simulate a query to gain access to more data. If the video object is yielded by a query, this property will be overriden by the query data.

Warning - This will make a lot of requests and can fake: some properties (like watched).

_assert_internal_success(res: dict) → None¶

Assert an internal response has succeeded.

Parameters:¶

res : dict¶: The rerquest json response.

property author : User¶: The video’s author.

property categories : list['asian' | 'orgy' | 'amateur' | 'big-ass' | 'babe' | 'bbw' | 'big-dick' | 'big-tits' | 'blonde' | 'bondage' | 'brunette' | 'celebrity' | 'blowjob' | 'bukkake' | 'creampie' | 'cumshot' | 'ebony' | 'fetish' | 'fisting' | 'handjob' | 'hardcore' | 'masturbation' | 'toys' | 'public' | 'interracial' | 'latina' | 'lesbian' | 'mature' | 'milf' | 'pornstar' | 'reality' | 'funny' | 'striptease' | 'anal' | 'hentai' | 'teen' | 'hd-porn' | 'japanese-gay' | 'bareback-gay' | 'pov' | 'red-head' | 'vintage' | 'black-gay' | 'massage-gay' | 'euro-gay' | 'daddy-gay' | 'asian-gay' | 'twink' | 'latino-gay' | 'muscle-gay' | 'fetish-gay' | 'party' | 'solo-male-gay' | 'euro' | 'blowjob-gay' | 'compilation' | 'big-dick-gay' | 'small-tits' | 'pornstar-gay' | 'webcam' | 'group-gay' | 'gay' | 'interracial-gay' | 'threesome' | 'bear-gay' | 'rough-sex' | 'college' | 'squirt' | 'hunks-gay' | 'creampie-gay' | 'double-penetration' | 'popular-with-women' | 'bisexual-male' | 'vintage-gay' | 'massage' | 'gangbang' | 'role-play' | 'straight-guys-gay' | 'transgender' | 'public-gay' | 'reality-gay' | 'cartoon' | 'school' | 'babysitter' | 'casting' | 'smoking' | 'solo-male' | 'feet' | 'french' | 'german' | 'british' | 'italian' | 'arab' | 'russian' | 'czech' | 'indian' | 'brazilian' | 'korean' | 'vr' | '60fps' | 'vr-gay' | 'hd-porn-gay' | 'interactive' | 'japanese' | 'exclusive' | 'music' | 'pussy-licking' | 'ffm' | 'fmm' | 'verified-amateurs' | 'verified-models' | 'behind-the-scenes' | 'old-young' | 'parody' | 'pissing' | 'sfw' | 'described-video' | 'cosplay' | 'cuckold' | 'amateur-gay' | 'handjob-gay' | 'uncut-gay' | 'rough-sex-gay' | 'jock-gay' | 'mature-gay' | 'webcam-gay' | 'cumshot-gay' | 'casting-gay' | 'pov-gay' | 'compilation-gay' | 'chubby-gay' | 'military-gay' | 'feet-gay' | 'cartoon-gay' | 'step-fantasy' | 'verified-couples' | 'solo-female' | 'female-orgasm' | 'muscular-men' | 'romantic' | 'scissoring' | 'strap-on' | 'tattooed-men-gay' | 'tattooed-women' | 'trans-with-girl' | 'trans-with-guy' | 'fingering' | 'trans-male' | '360' | '180' | '2d' | '3d' | 'voyeur' | 'uncensored' | 'verified-amateurs-gay' | 'closed-captions' | 'closed-captions-gay']¶: The categories of the video.

property date : datetime¶: The video publish date.

dictify(keys: 'all' | list[str] = 'all', recursive: bool = False) → dict¶

Convert the object to a dictionary.

Parameters:¶

keys : str¶: The data keys to include.
recursive : bool¶: Whether to allow other PHUB objects to dictify.

Returns:¶

A dict version of the object.

Return type:¶

dict

download(path: Union[str, os.PathLike], quality: Quality | str = 'best', *, downloader: Union[Callable, str] = <function default>, display: Callable[[int, int], None] = <function progress.<locals>.wrapper>, convert: bool = False) → str¶

Download the video to a file.

Parameters:¶

path : PathLike: The download path.
quality : Quality | str | int: The video quality.
downloader : Callable: The download backend.
display : Callable: The progress display.
convert : bool: Whether to convert the video to a valid .mp4 file using FFmpeg

Returns:¶

The downloader video path.

Return type:¶

str

property duration : timedelta¶: The video length.

property embed : str¶: The video iframe embed.

favorite(toggle: bool = True) → None¶

Set video as favorite or not.

Parameters:¶

toggle : bool¶: The toggle value.

fetch(key: str) → Any¶

Lazily fetch some data.

key format:: data@<dkey> => Get key from API page@<pkey> => Scrape key from page <dkey>|<pkey> => Choose considering cache

Parameters:¶

key : str¶: The key to fetch.

Returns:¶

The fetched or cached object.

Return type:¶

Any

get_M3U_URL(quality: Quality) → str¶

The URL of the master M3U file.

Parameters:¶

quality : Quality¶: The video quality.

Returns:¶

The M3U url.

Return type:¶

str

get_direct_url(quality: Quality) → str¶

Get the direct video URL given a specific quality.

Parameters:¶

quality : Quality¶: The video quality.

Returns:¶

The direct url.

Return type:¶

str

get_segments(quality: Quality) → Iterator[str]¶

Get the video segment URLs.

Parameters:¶

quality : Quality¶: The video quality.

Returns:¶

A segment URL iterator.

Return type:¶

Iterator

property hotspots : Iterator[int]¶: List of hotspots (in seconds) of the video.

property id : str¶: The internal video id.

property image : Image¶: The video thumbnail.

property is_HD : bool¶: Whether the video is in High Definition.

property is_VR : bool¶: Whether the video is in Virtual Reality.

property is_favorite : bool¶: Whether the video has been set as favorite by the client.

property is_free_premium : bool¶: Whether the video is part of free premium.

property is_vertical : bool¶: Whether the video is in vertical mode.

like(toggle: bool = True) → None¶

Set the video like value.

Parameters:¶

toggle : bool¶: The toggle value.

property liked : bool¶: Whether the video was liked by the account.

property likes : Like¶: Positive and negative reviews of the video.

property orientation : str¶: Video sexual orientation (e.g. straight).

property pornstars : list[User]¶: The pornstars present in the video.

property preview : Image¶: The preview ‘mediabook’ of the video. This is the lazy video displayed when hovering the video.

refresh(page: bool = True, data: bool = True) → None¶

Refresh video data.

Parameters:¶

page : bool¶: Whether to refresh the video page.
data : bool¶: Whether to refresh the video data.

property tags : list[Tag]¶: The video tags.

property title : str¶: The video title.

property views : int¶: How many people watched the video.

watch_later(toggle: bool = True) → None¶

Add or remove the video to the watch later playlist.

Parameters:¶

toggle : bool¶: The toggle value.

property watched : bool¶: Whether the video was viewed previously by the account.