Mod

Documentation on the object representing a mod.io Mod

Module storing representation of the mod objects

class modio.mod.Mod(**attrs)

Represent a modio mod object.

Filter-Only Attributes

These attributes can only be used at endpoints which return instances of this class and takes filter arguments. They are not attached to the object itself and trying to access them will cause an AttributeError

sort_downloads : str

Sort argument, provide to sort function to sort by most/least downloaded

sort_popular : str

Sort argument, provide to sort function to sort by most/least popular

sort_rating : str

Sort argument, provide to sort function to sort by weighed rating

sort_subscribers : str

Sort argument, provide to sort function to sort by most/least subscribers

id

ID of the mod. Filter attribute.

Type:int

status

Status of the mod. Filter attribute.

Type:Status

visible

Visibility of the mod. Filter attribute.

Type:Visibility

game_id

ID of the game the mod is for. Filter attribute.

Type:int

submitter

Instance of the modio User that submitted the mod. Filter attribute.

Type:User

date

UNIX timestamp of the date the mod was registered. Filter attribute.

Type:datetime.datetime

updated

UNIX timestamp of the date the mod was last updated. Filter attribute.

Type:datetime.datetime

live

UNIX timestamp of the date the mod went live. Filter attribute.

Type:datetime.datetime

logo

The mod logo

Type:Image

homepage

Link to the homepage of the mod, can be None. Filter attribute.

Type:str

name

Name of the mod. Filter attribute.

Type:str

name_id

sub_domain mod for the game (https://game_name.mod.io/name_id). Filter attribute.

Type:str

summary

Summary of the mod. Filter attribute.

Type:str

description

Detailed description of the mod, supports HTML. Filter attribute.

Type:str

metadata

Metadata stored by developers which may include properties on how information required. Can be None. Filter attribute.

Type:str

maturity

Maturity option of the mod. Filter attribute.

Type:Maturity

profile

URL of the mod’s modio profile

Type:str

file

Latest released instance. Can be None. Filter attribute.

Type:ModFile

media

Contains mod media data (links and images)

Type:ModMedia

stats

Summary of all stats for this mod

Type:ModStats

tags

Tags for this mod. Filter attribute.

Type:dict

kvp

Contains key-value metadata. Filter attribute.

Type:dict

plaintext

description field converted into plaintext.

Type:str

mod_key = 'id'

kvp

get_file(file_id: int) → modio.entities.ModFile

Get the Mod File with the following ID.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:file_id (int) – ID of the mod file you wish to retrieve Raises:NotFound – A mod with that ID has not been found Returns:The found modfile Return type:ModFile

get_files(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.ModFile][modio.entities.ModFile]

Get all mod files for this mod. Returns a named tuple with parameters results and pagination. This method takes filtering arguments

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:filter (Optional[Filter]) – A instance of Filter to be used for filtering, paginating and sorting results Returns:The results and pagination tuple from this request Return type:Returned[List[ModFile], Pagination]

get_events(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.Event][modio.entities.Event]

Get all events for that mod sorted by latest. Returns, a named tuple with parameters results and pagination. This method takes filtering arguments

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:filter (Optional[Filter]) – A instance of Filter to be used for filtering, paginating and sorting results Returns:The results and pagination tuple from this request Return type:Returned[List[Event], Pagination]

get_tags(*, filters: modio.objects.Filter = None) → modio.objects.Returned[dict][dict]

Gets all the tags for this mod. Updates the instance’s tag attribute. Returns a named tuple with parameters results and pagination. This method takes filtering arguments

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:filter (Optional[Filter]) – A instance of Filter to be used for filtering, paginating and sorting results Returns:The results and pagination tuple from this request Return type:Returned[List[Tag], Pagination]

get_metadata() → modio.objects.Returned[dict][dict]

Returns a dict of metakey-metavalue pairs. This will also update the mod’s kvp attribute.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Returns:The results and pagination tuple from this request Return type:Returned[List[MetaData], Pagination]

get_dependencies(*, filters: modio.objects.Filter = None) → modio.objects.Returned[dict][dict]

Returns a dict of dependency_id-date_added pairs. Returns a named tuple with parameters results and pagination. This method takes filtering arguments

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:filter (Optional[Filter]) – A instance of Filter to be used for filtering, paginating and sorting results Returns:The results and pagination tuple from this request Return type:Returned[List[Dependency], Pagination]

get_team(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.TeamMember][modio.entities.TeamMember]

Returns a list of TeamMember object representing the Team in charge of the mod. This method takes filtering arguments

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:filter (Optional[Filter]) – A instance of Filter to be used for filtering, paginating and sorting results Returns:The results and pagination tuple from this request Return type:Returned[List[TeamMember], Pagination]

get_comments(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.Comment][modio.entities.Comment]

Returns a list of all the top level comments for this mod wih comments replying to top level comments stored in the children attribute. This can be flattened using the utils.flatten function. This method takes filtering arguments

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:filter (Optional[Filter]) – A instance of Filter to be used for filtering, paginating and sorting results Returns:The results and pagination tuple from this request Return type:Returned[List[Comment], Pagination]

add_comment(content: str, *, reply: int = None) → modio.entities.Comment

Add a comment to the mod page. You can specify a comment to reply too.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:

• content (str) – The content of the comment
• reply (Optional[Comment]) – The comment to reply to

Returns:

The comment created

Return type:

Comment

get_stats() → modio.entities.ModStats

Returns a ModStats object, representing a series of stats for the mod.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Returns:The stats summary object for the mod. Return type:Stats

edit(**fields) → modio.mod.Mod

Used to edit the mod details. Sucessful editing will return the updated mod.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:

• status (Status) – For game admins only.
• visible (Visibility) – Modify the game visibility
• name (str) – Name of the mod, cannot exceed 80 characters
• name_id (str) – Subdomain for the mod, cannot exceed 80 characters
• summary (str) – Summary of the mod, cannot exceed 250 characters
• description (str) – Detailed description for your mod, which can include details such as ‘About’, ‘Features’, ‘Install Instructions’, ‘FAQ’, etc. HTML supported and encouraged.
• homepage (str) – URL to the official homepage for this mod.
• stock (str) – Maximium number of subscribers for this mod. A value of 0 disables this limit.
• maturity (Maturity) – Maturity option of the mod.
• metadata (str) – Metadata stored by the mod developer which may include properties as to how the item works, or other information you need to display.

Returns:

The updated version of the mod

Return type:

Mod

delete()

Delete a mod and set its status to deleted.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

add_file(file: modio.objects.NewModFile) → modio.entities.ModFile

Adds a new file to the mod, to do so first construct an instance of NewModFile and then pass it to the function.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:file (NewModFile) – The mod file to upload Raises:modioException – file argument must be type NewModFile Returns:The modfile after being processed by the mod.io API Return type:ModFile

add_media(*, logo: Optional[str] = None, images: Union[str, List[str], None] = (), youtube: List[str] = (), sketchfab: List[str] = ())

Upload new media to the mod.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:

• logo (Optional[str]) – Path to the logo file. If on windows, must be escaped. Image file which will represent your mods logo. Must be gif, jpg or png format and cannot exceed 8MB in filesize. Dimensions must be at least 640x360 and we recommended you supply a high resolution image with a 16 / 9 ratio. mod.io will use this logo to create three thumbnails with the dimensions of 320x180, 640x360 and 1280x720.
• images (Optional[Union[str, list]]) – Can be either the path to a file called .zip file containing all the images or a list of paths to multiple image files. If on windows, must be escaped. Only valid gif, jpg and png images in the zip file will be processed.
• youtube (Optional[List[str]]) – List of youtube links to be added to the gallery
• sketchfab (Optional[List[str]]) – List of sketchfab links to the be added to the gallery.

Returns:

A message confirming the submission of the media

Return type:

Message

delete_media(*, images: Optional[List[str]] = (), youtube: Optional[List[str]] = (), sketchfab: Optional[List[str]] = ())

Delete media from the mod page.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:

• images (Optional[List[str]]) – Optional. List of image filenames that you want to delete
• youtube (Optional[List[str]]) – Optional. List of youtube links that you want to delete
• sketchfab (Optional[List[str]]) – Optional. List sketchfab links that you want to delete

subscribe() → modio.mod.Mod

Subscribe to the mod. Returns None if user is already subscribed.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Returns:The mod that was just subscribed to, if the user was already subscribed it will return None Return type:Mod

unsubscribe()

Unsubscribe from a mod. Returns None if the user is not subscribed.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

add_tags(*tags)

Add tags to a mod, tags are case insensitive and duplicates will be removed. Tags which are not in the game’s tag_options will not be added.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:tags (List[str]) – list of tags to be added.

delete_tags(*tags)

Delete tags from the mod, tags are case insensitive and duplicates will be removed. Providing no arguments will remove every tag from the mod.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:tags (List[str]) – List of tags to remove, if no list is provided, will remove every tag from the mod.

add_metadata(**metadata)

Add metadate key-value pairs to the mod. To submit new meta data, pass meta data keys as keyword arguments and meta data value as a list of values. E.g pistol_dmg = [800, 400]. Keys support alphanumeric, ‘-’ and ‘_’. Total lengh of key and values cannot exceed 255 characters. To add meta-keys which contain a dash in their name they must be passed as an upacked dictionnary.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Example

mod.add_metadata(difficulty=[“hard”, “medium”, “easy”])

This will add the values “hard”, “medium” and “easy” to the meta key “difficulty”

mod.add_metadata(**{“test-var”: [“test1”, “test2”, “test3”]})

This will add the values “test1”, “test2” and “test3” to meta key “test-var”

Returns:message on the status of the successful added meta data Return type:Message

add_negative_rating()

Changes the mod rating to negative, the author of the rating will be the authenticated user. If the mod has already been negatively rated by the user it will return False. If the negative rating is successful it will return True.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

add_positive_rating()

Changes the mod rating to positive, the author of the rating will be the authenticated user. If the mod has already been positevely rated by the user it will return False. If the positive rating is successful it will return True.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

async_add_comment(content: str, *, reply: int = None) → modio.entities.Comment

async_add_dependencies(dependencies: List[Union[int, Mod]])

async_add_file(file: modio.objects.NewModFile) → modio.entities.ModFile

async_add_media(*, logo: Optional[str] = None, images: Union[str, List[str], None] = (), youtube: List[str] = (), sketchfab: List[str] = ())

async_add_metadata(**metadata)

async_add_negative_rating()

async_add_positive_rating()

async_add_tags(*tags)

async_add_team_member(email: str, level: modio.enums.Level, *, position: Optional[str] = None)

async_delete()

async_delete_dependencies(dependencies: List[Union[int, Mod]])

async_delete_media(*, images: Optional[List[str]] = (), youtube: Optional[List[str]] = (), sketchfab: Optional[List[str]] = ())

async_delete_metadata(**metadata)

async_delete_tags(*tags)

async_edit(**fields) → modio.mod.Mod

async_get_comments(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.Comment][modio.entities.Comment]

async_get_dependencies(*, filters: modio.objects.Filter = None) → modio.objects.Returned[dict][dict]

async_get_events(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.Event][modio.entities.Event]

async_get_file(file_id: int) → modio.entities.ModFile

async_get_files(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.ModFile][modio.entities.ModFile]

async_get_metadata() → modio.objects.Returned[dict][dict]

async_get_owner() → modio.entities.User

async_get_stats() → modio.entities.ModStats

async_get_tags(*, filters: modio.objects.Filter = None) → modio.objects.Returned[dict][dict]

async_get_team(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.TeamMember][modio.entities.TeamMember]

async_report(name: str, summary: str, report_type: modio.enums.Report = <Report.generic: 0>)

async_subscribe() → modio.mod.Mod

async_unsubscribe()

delete_metadata(**metadata)

Deletes metadata from a mod. To do so pass the meta-key as a keyword argument and the meta-values you wish to delete as a list. You can pass an empty list in which case all meta-values for the meta-key will be deleted. To delete meta-keys which contain a dash in their name they must be passed as an upacked dictionnary.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Example

mod.delete_metadata(difficulty=[“easy”])

This will remove the value “easy” from the meta key “difficulty”

mod.delete_metadata(difficulty=[])

This will remove the meta key “difficulty”

mod.delete_metadata(**{“test-var”: [“test1”]})

This will remove the value “test1” from the meta key “test-var”

mod.delete_metadata(**{“test-var”:[]})

This will remove the meta key “test-var”

get_owner() → modio.entities.User

Get the original submitter of the resource.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Returns:The original submitter Return type:User

report(name: str, summary: str, report_type: modio.enums.Report = <Report.generic: 0>)

Report a this game, make sure to read mod.io’s ToU to understand what is and isnt allowed.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:

• name (str) – Name of the report
• summary (str) – Detailed description of your report. Make sure you include all relevant information and links to help moderators investigate and respond appropiately.
• report_type (Report) – Report type

Returns:

The returned message on the success of the query.

Return type:

Message

add_dependencies(dependencies: List[Union[int, Mod]])

Add mod dependencies required by the corresponding mod. A dependency is a mod that should be installed for this mod to run.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:dependencies (List[Union[int, Mod]]) – List of mod ids to submit as dependencies.

delete_dependencies(dependencies: List[Union[int, Mod]])

Delete mod dependecies required by this mod. You must supply at least one dependency.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:dependencies (List[Union[int, Mod]]) – List of dependencies to remove

add_team_member(email: str, level: modio.enums.Level, *, position: Optional[str] = None)

Add a user to the mod team. Will fire a MOD_TEAM_CHANGED event.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:

• email (str) – mod.io email of the user you wish to add
• level (Level) – Level of permissions you grant the user
• position (Optional[str]) – Title of the user position