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 dicts 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).

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.