API Reference¶

Client¶

class asyncurban.urbandictionary.UrbanDictionary(loop=None, session=None)¶

A client which fetches word info from the UrbanDictionary API.

API_URL¶: str – The base URL for all search requests.

RANDOM_URL¶: str – The base URL for random word requests.

Parameters:	loop (`asyncio.AbstractEventLoop`, optional) – The event loop in which the client runs. If one isn’t provided, a loop is created. session (`aiohttp.ClientSession`, optional) – The session which makes all calls to the API. If one isn’t provided, a session is created.

coroutine get_word(self, term)¶

Gets the first matching word available.

Parameters:	term (`str`) – The word to be defined.
Return type:	`Word`
Returns:	The closest matching `Word` from UrbanDictionary.
Raises:	`UrbanConnectionError` – If the response status isn’t `200`. `WordNotFoundError` – If the response doesn’t contain data (i.e. no word found).

coroutine search(self, term, limit=3)¶

Performs a search for a term and returns a list of possible matching Word objects.

Parameters:	term (`str`) – The term to be defined. limit (optional) – Max amount of results returned. Defaults to 3.

Note

The API will relay a fixed number of words and definitions, so limit can be arbitrarily high if needed or wanted.

Return type:	`List`[`Word`]
Returns:	A list of `Word` objects of up to the specified length.
Raises:	`UrbanConnectionError` – If the response status isn’t `200`. `WordNotFoundError` – If the response doesn’t contain data (i.e. no word found).

coroutine get_random(self)¶

Gets a random word.

Return type:	`Word`
Returns:	A random `Word`.
Raises:	`UrbanConnectionError` – If the response status isn’t `200`.

coroutine get_word_raw(self, term)¶

Gets the raw json response for a word.

Parameters:	term (`str`) – The word to be defined.
Return type:	`dict`
Returns:	The JSON response from the UrbanDictionary API for `term`.
Raises:	`UrbanConnectionError` – If the response status isn’t `200`. `WordNotFoundError` – If the response doesn’t contain data (i.e. no word found).

coroutine search_raw(self, term, limit=3)¶

Performs a search for a term and returns the raw response.

Parameters:	term (`str`) – The term to be defined. limit (`int`) – The maximum amount of results you’d like. Defaults to 3.
Return type:	`List`[`dict`]
Returns:	A list of `dict`s which contain word information.

coroutine get_random_raw(self)¶

Gets a random word in raw json format.

Return type:	`dict`
Returns:	The json representation of a random word as a `dict`.
Raises:	`UrbanConnectionError` – If the response status isn’t `200`.

coroutine close(self)¶

Closes the UrbanDictionary client.

Return type:	None

Return Data¶

class asyncurban.word.Word(urban_dict)¶

A data class representing a word from the UrbanDictionary API

Available operations¶
Operation	Result
`x == y`	Checks if two Words are equal
`x != y`	Checks if two Words are not equal
`str(x)`	Returns the string representation of a Word

author¶: str – The author of the defintion contained in the object.

current_vote¶: str – An inexplicably empty string as far as I can tell, but included in the API response nonetheless.

defid¶: int – The UrbanDictionary definition ID.

definition¶: str – The definition of the word.

example¶: str – User created examples of the word. Typically used in a sentence (or a few).

permalink¶: str – The link to the definition of the word.

votes¶

Dict[str, int] – A dict containing both the upvotes and downvotes for this word and definition pair.

# Example structure
{
    'up': 400,
    'down': 20
}

word¶: str – The actual word.

Exceptions¶

exception asyncurban.errors.UrbanException¶: Base exception for the rest.

exception asyncurban.errors.WordNotFoundError(word)¶

Raised when the UrbanDictionary API does not return results for a word.

message¶: str – A message which is displayed indicating the error and which word was not found.

Parameters:	word (str) – The word which was not found (user input).

exception asyncurban.errors.UrbanConnectionError(http_status)¶

Raised when the UrbanDictionary API raises a status != 200 (success).

message¶: str – A message which is displayed indicating the error and response status.

Parameters:	http_status (int) – The status of the request which failed.