API Reference¶

Below is the API reference for cursepy. Each file is broken up into a different section. You can find tutorials on how to use these components elsewhere in this documentation.

Wrappers¶

cursepy wrapper classes.

These classes are designed to work with specific games, and make getting information about them much easier. The class you probably want to work with is the CurseClient.

class cursepy.wrapper.BaseClient(load_default=True)¶

CurseClient - a class all clients must inherit!

We implement the handler management and callback features outlined in the HandlerCollection. We do some extra things here and there to make life much easier for the end user.

We define some entry points for calling handlers. These functions will be called by the users actually using these handlers. We define some arguments that should be defined, as well as what we expect the functions to return.

This class also provides some entry points into the loaded handlers. This provides a standardized way of interacting with handlers.

Other clients can add/change functionality where necessary.

addon(addon_id: int) → CurseAddon¶

Gets information on a specific addon.

You will need to provide an addon ID, which can be found by searching a game category.

Parameters: addon_id (int) – Addon ID
Returns: CurseCategory instance representing the addon
Return type: base.CurseAddon

addon_description(addon_id: int) → CurseDescription¶

Gets the description of a specific addon.

Parameters: addon_id (int) – Addon ID
Returns: CurseDescription instance representing the addon’s description
Return type: base.CurseDescription

addon_file(addon_id: int, file_id: int) → CurseFile¶

Gets information on a specific file associated with an addon.

Parameters

addon_id (int) – Addon ID
file_id (int) – File ID

Returns

CurseFile instance representing the addon file

Return type

base.CurseFile

addon_files(addon_id: int, search: Optional[SearchParam] = None) → Tuple[CurseFile]¶

Gets a list of files associated with the addon.

Parameters: addon_id (int) – Addon ID
Returns: Tuple of CurseFile instances representing the addon’s files
Return type: Tuple[base.CurseFile]

catagories(game_id: int) → Tuple[CurseCategory, ...]¶

Gets ALL valid categories for a specific game.

This call can get expensive, so call in moderation!

Parameters: game_id (int) – Game ID to get catagories for
Returns: Tuple of CurseCategory instances
Return type: Tuple[base.CurseCategory, …]

category(category_id: int) → CurseCategory¶

Returns information on a category for a specific game.

Parameters

game_id (int) – ID of the game
category_id (int) – ID of the category

Returns

CurseCategory instance representing the category

Return type

base.CurseCategory

file_description(addon_id: int, file_id: int) → CurseDescription¶

Gets a description of an addon file.

Parameters

addon_id (int) – Addon ID
file_id (int) – File ID

Returns

CurseDescription representing the description

Return type

base.CurseDescription

game(id: int) → CurseGame¶

Returns information on a specific game.

Parameters: id (int) – ID of the game to get
Returns: CurseGame instance representing the game
Return type: base.CurseGame

games() → Tuple[CurseGame]¶

Returns a tuple of all games supported on curseforge.

This call can be somewhat intensive, so it’s a good idea to not call it often. Make a note of the relevant game’s information!

Returns: Tuple of CurseGame instances
Return type: Tuple[base.CurseGame]

iter_search(game_id: int, search: Optional[SearchParam] = None) → CurseAddon¶

Iterates over all results from the search operation.

We automatically bump the SearchParam by one after each call. We will keep yielding until we receive a tuple that has a length of zero, which at that point we will break.

Because we only bump the index value, we will start on the index that was provided by the SearchParam object. For example, if the index starts at one, then we will return each addon from that page on.

We use the ‘search’ method under the hood.

This method is best used in for loops/situations where iterators are used! Because we are a generator, calling this method on it’s own is not recommended! If you want a list of values, use the ‘list()’ method on us.

Parameters

game_id (int) – Game ID to search under
search (SearchParam) – Search Parameter to use

Returns

Each CurseAddon that returned during the search operation.

Return type

base.CurseAddon

load_default()¶: We simply load the cursepy default handler map.

search(game_id: int, search: Optional[SearchParam] = None) → Tuple[CurseAddon, ...]¶

Searches a given game for addons.

The game_id parameter is required for searching, but the search parameter can optionally be provided to fine-tune to search.

Each implementation has different search backends, so it is important to pass the correct search instance! If a search instance is not passed, then one will be automatically created.

Parameters

game_id (int) – ID of the game to search under
search (Any) – Search options to fine tune the search, optional

Returns

Tuple of addons that matched the search parameters

Return type

Tuple[base.CurseAddon, …]

sub_category(category_id: int) → Tuple[CurseCategory, ...]¶

Gets the sub-categories of the given category.

We return a tuple of CurseCategory instances representing the sub-categories

Parameters: category_id (int) – ID of category to get sub-catagories for
Returns: Tuple of CurseCategories representing the sub-categories
Return type: Tuple[base.CurseCategory, …]

class cursepy.wrapper.CTClient(name: str = 'cursepy', load_default=True)¶

CTClient - Implements curse.tools handlers.

Unlike the official curseforge handlers, the curse.tools handlers do NOT require an API key.

This backend does request that an app name be set, probably so the API maintainer can understand where requests are coming from. You can specify this when creating this client. If a name is not provided, then ‘cursepy’ will be used.

class cursepy.wrapper.CurseClient(curse_api_key, load_default=True)¶

CurseClient - Implements curseforge handlers.

We require an API key to work correctly, you can get one here: https://docs.curseforge.com/#getting-started

sub_category(game_id: int, category_id: int) → Tuple[CurseCategory, ...]¶

Gets the sub-categories of the given category.

We return a tuple of CurseCategory instances representing the sub-categories.

Parameters

game_id – ID of the game to get catagories for
category_id (int) – ID of category to get sub-catagories for

Returns

Tuple of CurseCategories representing the sub-categories

Return type

Tuple[base.CurseCategory, …]

class cursepy.wrapper.MinecraftWrapper(curse_api_key, load_default=True)¶

MinecraftWrap - Wrapper for working with Minecraft data on CUrseForge!

Minecraft is one of the most popular games on CurseForge. Because of this, we think it is appropriate to include a wrapper for solely working with Minecraft data.

We offer a lot of convince methods, most notably are the methods for searching/getting addons in a specific category. This will automate the search operation, filling in the necessary info when necessary. This means that you as the user will not have to work(as much) with IDs!

Do note that this wrapper is only valid for official CurseForge backends.

get_minecraft() → CurseGame¶

Returns the CurseGame client that represents minecraft.

Returns: Minecraft CurseGame instance
Return type: base.CurseGame

search_modpacks(search: Optional[SearchParam] = None) → Tuple[CurseAddon, ...]¶

Searches the Modpacks category for addons. Again, we use the SearchParam for the search operation.

Parameters: search (SearchParam, optional) – SearchParameters to use, defaults to None
Returns: Tuple of CurseAddons
Return type: Tuple[base.CurseAddon, …]

search_mods(search: Optional[SearchParam] = None) → Tuple[CurseAddon, ...]¶

Searches the Mods category for addons. Again, we use the SearchParam for the search operation.

Parameters: search (SearchParam, optional) – SearchParam to use, defaults to None
Returns: Tuple of CurseAddons
Return type: Tuple[base.CurseAddon]

search_plugins(search: Optional[SearchParam] = None) → Tuple[CurseAddon]¶

Searches the Plugins category for addons. Again, we use the SearchParam for the search operation.

Parameters: search (SearchParam, optional) – SearchParam to use, defaults to None
Returns: Tuple of CurseAddons
Return type: Tuple[base.CurseAddon]

search_resource_packs(search: Optional[SearchParam] = None) → Tuple[CurseAddon, ...]¶

Searches the Resource Packs category for addons. We use the given SearchParam for the search operation.

Parameters: search (SearchParam, optional) – SearchParam to use, default to None
Returns: Tuple of CurseAddons
Return type: Tuple[base.CurseAddon, …]

search_worlds(search: Optional[SearchParam] = None) → Tuple[CurseAddon, ...]¶

Searches the Worlds category for addons. Again, we use the SearchParam for the search operation.

Parameters: search (SearchParam, optional) – SearchParam to use, defaults to None
Returns: Tuple of CurseAddons
Return type: Tuple[base.CurseAddon, …]

sub_category(category_id: int) → Tuple[CurseCategory, ...]¶

Returns all sub-catagories for the given category.

We automatically pass the game ID when called, so the user can fetch sub-categories without passing a game ID. This allows us to operate like the BaseClient method for getting sub-categories.

Parameters: category_id (int) – _description_
Returns: _description_
Return type: Tuple[base.CurseCategory, …]

Curse Instances¶

Curse Instances are classes that represent info on CurseForge. They allow for an easy and standardized way to interact with CurseForge info.

General classes for representing curseforge information.

class cursepy.classes.base.BaseCurseInstance¶

BaseCurseInstance - Class all child instances must inherit!

A curses instance is a class representing information from curseforge. This allows developers to work with this information in a connivent way.

Some classes might even do operations on the data if needed, or might be able to fetch data themselves.

We seek to standardize curseforge information, allowing developers to work with with only one packet type, regardless of backend/method/source of information.

We also provide a field for supplying metadata about the instance. This can really be anything the backend thinks is helpful, although we recommend keeping it to connection details and statistics.

Packets can also have the raw, unformatted data attached to them. This data is NOT standardized, meaning that the raw data will most likely be different across different handlers. Be aware, that handlers are under no obligation to attach raw data to the packet!

We have the following parameters:

raw - Raw data from the backend(Does not have to be provided!)

meta - Meta data on this instance. See the backend in question for information on metadata

hands - HandlerCollection instance

class cursepy.classes.base.BaseDownloader¶

Parent class for all instances that download information.

We offer some helper methods for achieving this. We expect the protocol to be HTTP.

download(path: Optional[str] = None) → bytes¶

Download function for this class!

Child classes should implement this function! This allows them to fine-tune the download operation automatically, and pass the necessary parameters without the user having to specify them.

Implementations should use the ‘low_download’ function for this operation.

Parameters: path (str, optional) – Path to file to save the downloaded information to, defaults to None
Returns: Downloaded bytes
Return type: bytes
Raises: NotImplementedError: Must be overridden in child class!

low_download(url: str, path: Optional[str] = None) → bytes¶

Downloads the given data and returns it as bytes.

We use the ‘URLProtocol’ to get the information.

We also offer to save the downloaded information to an external file. You can pass the path to the file using the ‘path’ parameter. If this value is none, then the data will not be saved. The data will be returned regardless of weather it is saved or not.

Parameters

url (str) – URL of the content to download
path (str, optional) – Path to file to save downloaded data, optional

Returns

Bytes of the downloaded data

Return type

bytes

class cursepy.classes.base.BaseWriter¶

Parent class that adds writing functionality to the instance.

This class provides tools for writing content to external files, and offers entry points for child classes to fine-tune and configure these writes.

low_write_bytes(data: bytes, path: str, append: bool = False) → int¶

Writes the given data to an external file in bytes.

By default, we overwrite the file at the given path! If this is not something you want, you can pass ‘True’ to the ‘append’ value. This will append the description to the end of the file provided.

We use the internal ‘open’ function built into python. Standard exceptions associated with this function will be raised accordingly!

Parameters

data (bytes) – Data to write to the file
path (str) – Path to the file to write, must be a path-like-object
append (bool, optional) – Value determining if we are appending to the file, defaults to False

Returns

Number of bytes written

Return type

int

low_write_string(data: str, path: str, append: bool = False) → int¶

Similar to low_write_bytes, except we write the content as a string.

Parameters

data (str) – Data to write to file
path (str) – Path to file to write
append (bool, optional) – Value determining if we are appending to the file, defaults to False

Returns

Number of bytes written

Return type

int

write(path: str, append: bool = False) → int¶

Write function for this class.

Child classes should implement this function! This allows them to fine-tune the write process automatically, and pass the content to be written without the user having to specify it.

Child classes should use the ‘low_write’ function to preform the operation.

Parameters

path (str) – Path to the file to write to
append (bool, optional) – Value determining if we should append instead of overwrite, defaults to False

Raises

NotImplementedError – Function should be overridden in child class!

Returns

Number of bytes written

Return type

int

class cursepy.classes.base.CurseAddon(name: str, slug: str, summary: str, url: str, lang: str, date_created: str, date_modified: str, date_release: str, id: int, download_count: int, game_id: int, available: bool, experimental: bool, authors: Tuple[CurseAuthor, ...], attachments: Tuple[CurseAttachment, ...], category_id: int, root_category: int, all_categories: Tuple[CurseAddon, ...], is_featured: bool, popularity_score: int, popularity_rank: int, allow_distribute: bool, main_file_id: int, status: int, wiki_url: str, issues_url: str, source_url: str)¶

CurseAddon - Represents a addon for a specific game.

An ‘addon’ is something(mod, modpack, skin) that is added onto a game to change or add certain features and aspects.

The definition of a generic addon is purposely left ambiguous, as it can be anything from a resource pack in minecraft to a mod in Kerbal Space Program. If you want something a bit more helpful and specific to a game, then the game wrappers might be helpful!

This class contains useful metadata on a addon. We do NOT contain a detailed description information.

We contain the following parameters:

name - Name of the addon

slug - Slug of the addon

summary - Short summary of the addon

url - URL of the addon page

lang - Language of the addon

date_created - Date of creation

date_modified - Date of last modification

date_release - Date of the latest release

id - ID of this addon

download_count - Number of downloads

game_id - ID of the game this addon is in

available - Boolean determining if the addon is available

experimental - Boolean determining if the addon is experimental

authors - Tuple of authors for this addon

attachments - Tuple of attachments attributed with this addon

category_id - ID of the primary category this addon is apart of

root_category - ID of the root category this addon is apart of

all_categories - Tuple of all catagories this addon is affiliated with

is_featured - Boolean determining if this addon is featured

popularity_score - Float representing this addon’s popularity score
(Most likely used for popularity ranking)

popularity_rank - Int representing the game’s popularity rank

allow_distribute - If addon is allowed for distribution

main_file_id - ID of the main file for this addon

status - Status of this addon (new, approved, under review, ect.), use the class constants for this!

wiki_url - URL to the wiki of this mod, blank string if not specified

issues_url - URL to the issues page of this mod, blank string if not specified

source_url - URL to the source code of this mod, blank string if not specified

We also contain the following constants for identifying the status:

NEW - Used if the addon is new, no further actions have been made

CHANGES_REQUIRED - Used if the addon needs changes before approval

UNDER_SOFT_REVIEW - Used if the addon is under soft review (elaborate?)

APPROVED - Used if this addon is approved by the backend, good to be used

REJECTED - Used if this addon is reject by the backend, not to be used

CHANGES_MADE - used if changes have been made since the last review

INACTIVE - Used if this addon is inactive

ABANDONED - Used if this addon is abandoned

DELETED - Used if this addon has been deleted

UNDER_REVIEW - Used if this addon is under review

category() → CurseCategory¶

Gets and returns the category we are a member of

Returns: CurseCategory of the category we are in
Return type: CurseCategory

property description: CurseDescription¶

Gets the description for this CurseAddon.

Whatever handler is assigned to addon descriptions will be used to generate a CurseDescription.

Returns: CurseDescription representing this addon
Return type: CurseDescription

file(file_id: int) → CurseFile¶

Gets a file associated with this addon. We use this addon ID to get the file.

Parameters: file_id (int) – ID of the file to find
Returns: CurseFile representing the file
Return type: CurseFile

files() → Tuple[CurseFile, ...]¶

Gets a tuple of files associated with this addon.

Returns: Tuple of CurseFile instances
Return type: Tuple[CurseFile, …]

game() → CurseGame¶

Gets and returns the CurseGame instance this addon is apart of.

Returns: CurseGame instance
Return type: CurseGame

class cursepy.classes.base.CurseAttachment(title: str, id: int, thumb_url: str, url: str, is_thumbnail: bool, addon_id: int, description: str)¶

CurseAttachment - Represents an attachment.

An ‘attachment’ is a piece of media, usually an image or thumbnail, that is shown on the addon page.

These attachments can be the icon of the addon, as well as bonus images of the addon provided by the author.

We contain useful metadata on said images, and we also offer tools to download and save these images.

We contain the following parameters:

title - Title of the attachment

id - ID of the attachment

thumb_url - URL of the thumbnail image(If attachment is image, then thumbnail is smaller image)

url - URL of the attachment

is_thumbnail - Boolean determining if this attachment is the thumbnail of the addon

description - Description of this attachment

download(path: Optional[str] = None) → bytes¶

Downloads the attachment.

You can use the ‘path’ parameter to save the downloaded information to a file.

If you provide a path to a directory and not a file, then we will use the name of the remote file as the name.

Parameters: path (str) – Path to save the data to, optional
Returns: Downloaded bytes
Return type: bytes

download_thumbnail(path: Optional[str] = None) → bytes¶

Downloads the thumbnail of this attachment.

You can use the ‘path’ parameter to save the thumbnail to a file.

Like the download method, we automatically generate a name if the path is None, or is just a directory.

Parameters: path (str, optional) – Path to save the file to, defaults to None
Returns: downloaded bytes
Return type: bytes

class cursepy.classes.base.CurseAuthor(id: int, name: str, url: str)¶

CurseAuthor - Represents an author for a curses addon.

An ‘author’ is an account that published a curses addon.

This class only contains metadata on a author. The information in this class is not necessary for getting addon information. Instead, it is extra info for those interested.

Completely disregard this info if it is not relevant to you!

We contain the following parameters:

id - ID of this author

name - Name of the author

url - URL to author’s page

class cursepy.classes.base.CurseCategory(id: int, game_id: int, name: str, root_id: int, parent_id: int, icon: CurseAttachment, url: str, date: str, slug: str)¶

CurseCategory - Represents a category for a specific game.

A ‘category’ is a collection of addons for a specific game. Lets use Minecraft as an example, Minecraft has the following catagories:

Resource Packs

Modpacks

Mods

Worlds

If you wanted to get info on a mod, then you would search in the ‘Mods’ category. This allows addons to be organized by type.

This class contains identifying info on catagories, most important being the category ID, which is needed to search for projects in that specific category.

Categories can be nested, meaning that each category can have a variable number of child categories. We contain references to the root_id, which is the ID of the root category for all nested categories. The parent_id is the ID of the category one level up from ours.

We contain the following parameters:

id - ID of the category

game_id - ID of the game this category is under

name - Name of the category

root_id - ID of the root category

parent_id - ID of the parent category

icon - CurseAttachment of this catagories icon

url - URL to the category page

date - Date this category was created

slug - Slug of the category

parent_category() → CurseCategory¶

Gets and returns the parent category for this instance.

If there is no parent category, then ‘None’ will be returned instead

Returns: CurseCategory instance, or None if there is no parent
Return type: CurseCategory, None

root_category() → CurseCategory¶

Gets and returns the root category for this instance.

If there is no parent category, then ‘None’ will be returned instead.

Returns: CurseCategory instance, or None if there is no parent
Return type: CurseCategory, None

sub_categories() → Tuple[CurseAddon, ...]¶

Gets all sub-catagories for this category.

Returns: Tuple of sub-categories for this category
Return type: Tuple[CurseCategory, …]

class cursepy.classes.base.CurseDependency(id: int, addon_id: int, file_id: str, type: str)¶

CurseDependency - Represents a dependency of an addon.

A dependency is an addon file that is wanted or required by another addon. This class represents these dependencies.

We contain useful metadata on each dependency, such as the addon ID and file ID this addon is apart of. We also offer methods to retrieve the addon and file.

In some cases, we will not have all the required dependency information such as the dependency ID and file ID. This can happen if you use the ForgeSVC handlers and get ALL addon files instead of requesting a specific one. If this dependency instance is limited, then ‘id’ and ‘file_id’ will be None.

We contain the following parameters:

id - ID of the dependency

addon_id - ID of the addon this dependency is apart of

file_id - ID of the file this dependency is apart of

type - Type of the dependency

required - Whether or not this dependency is required

We also contain the following constants:

INCLUDE - TODO: Document this

INCOMPATIBLE - This dependency is incompatible

TOOL - This dependency is an optional tool

REQUIRED - This dependency is required

OPTIONAL - This dependency is optional

EMBEDDED_LIBRARY - This dependency is an embedded library

addon() → CurseAddon¶

Gets the CurseAddon this dependency is apart of.

Returns: CurseAddon this dependency is apart of
Return type: CurseAddon

file() → CurseFile¶

Gets the CurseFile this dependency is apart of.

Returns: CurseFile this dependency is apart of
Return type: CurseFile

property required: bool¶

Determines if this dependency is required.

Returns: True is required, False if not
Return type: bool

class cursepy.classes.base.CurseDescription(description: str)¶

CurseDescription - Represents a description of a addon.

A ‘description’ is HTML code that the addon author can provide that describes something in detail. Addons and file descriptions fall into this category.

Again, this description is in HTML, so some formatting may be necessary!

We offer the ability to attach custom ‘formatters’ to this object. A ‘formatter’ will convert the HTML code into something. The implementation of formatters is left ambiguous, as users may have different use cases. Check out the formatter documentation for more info.

A formatter can be attached to us manually, or it can automatically be added upon each call by the CursesAPI or wrapper.

We also offer the ability to save the description to an external file for later usage.

We contain the following parameters:

description - Raw, unformatted description

formatter - Formatter instance attached to this object

attach_formatter(form: BaseFormat)¶

Attaches the given formatter to this instance.

We do a check to make sure that the formatter inherits ‘BaseFormat’.

Parameters: form (BaseFormat) – Formatter to attach to this description
Raises: TypeError: If the formatter does NOT inherit ‘BaseFormat’

format() → Any¶

Sends the description through the formatter, and returns the formatted content, whatever that may be.

Returns: Formatted data
Return type: Any

write(path: str, append: bool = False) → int¶

Writes the description to an external file.

We use the CurseWriter ‘low_write’ method for this operation.

We write the raw content, as formatters may not return writable components!

Parameters

path (str) – Path to the file to write, must be a path-like-object
append (bool, optional) – Value determining if we are appending to the file, defaults to False

Returns

Number of bytes written

Return type

int

class cursepy.classes.base.CurseFile(id: int, addon_id: int, display_name: str, file_name: str, date: str, download_url: str, length: int, version: ~typing.Tuple[str, ...], dependencies: ~typing.Tuple[~cursepy.classes.base.CurseDependency, ...], game_id: int = -1, is_available: bool = True, release_type: int = -1, file_status: int = -1, hashes: ~typing.Tuple[~cursepy.classes.base.CurseHash, ...] = <factory>, download_count: int = -1)¶

CurseFile - Represents an addon file.

An ‘addon file’ is a specific file available in an addon. Because multiple versions for an addon can exist, most addons have multiple files that can be downloaded.

We contain useful metadata on each file, and offer the ability to download said file, as well as retrieve the changelog.

We contain the following parameters:

id - ID of the file

addon_id - ID of the addon this file is apart of

display_name - Display name of the file

file_name - File name of the file

date - Date the file was uploaded

download_url - Download URL of the file

length - Length in bytes of the file

version - Version of the game needed to work with this file

dependencies - Tuple of CurseDependency objects

game_id - ID of the game this file is apart of

is_available - Boolean determining if this file is available for download

release_type - Release type of this file (beta, alpha, release), use class constants for identifying this!

file_status - Status of the file (approved, under review, deprecated, ect.), use the constants below for this!

hashes - Tuple of CurseHashes representing file hashes

download_count - Number of times this addon has been downloaded

We also contain the following constants:

RELEASE - Used if the release type is ‘release’ (For for production use)

BETA - Used if the release type is ‘beta’

ALPHA - Used if the release type is ‘alpha’

PROCESSING - Used for file status if the file is currently being processed

CHANGES_REQUIRED - Used for file status if the file needs changes before approval

UNDER_REVIEW - Used for file status if the file is currently under review

APPROVED - Used for file status if the file is approved

REJECTED - Used for file status if the file is rejected

MALWARE_DETECTED - Used for file status if malware is detected in the uploaded file

DELETED - Used for file status if the file has been deleted

ARCHIVED - Used for the file status if the file has been archived

TESTING - Used for the file status if the file is in the testing phase

RELEASED - Used for the file status if the file is released, if this is the status, then the file is ready to be used!

READY_FOR_REVIEW - Used for the file status if the file is ready for review

DEPRECATED - Used for the file status if the file has been marked as deprecated

BAKING - Used for the file status TODO: What does this mean?

AWAITING_PUBLISHING - Used for file status if the file is awaiting publishing

FAILED_PUBLISHING - Used for file status if the file has failed publishing

property changelog: CurseDescription¶

Gets the changelog of this file, and returns it as a CurseDescription object.

Whatever handler is registered to the HandlerCollection for getting game descriptions will be used!

Returns: CurseDescription representing the description of this file
Return type: CurseDescription

download(path: Optional[str] = None) → bytes¶

Downloads the file.

If the provided path points to a directory, then the default file name will be used.

Parameters: path (str) – Path to download the file to, optional
Returns: Downloaded file bytes
Return type: bytes

get_addon() → CurseAddon¶

Gets the CurseAddon this file is apart of.

Returns: CurseAddon this file is apart of
Return type: CurseAddon

get_dependencies(depen_type: int) → Tuple[CurseDependency, ...]¶

Returns a tuple of CurseDependency objects that this addon file requires.

Users can specify a dependency type, which will only return dependencies that match the given type. You can use the dependency

Parameters: depen_type (int) – Dependency type to return
Returns: Tuple of CurseDependency objects
Return type: Tuple[CurseDependency, …]

good_file() → bool¶

This method determines if this file is valid and ready to be used.

We do this by checking the release type, file status, and if the file is available for download. If this file is valid, then we return True.

Just because a file is not good does not mean that it can’t be used! On top of this, just because a file is good does not mean it will work properly! We only check if the file is downloadable and marked production ready. Production ready files could be poorly made, and non-production experimental files could also be valid.

Returns: Boolean determining if this file is ‘good’
Return type: bool

guess_download() → str¶

This method will attempt to guess the download URL.

Some addons do not allow distribution on 3rd party services and APIs. If this is the case, then the download URL will be ‘None’. This method will use available info to make a best guess URL for use.

We do this by splitting up the file ID into parts of 4 and merging some attributes together. For example, if we have an id of ‘1234567’ and a filename of ‘test.jar’, we will get the following download URL:

https://edge.forgecdn.net/files/1234/567/test.jar

Please note, this method is experimental and might not work! It is ALWAYS recommended to use the provided download URL, if one is provided. Also, this method will generate a URL for the official CurseForge CDN.

Once you have this guess, you can set the ‘download_url’ parameter to the value returned from this method, and download the file from there:

file.download_url = file.guess_download()
file.download(PATH)

Or, you can use this URL directly in the download operation:

file.low_download(file.guess_download(), PATH)

We use the ‘low_download()’ method, as it accepts a custom URL.

Returns: The best guess download URL
Return type: str

class cursepy.classes.base.CurseGame(name: str, slug: str, id: int, support_addons: float, icon_url: str = '', tile_url: str = '', cover_url: str = '', status: int = -1, api_status: int = -1)¶

CurseGame - Represents a game on curseforge.

A game is a collection of addons/catagories that are relevant to a specific title, such as World of Warcraft or Minecraft.

Game instances can have useful meta info for a particular title, but the most important are the game ID and catagories info, as you will need these values to get more precise project information.

Not all games support addons! Some games are listed for reasons unknown, and do not have addon support. You can determine if a game has addon support by checking the ‘support_addons’ parameter.

Some values are not loaded and interpreted by this class! These include game detection hints(Used for determining where a game is), and game file information(What files are necessary for modding and where they can be found). If this information is important to you, then the raw data can be found under the ‘raw’ parameter.

We contain the following parameters:

name - Name of the game

slug - Slug of the game

id - ID of the game

support_addons - Boolean determining if this game supports addons

icon_url - URL to the icon of the game

tile_url - URL to the tile picture of the game

cover_url - URL to the banner/cover of the game

status - Status of this game (draft, test, approved, ect.), use constants for defining this!

api_status - Weather this game is public or private, use constants for defining this!

categories() → Tuple[CurseCategory, ...]¶

Gets a tuple of all root categories for this game.

Returns: Tuple of all root CurseCategories
Return type: Tuple[CurseCategory, …]

iter_search(search_param: Optional[SearchParam] = None) → CurseAddon¶

Invokes the ‘iter_search’ method of the HC with the given search parameters.

You should check out HC’s documentation on ‘iter_search’, but in a nutshell it basically allows you to iterate though all found addons, automatically incrementing the index when necessary.

Parameters: search_param (Optional[SearchParam], optional) – [description], defaults to None
Returns: Each curse addon found
Return type: CurseAddon

search(search: Optional[SearchParam] = None) → Tuple[CurseAddon, ...]¶

Searches for addons under this game.

Parameters: search (BaseSearch, optional) – Search object to use, defaults to None
Returns: Tuple of CurseAddon objects
Return type: Tuple[CurseAddon, …]

class cursepy.classes.base.CurseHash(hash: str, algorithm: int)¶

CurseHash - Represents a hash of some kind.

Some backends distribute hashes for some reason or another. In most cases, these hashes are of files to ensure that the downloaded data is valid.

This class keeps track of the hash value, as well as the possible algorithms used to determine the hash. You can use the constants attached to this class to determine the hashing algorithm.

We contain the following parameters:

hash - Raw hash value

algorithm - Hashing algorithm used, used constants to identify this!

We also contain the following constants:

SHA1 - Secure Hash Algorithm 1

MD5 - Message Digest 5 algorithm

Handler Components¶

Documentation on basic handler components that act as building blocks for other handlers.

This file contains base components for handler development.

A ‘handler’ is something that ‘handles’ data from a specific source of a specific type. Essentially, when data comes from a specific source, the handler is the thing that gets and formats that data into something that is easy to work with. A handler may also fetch data from elsewhere to fill in the blanks.

In this file, we outline some of the functionality of a handler, and layout certain components that it will need to play nicely with everything else.

Because handlers can do a large variety of things, the specific implementation is left ambiguous.

By default, the HandlerCollection only works with the ‘handle’ method, which will accept raw data from the service we are talking to. There will be other components that the handler can override if necessary.

class cursepy.handlers.base.BaseHandler(name: str = '')¶

BaseHandler - Child class all handlers must inherit!

We offer some basic methods that a handler should inherit, as well as define the cappy Handler Framework(CHF).

Essentially, the function makeup of the CHF is this:

make_proto - Should return a valid protocol object for this handler

proto_call - Call to the protocol of this handler, should return valid raw data

pre_process - Decodes data from the protocol before being send to the handler

format - Method called for formatting raw data from the protocol

post_process - Finalizes the formatted data(Adds metadata, raw data, ect.)

handle - Invokes the handling process for this handler

This allows handlers to control many aspects of their implementation. With smart inheritance, it also removes a lot of repeated calls and instructions. These functions are called in the order defined above. Everything from getting information to formatting can be customized.

Handlers are identified by instance types. Instance types are simply an integer that represents what this handler does.

The handle method is the entry point for handlers. It will accept the arguments and information from the handler collection, and will work with them as necessary. The default handle method will call all components in order, so it is a good idea to use ‘super()’ once you have configured your methods. You can configure the handle method to accept any arguments you like, the HandlerCollection will pass all arguments that it receives to the ‘handle’ method, so you should use this as the primary way to accept arguments.

The handler ID will be stored under the ID parameter. Unidentified handlers will have an ID of -1. Handlers must be identified if they are to be used for handler processes!

These handlers are designed to be customizable! The CHF is designed to be a good default implementation, that minimizes the amount of code developers have to write for handler development.

Don’t like the CHF? No problem! Most of the functions defined here are not necessary for handlers to work! The only functions that NEED to be defined are ‘handle’ and ‘make_proto’. This means you can define your own methods and frameworks by creating a custom ‘handle’ method, that can call/do anything you would like it too.

format(data: Any)¶

Converts the given raw data into something, usually a CurseInstance.

In here, we format and organize the given data into something that is useful to the user.

This formatter can do other things if necessary, and they don’t necessarily have to be within the scope of formatting! However, it is recommended to use the ‘handle’ method for other use cases.

Parameters: data (Any) – Data to be formatted

get_proto() → BaseProtocol¶

Gets the given protocol object from the HandlerCollection.

If a protocol of our name is present, then we will get it for our continued use. If not, then we will create one and register it to our name.

If a protocol of our name is present, and it does not match the type of the protocol we are attempting to assign, then a ‘ProtocolMismatch’ exception will be raised.

Parameters: proto (BaseProtocol) – Protocol object type to fetch
Returns: Protocol instance that we will use
Return type: BaseProtocol
Raises: ProtocolMismatch – Raised when a protocol mismatch occurs

handle(*args, **kwargs) → Any¶

Default handle method.

This is the default handle method, meaning that we call all components in order.

We pass all arguments to ‘proto_call’, as this is the component that will need these arguments to fetch information.

We also check to see if we are working with a tuple of instances. If this is the case, then we iterate over them and post-process each instance.

make_proto() → Any¶

Function called when we need a valid protocol object.

This usually occurs when a ‘get_proto’ check determines that no protocol exists for this handler. If this is the case, then this function should return a valid protocol object for this handler and other handlers of this same name.

post_process(data: Any) → Any¶

Finalizes the packet after it is created.

This can do many things, attach raw data, metadata, anything the developer thinks is necessary.

Parameters: data (Any) – Data packet to be finalized
Returns: Finalized packet
Return type: Any

pre_process(data: Any) → Any¶

We pre-process the raw information for the protocol, and convert it into something the handler can understand.

Parameters: data (Any) – Data to decode

proto_call() → Any¶

Calls the underlying protocol instance of this handler.

This function only calls the protocol instance! We do not decode or interpret this information, we only get it and return.

Returns: Raw data from the protocol
Return type: Any

start()¶

Function called when this handler is attached to a HandlerCollection.

The user can put any relevant code here that would be appropriate to run at loadtime.

stop()¶

Function called when this handler is removed from a HandlerCollection.

Again, the user can put any relevant code here that would be appropriate to run at stop time.

class cursepy.handlers.base.HandlerCollection(load_default=True)¶

HandlerCollection - Manages and works with handlers!

This allows wrappers and backends to easily manage and work with handlers.

We normalize calling, adding, and removing handlers. This allows for handler auto configuration, and other time saving features.

We also provide a collective space for handlers to share protocol objects between like-minded handlers.

Only one handler can be registered to a given event! These handlers can be of different types and come from different sources, but only one can be registered to a given event!

We define some entry points for calling handlers. These functions will be called by the users actually using these handlers. We define some arguments that should be defined, as well as what we expect the functions to return.

Users can optionally attach callbacks to certain events. These callbacks should be a callable, which will be called after the handle event is complete. Callbacks should accept at least one argument, which is the data the handler is returned. Any other arguments can be optionally provided.

You can utilize wrappers to change what functions expect and return. Be aware, that default dataclasses will call the functions defined here with the given arguments!

Sub-classing us is recommended and encouraged! This allows developers to easily automate actions, and make interacting with certain games much easier.

By default, we call the ‘load_default()’ method upon instantiation. Wrappers should probably overload that method! If this is not something you want, you can pass False to the ‘load_default’ parameter.

add_handler(hand: BaseHandler, id: Optional[int] = None)¶

Adds the given handler to the HandlerCollection.

By default, we pull the instance ID out of the handler. However, the developer can manually provide an instance ID to register the handler to. If this is the case, then the ID on the handler will be ignored.

We use ‘remove_handler()’ to remove the handler at this location.

The handler to be added MUST inherit BaseHandler! If it does not, then a ValueError will be raised.

Parameters

hand (BaseHandler) – Handler to register
id (int) – ID to register the handler to, None to use ID on given handler

Raises

TypeError: If the handler does not inherit BaseHandler

bind_callback(call: Callable, id: int, *args, **kwargs) → Callable¶

Binds a callback function to the handler at the given ID.

We can either be called the conventional way, or we can be used as a decorator.

Your run function should take at least one parameter, which will be the CurseInstance associated with the handler. Other arguments can optionally be provided.

We keep a reference of the callback and arguments in this class as a dictionary. You can alter this structure yourself, but it is recommended to use the higher level methods for this.

Any extra arguments that are passed will be saved and passed to the callback at a later time.

Multiple callbacks can be registered to an event! The order that they are added will be the order that they will be called.

The callback will be called after the data is retrieved, decoded, and formatted!

Parameters

call (function) – Callback function to add to the handler
id (int) – ID of the handler to bind the callback to

clear_callback(id: int, call: Optional[Callable] = None) → int¶

Clears the callback from the given event.

If a callback is not specified, then ALL callbacks will be cleared. If a callback is specified, then the callbacks that match the provided object will be deleted.

Parameters

id (int) – ID to clear
call (Callbale, None) – Callback to remove, optional

Returns

Number of callbacks removed.

Return type

int

default_formatter(form: BaseFormat)¶

Registers a default formatter to this object.

We automatically attach the default formatter to any CurseDesciprion objects we return.

If the CurseDescrpition does not inherit BaseFormat, then we will raise a TypeError excpetion.

Parameters: form (BaseFormat) – Formatter to register
Raises: TypeError: If formatter does not inherit BaseFormat!

get_handler(id: int) → BaseHandler¶

Returns the handler at the given ID.

Parameters: id (int) – ID of the handler to get
Returns: The handler in question
Return type: BaseHandler

get_search() → SearchParam¶

Returns a SearchParam used for searching.

Returns: SearchParam object used for searching
Return type: SearchParam

handle(id: int, *args, **kwargs) → Any¶

Invokes the handle process at the handler with the given ID.

As outlined earlier, this gets and formats data from an external location.

We pass all arguments and keyword arguments to the handler at the given ID.

We also attach ourselves to valid CurseInstances automatically! If the returned data does not inherit BaseCurseInstance, then we will not attempt to attach ourselves to it, and simply return it.

Parameters: id (int) – ID of the handler to call
Returns: The final class provided by the handler
Return type: BaseCurseInstance

load_default()¶

Loads the default handlers for this HandlerCollection.

We are called at instantiation if load_default is True. It can also be called at any point during the lifecycle of the collection.

This function should load a set of handlers that is relevant to the operation of the HandlerCollection.

By default, we raise a ‘NotImplementedError’. It is up to wrappers to implement this function!

It is probably best if this function used the ‘load_handlers()’ method to do all the dirty work.

load_handlers(mapper: Any)¶

Loads handlers from the given iterable.

This function allows multiple handlers to be loaded at once, and in a certain priority.

We use the iterables to determine the priority and ID of the handler. During the load, if the handler at the given ID is NOT a NullHandler, then it will be skipped. This allows for handler priorities to be set.

The ‘root’ iterable should contain sub-iterables that map handlers to ID’s. The lower the index, or key, of the handler map, the higher priority they will have. This allows lower priority handlers to ‘fill in the blanks’ of there higher priority counterparts.

The iterables can be lists or tuples, (Tuples are recommended for memory and speed reasons, and are the iterable method used for built in handlers). You can also use a dictionary to denote ordering. The keys for the dictionary should be an integer. Higher integers mean they are lower priority.

If the dictionary is used as a handler map, then the key should be the ID that the handler is going to associate with.

Here is an example of an iterable for loading handlers:

(
    (
        Hand1(),
        Hand1(),
        Hand1()
    ),
    {
        0: Hand2(),
        2: Hand2(),
        4: Hand2()
    }
)

In this example, the handler map will look like this:

0 - Hand1
1 - Hand1
2 - Hand1
4 - Hand2

Notice, that even though Hand2 was assigned to ID’s 0 and 2, it was not used, as Hand1 had a higher priority. However, ID 4 had no handlers assigned to it, so Hand2 was allowed to associate with it.

Here is another example, and instead of utilizing dictionaries for skipped indexes, we simply use a NullHandler as a placeholder:

(
    (
        Hand1(),
        Hand1(),
        NullHandler(),
        Hand1()
    ),
    (
        Hand2(),
        NullHandler(),
        Hand2(),
    )
)

In this example, we do not assign a handler for the 2nd index in the first priority handler map, and instead assign a NullHandler in it’s place. Because NullHandlers are ALWAYS a lower priority, the lower priorities will overrite them, even though they have been specified. This allows users to skip ID’s without having to use dictionaries.

We use ‘add_handler()’ under the hood, and we use recursion to iterate over the handlers.

Parameters: loader (Any) – Iterable to load

remove_handler(id: int)¶

Removes the handler at the given ID.

We replace the handler with a NullHandler to ensure that something is working with data no matter what.

We will automatically stop the handler at this location.

Parameters: id (int) – ID of the handler to remove

reset()¶

Resets the HandlerCollection back to it’s original state.

This clears all handlers and replaces them with NullHandlers. We also remove all affiliated protocol instances.

Be warned, if not referenced, the removed handlers and all information on them may be erased!

class cursepy.handlers.base.NullHandler(name: str = 'Nullhandle', id: int = 0)¶

NullHandler - Does nothing

As in the name, all information given to us will be ignored, and we will simply return ‘None’.

Great if you want to disable a certain feature.

The only thing that needs to be specified is what ID we are being registered to. This is optional, as you can manually provide your own ID in the HandlerCollection.

We are used as a default handler that is attached to ID’s that have no handlers associated with them.

handle(*args, **kwargs) → None¶

As we are a NullHandler, we simply return None.

Returns: None
Return type: None

class cursepy.handlers.base.RaiseHandler(name: str = 'RaiseHandler', id: int = 0)¶

Raises an exception when the ‘handle’ method is called.

This is very similar to the NullHandler, but we go a step further by raising an exception.

This can be used as a more explicit, forceful way of disabling a feature, compared to just doing nothing.

You can optionally change the name of the handler, as well as provide a custom ID.

handle(*args, **kwargs)¶

Raise a ‘HandlerRaise’ excpetion.

Raises: HandlerRaise: Always

class cursepy.handlers.base.URLHandler(name: str, host: str, extra: str = '/', path: str = '')¶

URLHandler - Parent class for handlers using URLProtocol.

We offer some ease of use features, such as automatically registering our protocol as URLProtocol, and simplifying the process for getting information from remote resources. We use the given information to automatically build URLs to get data from.

We also offer ways to get the HTTPResponse of the last made request, and offer an easy way to generate metadata for curse instances.

build_url(*args) → str¶

Method called by the ‘proto_call()’ method when a URL needs to be built.

This is useful for generating custom URL’s that may change with diffrent requests. By default, we simply return the result of URLProtocol’s build_url() method, with the path parameter as the argument.

Returns: Build URL to make our request to
Return type: str

handle(*args) → Any¶

We do the same as the BaseHandler’s handle method, except we call the ‘build_url’ method to generate a valid URL.

We pass all arguments to the ‘build_url()’ method.

Returns: CursesInstance generated from this handler
Return type: BaseCurseInstance

make_meta() → dict¶

Makes valid metadata about the request and connection and returns it.

This is a good way to integrate connection stats into your CurseInstances!

The meta information is structured like this:

headers - A list of (header, value) tuples

version - HTTP Protocol version used by server

url - URL of the resource retrieved

status - Status code returned by server

reason - Reason phase returned by server

These values are returned in dictionary format.

make_proto() → URLProtocol¶

Creates and returns a valid URLProtocol instance.

We automatically add the extra path information to the protocol instance.

Returns: Valid URLProtocol for this handler
Return type: URLProtocol

proto_call(*args) → bytes¶

Creates a valid URL using ‘build_url()’, and then passes this value to the protocol instance. We pass all arguments to the ‘build_url()’ method.

We return the raw data from the HTTP request for further processing. We also save the HTTPResponse for future reference, specifically to generate metadata fro curse instances.

Returns: Raw data from the protocol object
Return type: bytes

Protocol Objects¶

Low level tools and components for network communication.

We offer components that can be used to get curseforge information from somewhere, in this case HTTP get requests.

class cursepy.proto.BaseProtocol(host: str, port, timeout: int = 60)¶

Base protocol implementation - All child protocols must inherit this class!

A ‘protocol’ is a class that eases low level network communications. Protocols only handle the getting(And maybe transmission) of information. Protocols do not engage in any unnecessary content parsing, interpreting, or decoding!

Protocols are designed to be modular, and can be ‘attached’ to implementations/backends. This is not something the user will have to do, handlers will auto-configure the protocol they are designed to use.

We keep this implementation ambiguous, although we do define some behavior that all protocols MUST implement!

class cursepy.proto.TCPProtocol(host: str, port: int, timeout: int = 60)¶

TCPProtocol - Protocol object for data exchange via TCP sockets.

We offer convince methods for working with TCP sockets. We also provide methods for generating valid metadata, which will provide the number of bytes transmitted/received, as well as the remote entity we are communicating with.

read(length: int) → bytes¶

Reads content from the TCP socket. We make sure to check the received data length to ensure that we read everything that we expect.

Parameters: length (int) – Number of bytes to read
Returns: Retrieved bytes
Return type: bytes

write(byts: bytes)¶

Writes data over the TCP socket.

Parameters: byts (bytes) – Bytes to write

class cursepy.proto.UDPProtocol(host: str, port, timeout: int)¶

UDPProtocol - Protocol object for data exchange via UDP sockets.

We offer convenience methods for working with UDP sockets. Like TPCProtocol, we keep metadata that keeps track of data transferred, as well as the address of the last exchange.

read() → bytes¶

Reads content over the UPD socket.

Returns: Bytes read
Return type: bytes

write(byts: bytes)¶

Writes data over the UPD socket.

Parameters: byts (bytes) – Bytes to write

class cursepy.proto.URLProtocol(host: str, timeout: int = 60)¶

URLProtocol - Gets information via HTTP.

We seek to ease the process of retrieving information via HTTP requests. We not only facilitate the communication process, but we also provide other features such as user defined headers, URL generation, and we implement the protocol caching system.

The host will be used to automatically build URLs if used. If you want to provide URLs manually, you can use lower level methods to do so.

We raise the usual urllib exceptions if issues arise.

get_data(url: str, timeout: Optional[int] = None, data: Optional[dict] = None) → bytes¶

Gets and returns raw data from the given URL.

By default, we get this data via a HTTP GET request, and return the raw bytes from this request.

The user can optionally provide a dictionary of data, which will turn this call into a POST operation.

We handle caching, if enabled, and will automatically get and update values from said cache.

Parameters

url (str) – URL to get data from
timeout (Optional[dict], optional) – Timeout of the operation, default value if None is used
data (dict) – Data to use in the call, converting this to a POST operation

Returns

Raw string data from the given URL

Return type

str

low_get(url: str, timeout: Optional[int] = None, heads: Optional[dict] = None) → HTTPResponse¶

Low-level get method.

We get the necessary data from the server and return the corresponding HTTP object.

If you want to work with HTTPResponse objects directly, (Like if you want to get information regarding return codes and other information), then this is the method you should use!

Parameters

url (str) – URL to get data from
timeout (int, optional) – Timeout value, uses default value if None
heads – Extra headers to include with our defaults

Returns

HTTPResponse object containing response from server

Return type

HTTPResponse

make_meta() → dict¶

Gets and returns the metadata on the last made request.

This is a good way to integrate connection stats into your CurseInstances!

The meta information is structured like this:

headers - A list of (header, value) tuples

version - HTTP Protocol version used by server

url - URL of the resource retrieved

status - Status code returned by server

reason - Reason phase returned by server

These values are returned in dictionary format.

Returns: Dictionary of metadata
Return type: dict

url_build(path: str) → str¶

Builds and returns a URL using the given path.

We combine the hostname of this protocol instance, and the given path to generate a valid url.

Parameters: path (str) – Path to append onto the end of the hostname
Returns: New URL to use
Return type: str

Formatters¶

Formatters for use with CurseDescriptions.

We offer methods for normalizing and formatting descriptions, which are in HTML.

This can be as simple as striping HTML markups, or as in-depth as loading said information into a custom class.

class cursepy.formatters.BSFormatter(parser='html.parser')¶

Loads the data into the Beautiful Soup parser for further processing.

The user can specify the parser to use. We use python’s built in HTML parser by default, although another can be selected using class parameters.

format(data: str) → Any¶

Sends the given data to the Beautiful Soup parser. We use the selected parser.

Parameters: data (str) – HTML Data to parse
Returns: BeautifulSoup object
Return type: Any

class cursepy.formatters.BaseFormat¶

BaseFormat - Base class all formatters must inherit!

We define some useful functionality for all formatters to implement. A ‘formatter’ is something that changes HTML content into something else. What the content gets converted to is up to the formatter!

format(data: str) → Any¶

Formats the given string data.

This is the entry point for the formatter! If formatting is enabled, then this method will be called with the given string to be formatted.

Parameters: data (str) – Data to be formatted
Returns: Formatted data, whatever that may be
Return type: Any
Raises: NotImplementedError: Must be overridden in child class!

class cursepy.formatters.NullFormatter¶

NullFormatter - As the name implies, does nothing!

We simply return the data that we were provided with.

format(data: str) → str¶

Returns the given data

Parameters: data (str) – Data to format
Returns: Given data
Return type: str

class cursepy.formatters.StripHTML¶

Strips all HTML tags and metadata using regular expressions.

This is not a foolproof operation, and this could easily fail in many ways!

format(data: str) → str¶

Strips the given data of all HTML tags and metadata.

Parameters: data (str) – Data to format
Returns: Formatted string data
Return type: str

Search Objects¶

Search objects for representing search parameters.

We also provide methods for converting these values into something handlers can understand.

class cursepy.classes.search.SearchParam(gameId: Optional[int] = None, rootCategoryId: Optional[int] = None, categoryId: Optional[int] = None, gameVersion: Optional[str] = None, searchFilter: Optional[str] = None, sortField: Optional[int] = None, sortOrder: Optional[str] = None, modLoaderType: Optional[int] = None, gameVersionTypeId: Optional[int] = None, slug: Optional[str] = None, index: int = 0, pageSize: int = 20)¶

SearchParam - Object that contains various parameters for searching.

This object is used for both addon searching, and file sorting. It is up to the handler receiving this object to use and interpret these values! The handler can ignore any values they see fit.

We define the following values:

gameId - ID of the game to search addons for

rootCategoryId - Filter by section ID

categoryId - Filter by category ID

gameVersion - Filter by game version string

searchFilter - Filter by free text search, just like a search bar

sortField - Filter mods in a certain way (featured, popularity, total_downloads, ect.), use constants for defining this!

sortOrder - Order of search results (ascending or descending), use constants for defining this!

modLoaderType - Filter mods associated with a specific mod loader

gameVersionTypeId - Only show files tagged with a specific version ID

slug - Filter by slug

index - Index of the first item to include in the results

pageSize - Number of items to show in each page

asdict() → dict¶

Converts ourselves into a dictionary.

Returns: Dictionary of SearchParam values
Return type: dict

bump_page(num: int = 1)¶

Bumps the page up or down.

We add the page change to the current index using this equation:

index += num * pageSize

This will change the page in relation with the current index. For example, if you bump the page up twice, have a page size of five and an index of three, the resulting index after the operation will be 13.

You can supply a negative number to bump the page downward. If the index ends up below zero, then we will set the index to zero.

Parameters: num (int) – Number of pages to bump

set_page(num: int)¶

Changes the page we are on.

We change the index to reach the next page, we use this equation to determine this:

index = num * pageSize

This will set the index to the given page. For example, if we set the page number to two, have a page size of five, and an index of three, then the resulting index after the operation will be 10.

Parameters: page (int) – Page number to set the index to

cursepy.classes.search.url_convert(search: dict, url: str = '') → str¶

Converts the given dictionary into valid URL parameters. If the ‘base_url’ is provided, then we will append the converted values to the base_url.

Parameters

search (SearchParam) – The SearchParam to convert
url (str) – URL to build off of

Returns

Converted SearchParameter value

Return type

str

Exceptions¶

cursepy exceptions and errors

exception cursepy.errors.CurseBaseException¶

CFABaseException - Base exception all CFA exceptions will inherit!

This will NOT be raised by any CFA component! This exception can be used to identify the custom CFA exceptions.

exception cursepy.errors.HandlerNotImplemented¶

Exception raised when this handler implementation is not implemented.

Usually, this occurs when no handlers are attached to the given operation.

exception cursepy.errors.HandlerNotSupported¶

Exception raised when an operation is not supported by a handler.

For example, the CF handlers do not support getting info on a specific category. Because of this, each time that handler is called, this exception will be raised.

exception cursepy.errors.HandlerRaise¶

Exception raised when the ‘RaiseHandler’ is called.

This exception will not be raised anywhere else!

exception cursepy.errors.ProtocolMismatch¶

Exception raised when a protocol mismatch has occurred.

A ‘protocol mismatch’ is when a handler attempts to assign a protocol object that does not match the protocol object currently assigned to the handler name.

API Reference¶

Wrappers¶

Curse Instances¶

Handler Components¶

Protocol Objects¶

Formatters¶

Search Objects¶

Exceptions¶

cursepy

Navigation

Related Topics