epicure

epicure is a collection of useful python methods and utils with no dependencies other than the Python standard library. Never write the same little utils again!

json

epicure.file_handling.read_json(file_path)

Read a JSON file and return its content as a dictionary.

Parameters:

file_path (str) – The path to the JSON file.

Returns:

The content of the JSON file as a dictionary.

Return type:

dict

Raises:

FileNotFoundError: If the file is not found.

Raises:

PermissionError: If read permission is denied.

Raises:

IsADirectoryError: If file_path is a directory.

Raises:

JSONDecodeError: If the file is not a valid JSON file.

Examples:
>>> users = read_json("users.json")
>>> users
{
    "users": [
        {
            "id": 1,
            "name": "John Doe",
            "email": "
        },
        {
            "id": 2,
            "name": "Jane Doe",
            "email": "
        }
    ]
}

>>> read_json("invalid/path/to/file/users.json")
FileNotFoundError: [Errno 2]
No such file or directory: 'invalid/path/to/file/users.json'
epicure.file_handling.write_json(file_path, data)

Write a dictionary to a JSON file.

Parameters:

  • file_path (str) – The path to the JSON file.

  • data (dict) – The dictionary to write to the file.

Returns:

True if the file was written successfully.

Return type:

bool

Raises:

FileNotFoundError: If the directory doesn’t exist

Raises:

PermissionError: If write permission is denied

Raises:

IsADirectoryError: If file_path is a directory

Examples:
>>> users = {
...     "users": [
...         {
...             "id": 1,
...             "name": "John Doe",
...             "email": "
...         },
...         {
...             "id": 2,
...             "name": "Jane Doe",
...             "email": "
...         }
...     ]
... }
>>> write_json("users.json", users)
# The content of the file "users.json" will be:
{
    "users": [
        {
            "id": 1,
            "name": "John Doe",
            "email": "
        },
        {
            "id": 2,
            "name": "Jane Doe",
            "email": "
        }
    ]
}

>>> write_json("invalid/path/to/file/users.json", users)
FileNotFoundError: [Errno 2]
No such file or directory: 'invalid/path/to/file/users.json'

input

epicure.input.ask_yes_no_question(prompt, default='yes', case_sensitive=False, prompt_fg_color=None, prompt_bg_color=None, error_message="Please respond with 'yes' or 'no' (or 'y' or 'n').")

Ask the user a yes/no question.

Parameters:

  • prompt (str) – The question to ask the user.

  • default (str) – The default answer if the user just presses Enter.

  • case_sensitive (bool) – Whether the response should be case-sensitive.

  • prompt_fg_color (str) – The foreground color of the prompt text.

  • prompt_bg_color (str) – The background color of the prompt text.

  • error_message (str) – The message to display if the user enters an invalid response.

Returns:

‘True’ if the user answers ‘yes’, ‘False’ if the user answers ‘no’.

Return type:

bool

Raises:

ValueError: If the default parameter is neither “yes” nor “no”.

Examples:
>>> result = ask_yes_no_question("Do you want to proceed?")
Do you want to proceed? [Y/n]: yes
>>> print(result)
True

>>> result = ask_yes_no_question("Continue?", default="no")
Continue? [y/N]: n
>>> print(result)
False

>>> result = ask_yes_no_question("Continue?", case_sensitive=True)
Continue? [Y/n]: Y
>>> print(result)
True

>>> result = ask_yes_no_question("Continue?", default="maybe")
Traceback (most recent call last):
...
ValueError: Invalid default answer. Must be 'yes' or 'no'.

>>> result = ask_yes_no_question("Continue?", error_message="Invalid response.")
Continue? [Y/n]: maybe
Invalid response.
Continue? [Y/n]:
epicure.input.multi_choice_question(prompt, choices, prompt_fg_color=None, prompt_bg_color=None)

Ask the user to choose multiple options from a list of choices.

Parameters:

  • prompt (str) – The question to ask the user.

  • choices (list) – The list of choices to present to the user.

  • prompt_fg_color (str) – The foreground color of the prompt text.

  • prompt_bg_color (str) – The background color of the prompt text.

Returns:

The list of chosen options.

Return type:

list

Examples:
>>> result = multi_choice_question_interactive(
...     "Choose your favorite colors:",
...     ["red", "green", "blue"]
... )
Choose your favorite colors:
1. red
2. green
3. blue
Enter the number of your choice (or press Enter to finish): 2
1. red
2. green [x]
3. blue
Enter the number of your choice (or press Enter to finish): 3
1. red
2. green [x]
3. blue [x]
Enter the number of your choice (or press Enter to finish):
>>> print(result)
["green", "blue"]

>>> result = multi_choice_question_interactive(
...     "Choose your favorite colors:",
...     ["red", "green", "blue"]
... )
Choose your favorite colors:
1. red
2. green
3. blue
Enter the number of your choice (or press Enter to finish): 4
Invalid choice.
Please enter a number corresponding to one of the options.
Enter the number of your choice (or press Enter to finish): 2
1. red
2. green [x]
3. blue
Enter the number of your choice (or press Enter to finish): 2
1. red
2. green [x]
3. blue [x]
Enter the number of your choice (or press Enter to finish):
epicure.input.multi_choice_question_interactive(prompt, choices, prompt_fg_color='white', prompt_bg_color='black', option_fg_color='white', option_bg_color='black', hover_fg_color='black', hover_bg_color='white', selected_indicator_fg_color='white', selected_indicator_bg_color='black')

Ask the user to choose multiple options from a list of choices using an interactive menu.

Parameters:

Parameters:

  • prompt (str) – The question to ask the user.

  • choices (list) – The list of choices to present to the user.

  • prompt_fg_color (str) – The foreground color of the prompt text.

  • prompt_bg_color (str) – The background color of the prompt text.

  • option_fg_color (str) – The foreground color of the options.

  • option_bg_color (str) – The background color of the options.

  • hover_fg_color (str) – The foreground color of the hovered option.

  • hover_bg_color (str) – The background color of the hovered option.

  • selected_indicator_fg_color (str) – The foreground color of the selected options.

  • selected_indicator_bg_color (str) – The background color of the selected options.

Returns:

The list of chosen options.

Return type:

list

Examples:
>>> result = multi_choice_question_interactive(
                "Choose your favorite colors:", ["red", "green", "blue"]
             )
Please choose one or more of the following options
(use arrows to navigate, space to select, Enter to finish):
  > red
    green
    blue
Press Enter to finish.
>>> print(result)
["red"]

>>> result = multi_choice_question_interactive(
                "Choose your favorite colors:", ["red", "green", "blue"]
             )
Please choose one or more of the following options
(use arrows to navigate, space to select, Enter to finish):
    red
  > green
    blue
Press Enter to finish.
>>> print(result)
["green"]

>>> result = multi_choice_question_interactive(
                "Choose your favorite colors:", ["red", "green", "blue"]
             )
Please choose one or more of the following options
(use arrows to navigate, space to select, Enter to finish):
    red
    green
  > blue
Press Enter to finish.
>>> print(result)
["blue"]

>>> result = multi_choice_question_interactive(
                "Choose your favorite colors:", ["red", "green", "blue"]
             )
Please choose one or more of the following options
(use arrows to navigate, space to select, Enter to finish):
    red
    green
    blue
Press Enter to finish.
>>> print(result)
[]
epicure.input.simple_choice_question(prompt, choices, prompt_fg_color=None, prompt_bg_color=None)

Ask the user to choose one option from a list of choices.

Parameters:

  • prompt (str) – The question to ask the user.

  • choices (list) – The list of choices to present to the user.

  • prompt_fg_color (str) – The foreground color of the prompt text.

  • prompt_bg_color (str) – The background color of the prompt text.

Returns:

The chosen option.

Return type:

str

Examples:
>>> result = simple_choice_question("Choose a color:", ["red", "green", "blue"])
Choose a color:
1. red
2. green
3. blue
Enter the number of your choice: 2
>>> print(result)
"green"

>>> result = simple_choice_question("Choose a color:", ["red", "green", "blue"])
Choose a color:
1. red
2. green
3. blue
Enter the number of your choice: 4
Invalid choice. Please enter a number corresponding to one of the options.
Enter the number of your choice: 1
>>> print(result)
"red"

output

epicure.output.colored_print(text, fg_color=None, bg_color=None, end='\\n')

Print text in the specified foreground and background colors.

Parameters:

  • text (str) – The text to print.

  • fg_color (str) – The foreground color to print the text in.

  • bg_color (str) – The background color to print the text in.

  • end (str) – The string to print at the end of the text.

Returns:

None

Return type:

None

Examples:
>>> colored_print("Hello, world!", fg_color="red", bg_color="black")
Hello, world!  # In red text on a black background.

>>> colored_print("Hello, world!", fg_color="red")
Hello, world!  # In red text, default background.