Authenticating

The client object allows you to manipulate a user object that is logged in. Each client object represents a logged in user on which you can do a set of operations and requests. This gives you more interactivity with the website beyond simply getting random page. You can track, untrack pages and get the updates to those pages.

The client also supports __enter__ and __exit__ as means to temporarily replace the module’s session with the client’s. See snippets for an example.

Client

class moddb.client.Client(username, password)

Login the user to moddb through the library, this allows user to see guest comments and see private groups they are part of. In addition, this can be used for a lot of the operation

Parameters:

• username (str) – The username of the user

• password (str) – The password associated to that username

Raises:

ValueError – The password or username was incorrect

member

The member objects this client instance represents

Type:

Member

add_comment(page, text, *, comment=None)

Add a comment to a page.

Parameters:

• page (Any) – Must be a moddb.page, the page you wish to add the comment to.

• test (str) – The content of the comment you wish to post

• comment (Optional[Comment]) – If you wish to reply to another comment you must provide the comment object for it there.

Returns:

The page’s updated object containing the new comment and any other new data that has been posted since then

Return type:

Any

add_member_to_thread(thread, member)

Add a member to a conversation

Parameters:

• thread (Union[Thread, ThreadThumbnail]) – The thread to add add a member to

• member (Member) – The member to add

Returns:

Whether adding the member was succesful. This will not update the thread.

Return type:

bool

add_review(page, rating, *, text=None, has_spoilers=False)

Rate and review a page. If you rating is below 3 or above 8 you will be asked to also provide a review or else the request will not be made. This is also used to edit existing reviews.

Parameters:

• page (Union[Mod, Game, Engine, Hardware, Software, Platform]) – The page you wish to review

• rating (int) – The rating from 1 to 10

• text (str) – The text review you are giving of this page

• has_spoilers (bool) – Whether or not this review contains spoilers.

Raises:

ModdbException – An error occured trying to review the page.

Returns:

True of the review was successfuly submitted.

Return type:

bool

clear_updates(category)

Clear all updates for a specific category of watched. This method will conduct two requests because the clear update request requires a hash generated by moddb.

Parameters:

category (WatchType) – The category of watched to clear

Returns:

Whether or not the clear was successful

Return type:

bool

delete_comment(comment)

This will delete the supplied comment provided you have the correct permissions. This is an expensive request because if how moddb works. It needs to make two requests in order to get the correct hash to delete the comment. In addition, it may fail if the comment has changed location (page number) from what the object says. It is recommended to use a newly created comment object that is less than 30 minutes old.

Parameters:

comment (Comment) – The comment to delete

Raises:

ModdbException – An error occured while trying to delete the comment

Returns:

True if the comment was successfully deleted

Return type:

bool

delete_review(review)

Delete your review on the given page. This function will do two requests in order to delete your review.

Parameters:

review (Review) – The review you wish to delete

Raises:

ModdbException – An error occured while trying to delete the review

Returns:

True if the review was successfully deleted

Return type:

bool

dislike_comment(comment)

Dislike a comment, if the comment has already been disliked nothing will happen.

Parameters:

comment (Comment) – The comment to dislike

Raises:

ModdbException – An error has occured while trying to dislike the comment

Returns:

True if comment has been successfully disliked.

Return type:

bool

downvote_tag(tag)

Downvote a tag

Parameters:

tag (Tag) – The tag to downvote

Returns:

Whether the downvote was successful

Return type:

bool

edit_comment(comment, new_text)

Edit the contents of a comment. You can only edit your comment 120 minutes after it has been posted

Parameters:

• comment (Comment) – The comment to edit

• new_text (str) – The new content of the comment

Raises:

ModdbException – An error has occured trying to edit the comment

Returns:

True if the comment was successfully edited

Return type:

bool

get_friend_requests()

Get the current friend requests the user has.

Returns:

List of requests (thumbnail like objects with extra methods)

Return type:

List[Request]

get_threads(query=None, read=None, replied=None, sent_items=False, sort=None)

Get all the messages this user has sent or received. This does not return threads you have left.

Parameters:

• query (Optional[str]) – Optional query to filter messages

• read (Optional[bool]) – True to filter only read message, false to filter unread, None to allow both

• replied (Optional[bool]) – True to filter messages where you are the last message, False for messages where another user is the last message, None for both.

• sent_items (bool) – Get only the threads you have started

• sort (Tuple[str, str]) – Optional sort tuple to order threads

Returns:

Thread typed thumbnails

Return type:

List[ThreadThumbnail]

get_updates()

Get the current updates the user has for models they are subscribed to.

Returns:

List of updates (thumbnail like objects with extra methods and an extra attribute)

Return type:

List[Update]

get_watched(category, page=1)

Get a list of thumbnails of watched items based on the type parameters. Eventually, you’ll also be able to paginate your mods.

Parameters:

• category (WatchType) – The type of watched thing you wanna get (mod, games, engines)

• page (int) – The page number you want to get

Returns:

List of watched things

Return type:

ResultList[Thumbnail]

leave_thread(thread)

Leave a thread, you will not get any more notifications on this thread.

Parameters:

thread (Union[Thread, ThreadThumbnail]) – The thread to leave

Returns:

Whether leaving the thread was successful

Return type:

bool

like_comment(comment)

Like a comment, if the comment has already been liked nothing will happen.

Parameters:

comment (Comment) – The comment to like

Raises:

ModdbException – An error has occured while trying to like the comment

Returns:

True if the comment has been successfully liked

Return type:

bool

mark_all_read()

Mark all threads as read.

Returns:

True if all threads have been marked as read

Return type:

bool

membership(page)

Join/leave a team

Parameters:

page (Union[Group, Team]) – The team/group you want to join. Will not work if you don’t have permissions

Raises:

ModdbException – An error has occured while trying to join/leave the group/team

Returns:

True if the group/team has been successfully joined, False if the group/team has been successfully left.

Return type:

bool

parse_thread(thread)

Parse a thread thumbnail into a full thread object.

Parameters:

thread (ThreadThumbnail) – The thumbnail to parse

Returns:

The parsed thread and its messages

Return type:

Thread

reply_to_thread(thread, text)

Add an additional message to an exiting thread

Parameters:

• thread (Union[Thread, ThreadThumbnail]) – The thread to add the message to

• text (str) – The text to send

Returns:

The updated thread containing the new message. It is recommended to use this object as it also contains a new hash for sending another message

Return type:

Thread

report(page)

Report a page. This can take any object that has an id and url attribute.

Parameters:

page (Any) – The page to report

Raises:

ModdbException – An error has occured while trying to report the page

Returns:

True if the page has been successfully reported

Return type:

bool

send_message(members, name, message)

Send a message and start a thread with one or more members

Parameters:

• member (List[Member]) – The members to send the message to and start the thread with

• name (str) – The subject of the message

• message (str) – The message to send

Returns:

The thread started from sending this message

Return type:

Thread

send_request(member)

Send a friend request to a user. You will not instantly become friends with them, they will have to accept the friend request you sent them first.

Parameters:

member (Member) – The member you wish to send a friend request to

Raises:

ModdbException – An error has occured trying to send a friend request to that user

Returns:

True if the user was succesfully sent a friend request

Return type:

bool

tracking(page)

Follow/unfollow this page.

Parameters:

page (Union[Mod, Game, Engine, Group, Member]) – The page you wish to watch/unwatch

Raises:

ModdbException – An error has occured while trying to follow/unfollow the page

Returns:

True if the page has been successfully followed, False if it has been successfully unfollowed

Return type:

bool

undelete_comment(comment)

This will undelete the supplied comment provided you have the correct permissions. This is an expensive request because of how moddb works. It needs to make three requests in order to get the correct hash to undelete the comment. In addition, it may fail if the comment has changed location (page number) from what the object says. It is recommended to use a newly created comment object that is less than 30 minutes old.

Parameters:

comment (Comment) – The comment to undelete

Raises:

ModdbException – An error occured while trying to undelete the comment

Returns:

True if the comment was successfully undeleted

Return type:

bool

unfriend(member)

Unfriend this member if you are friends with them.

Parameters:

member (Member) – The member you wish to unfriend

Raises:

ModdbException – An error has occured trying to unfriend this user

Returns:

True if the user was succesfully unfriended

Return type:

bool

upvote_tag(tag)

Upvote a tag

Parameters:

tag (Tag) – The tag to upvote

Returns:

Whether the upvote was successful

Return type:

bool

ThreadThumbnail

class moddb.client.ThreadThumbnail(**kwargs)

The thumbnail of a thread, these represent partial objects that must be parsed using a client to get the full thread.

name

The name of the thread

Type:

str

id

The id of the thread

Type:

int

url

The url for the thread

Type:

str

last_messager

A thumbnail representig the user that sent the last message

Type:

Thumbnail

timestamp

Datetime of the last message

Type:

datetime.datetime

content

Content of the last message. Useful for checking the last message without having to parse the thread.

Type:

str

Thread

class moddb.client.Thread(html)

A thread is a conversation between two or more members in which one or more messages can be sent.

Sorting

• id - when the message was sent, asc is oldest, desc is most recent

• name - order alphabetically, asc is a-z, desc is z-a

• hasread - order by whether or the message has been read, asc is unread first, desc is read first

• hasreplied - order by whether or not you have replied to the message, asc us unreplied first, desc is replied first

name

Name of the thread

Type:

str

id

Id of the thread

Type:

int

count

The number of messages in this thread

Type:

int

members

All the members participating in the thread. Note: The thumbnail of the member who fetched the message will always be first and will have their name attribute be ‘you’ instead of the username

Type:

List[Tumbnail]

message

The messages associated to this thread

Type:

List[Message]

Message

class moddb.client.Message(html)

A single message within a thread.

id

The id of the message

Type:

int

member

A member type thumbnail representing the member who sent the message

Type:

Thumbnail

timestamp

Message send date

Type:

datetime.datetime

text

The html text of the message

Type:

str

Update

class moddb.client.Update(**attrs)

An update object. Which is basically just a fancy thumbnail with a couple extra attributes and methods.

url

The url to the full model, mandatory attribute.

Type:

str

name

The name of the model

Type:

str

image

The optional thumbnail image of the model

Type:

str

summary

Optional bit of fluff

Type:

str

date

A date related to this timestamp if it exists. Can be None

Type:

datetime.datetime

type

The type of the resource, mandatory attribute

Type:

ThumbnailType

updates

A list of thumbnail objects of the things thave have been posted (new files, new images)

Type:

List[Thumbnail]

clear()

Clears all updates

Raises:

ModdbException – An error has occured while trying to clear the updates for this page

Returns:

True if the updates were successfully cleared

Return type:

bool

parse()

Uses the Thumbnail’s mandatory attributes to get the full html of the model and parse them with the appropriate object.

Returns:

The model that was parsed, can be any model from the list of the ThumbnailType enum.

Return type:

Any

unfollow()

Unfollows the page. This will also clear the updates

Raises:

ModdbException – An error has occured while trying to unfollow this page

Returns:

True if the page was successfully unfollowed

Return type:

bool

Request

class moddb.client.Request(**attrs)

A thumbnail with two extra methods used to clear and accept requests.

url

The url to the full model, mandatory attribute.

Type:

str

name

The name of the model

Type:

str

image

The optional thumbnail image of the model

Type:

str

summary

Optional bit of fluff

Type:

str

date

A date related to this timestamp if it exists. Can be None

Type:

datetime.datetime

type

The type of the resource, mandatory attribute

Type:

ThumbnailType

accept()

Accept the friend request.

Raises:

ModdbException – An error has occured while trying to accept the request

Returns:

True if the request was successfully accepted

Return type:

bool

decline()

Decline the friend request

Raises:

ModdbException – An error has occured while trying to decline the request

Returns:

True if the page was successfully declined

Return type:

bool

parse()

Uses the Thumbnail’s mandatory attributes to get the full html of the model and parse them with the appropriate object.

Returns:

The model that was parsed, can be any model from the list of the ThumbnailType enum.

Return type:

Any