# utils

`randomstuff.utils` is a sub module that contains some useful functions to aid with the API interactions.

{% hint style="info" %}
All functions are library specific and are not provided or suggested by API.
{% endhint %}

{% hint style="info" %}
In order to use this module, You have to import it explicitly like this:

```python
from randomstuff import utils
# or
import randomstuff.utils
```

{% endhint %}

## Functions

### `generate_uid`

Generates a complex and safe to use unique ID. This is very useful when you need a unique key for AI response endpoint.

{% tabs %}
{% tab title="Arguments" %}

#### `level`(Optional)

This determines the number of chars in the key. Defaults to `30` by default.

**Type:** [`int`](https://www.w3schools.com/python/python_strings.asp)
{% endtab %}

{% tab title="Returns" %}
[`str`](https://www.w3schools.com/python/python_strings.asp) : The generated key.
{% endtab %}
{% endtabs %}

### `format_joke`

A simple method to turn a two-part joke into a string. It simply formats two-part joke in provided format, By default is: `'{setup}... {delivery}'`

{% tabs %}
{% tab title="Arguments" %}

#### `format_to` (Optional)

This is the format. In that format, `{setup}` is replaced with `setup` of the joke and `{delivery}` with `delivery` . 

For example:

```python
joke = client.get_joke()
formatted_joke = utils.format_joke(
    joke, 
    format_to='{setup}... {delivery}'
    )
print(formatted_joke.joke) # The formated joke
```

**Type:** [`str`](https://www.w3schools.com/python/python_strings.asp)

{% hint style="info" %}
If the passed joke type is single, It silently ignores it and returns the passed joke as it is. (So, this technically raises no error so you can use it for general usage without having to handle any error.)
{% endhint %}
{% endtab %}

{% tab title="Returns" %}
[`Joke` ](https://nerdguyahmad.gitbook.io/randomstuff/data-classes/joke): The new joke with `joke` attribute as the formatted joke.
{% endtab %}
{% endtabs %}

### `get_safe_joke`

A method that filters or ignores any unsafe joke. This method is made to be used in replacement to [`get_joke`](https://nerdguyahmad.gitbook.io/randomstuff/clients/client#get_joke) method.

{% hint style="info" %}
It ignores any joke whose `safe` attribute is `False` and fetches another joke. Here, A question is raised that won't it cause rate-limit because of calling API so many times. The answer is, No. Usually jokes are returned with `safe` attribute as `True` there is a small chance of getting an unsafe joke. This method handles that chance. So, it has hardly noticeable affect.
{% endhint %}

For example:

```python
client = randomstuff.Client(api_key="key") # Or AsyncClient 
joke = utils.get_safe_joke(client, type="any")
print(joke.safe) # Always prints `True`
print(joke.joke)
```

{% tabs %}
{% tab title="Arguments" %}

#### `client`

Your [`Client`](https://nerdguyahmad.gitbook.io/randomstuff/clients/client) or [`AsyncClient`](https://nerdguyahmad.gitbook.io/randomstuff/clients/asyncclient) instance.

**Type:** `Union[`[`Client`](https://nerdguyahmad.gitbook.io/randomstuff/clients/client)`,` [`AsyncClient`](https://nerdguyahmad.gitbook.io/randomstuff/clients/asyncclient)`]`

#### `type` (Optional)

Equivalent to [`Joke.type`](https://nerdguyahmad.gitbook.io/randomstuff/clients/client#get_joke)

**Type:** `Union[`[`Client`](https://nerdguyahmad.gitbook.io/randomstuff/clients/client)`,` [`AsyncClient`](https://nerdguyahmad.gitbook.io/randomstuff/clients/asyncclient)`]`
{% endtab %}
{% endtabs %}