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: Returns: The closest matching
Word
from UrbanDictionary.Raises: UrbanConnectionError
– If the response status isn’t200
.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: Returns: A list of
Word
objects of up to the specified length.Raises: UrbanConnectionError
– If the response status isn’t200
.WordNotFoundError
– If the response doesn’t contain data (i.e. no word found).
- term (
-
coroutine
get_random
(self)¶ Gets a random word.
Return type: Word
Returns: A random Word
.Raises: UrbanConnectionError
– If the response status isn’t200
.
-
coroutine
get_word_raw
(self, term)¶ Gets the raw json response for a word.
Parameters: term (
str
) – The word to be defined.Return type: Returns: The JSON response from the UrbanDictionary API for
term
.Raises: UrbanConnectionError
– If the response status isn’t200
.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: Return type: 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’t200
.
-
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
¶ 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 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.