Basic Usage¶

The simplest way to use this library is to simply pass a ModDB url to the parse function and let the magic happen:

importmoddbmod=moddb.parse_page("http://www.moddb.com/mods/edain-mod")print(mod.name)#Edain Mod

Advanced Usage¶

Of course, relying on the library isn’t always what we want, you’d be forced to use requests plus nothing’sperfect and errors might occur. In some cases, you might benefit from having a finer control upon the process,in which case, it is good to know that you can easily do this with few additional imports. Given you suddenlywant to use something like aiohttp to get the pages you could easily do something like this:

importmoddbimportaiohttpasyncdefget_page():asyncwithaiohttp.ClientSession()assession:asyncwithsession.get("http://www.moddb.com/mods/edain-mod")asresponse:soup=moddb.soup(awaitr.text())returnmoddb.Mod(soup)

This would return a mod object, with you only having to import the bit you want to change from the original library,in that case aiohttp. This is not fully supported for all things however, for example trying to get the articles forthat mod page you would be forced to completly parse the result page on your own or be forced to use requests.

See more snippets there:Examples and Snippets.

Searching¶

The package supports searching moddb with an optional query, filters and to sort those results. Filters differ widelydepending on which model is being searched therefore a good read of the documentation of the search function isrecommended. The only required parameter of the search function is a valid moddb.SearchCategory as the first argument.All other arguments are optional. thesearch function returns a moddb.Search object. The most basic example is:

frommoddbimportsearch,SearchCategorysearch=search(SearchCategory.mods)#returns a search objects with the results being a#list of mod thumbnails

You can also search titles of the models with a string query:

frommoddbimportsearch,SearchCategorysearch=search(SearchCategory.mods,query="age of the ring")#returns a search objects with the results being a list of#mod thumbnails which moddb has matched with the words age of the ring

Many additional filters are available and listed in the documentation, each filter kwarg will expected a specific enum.The only exception is the game filters which expects either a game object or a moddb.Object with an id attribute. For exampleif we want to search for a released fantasy mod:

frommoddbimportsearch,SearchCategory,Theme,Statussearch=search(SearchCategory.mods,theme=Theme.fantasy,released=Status.released)#returns a search objects with the results being a list of mod#thumbnails of mods which have been released and are labelled as#fantasy themed.

And finally, you can sort the results with thesort kwargs which expects a tuple with the first element being a sortcategory which is valid for the model you’re sorting for and the second being whether you want the sort to be ascending or descending:

frommoddbimportsearch,SearchCategory,Sortsearch=search(SearchCategory.mods,sort=("rating","asc"))#returns a search objects with the results being a list of mod#thumbnails sorted by rating with highest rating first

Logging¶

This package makes use of the powerful Python logging module. Whenever the scrapper is unable to find a specific fieldfor a model, either because it does not exist or because the scrapper cannot see it with its current permissions, then itwill log it as an info. All logs will be sent to themoddb logger, to have access to the stream of logs you can do things like:

importlogginglogging.basicConfig(level=logging.INFO)

or:

importlogginglogger=logging.getLogger('moddb')logger.setLevel(logging.INFO)handler=logging.FileHandler(filename='moddb.log',encoding='utf-8',mode='w')handler.setFormatter(logging.Formatter('%(asctime)s:%(levelname)s:%(name)s:%(message)s'))logger.addHandler(handler)

Account¶

This package allows users to login into ModDB in order to have access to additional information which Guest users(the account the package uses by default) cannot see such as Guest comments waiting for approval or privategroups/members. In order to login simply use the built-in library method:

importmoddbmoddb.login("valid_username","valid_password")

The session the package uses will be updated and all further requests will now be made logged in as that user.The function will raise a ValueError if the login fails. You can also log out of the account to disable accessto those restricted elements with thelogout function:

importmoddbmoddb.logout()

Installing¶

Install with pip:

pipinstallmoddb