riddle-handler 1.0.4

A Python package for managing and interacting with a JSON-based riddle library.

Riddle Handler

Overview

Riddle Handler is a lighthearted Python package designed to bring a bit of joy and levity to developers' lives. It provides an interactive experience where users can generate riddles of varying difficulties and topics, check answers, submit new riddles, and receive hints. The package is built following rigorous software engineering practices, ensuring quality and reliability.

PyPI Link

Riddle Handler

Installation

Install the package via pip:

pip install riddle-handler==1.0.3

Usage

Importing the Package

import riddle_handler

Functions and Examples

Function 1: generate_riddle(difficulty: int) -> str

Generates a random riddle based on the specified difficulty level.

• Parameters:

  • difficulty (int): The difficulty level of the riddle (1 to 4).

• Returns:

  • A string containing the riddle's question.

• Example:

  import riddle_handler
  
  # Generate a riddle of difficulty level 2
  riddle = riddle_handler.generate_riddle(2)
  print(f"Here's your riddle: {riddle}")
  

Function 2: check_answer(riddle_id: int, answer: str) -> str

Checks if the provided answer to the riddle is correct.

• Parameters:

  • riddle_id (int): The ID of the riddle.
  • answer (str): The user's answer to the riddle.

• Returns:

  • A string indicating whether the answer is correct or incorrect.

• Example:

  import riddle_handler
  
  # Check the answer to a riddle with ID 5
  result = riddle_handler.check_answer(5, 'shadow')
  print(result)  # Outputs: "Correct answer!" or "Incorrect answer. Try again!"
  

Function 3: submit_riddle(riddle: dict) -> str

Allows users to submit their own riddles to the library.

• Parameters:

  • riddle (dict): A dictionary containing the riddle's details.

    • question (str): The riddle's question.
    • answer (list): A list of acceptable answers.
    • hint (str): A hint for the riddle.
    • difficulty (int): Difficulty level (1 to 4).
    • topic (str): The topic of the riddle.

• Returns:

  • A string indicating success or an error message.

• Example:

  import riddle_handler
  
  # Define your custom riddle
  my_riddle = {
        "question": "I can move, yet I stay in one place; People use me to send messages, but I'm nowhere to be seen; Anytime, anywhere, you can call for me, and I'll always be there. What am I?",
        "answer": ["sound"],
        "hint": "You can hear me but cannot see me.",
        "difficulty": 3,
        "topic": "Communication"
  }
  
  # Submit the riddle
  response = riddle_handler.submit_riddle(my_riddle)
  print(response)  # Outputs: "Riddle submitted successfully!"
  

Function 4: provide_hint(riddle_id: int) -> str

Provides a hint for the specified riddle.

• Parameters:

  • riddle_id (int): The ID of the riddle.

• Returns:

  • A string containing the hint or an error message.

• Example:

  import riddle_handler
  
  # Get a hint for a riddle
  hint = riddle_handler.provide_hint(5)
  print(hint)  # Outputs the hint for the riddle
  

For more examples, check out this example program.

Contributing

Setting Up the Development Environment

1. Clone the repository:

   git clone https://github.com/software-students-fall2024/3-python-package-codecrafter
   

2. Install pipenv:

If you haven’t installed pipenv yet, use the following command:

pip install pipenv

3. Set Up the Virtual Environment:

To create a virtual environment and install dependencies using the Pipfile, run:

pipenv install

This command will read the Pipfile and create a virtual environment with all the specified dependencies.

If you only want to create the environment without installing dependencies, you can use:

pipenv install --ignore-pipfile

4. Activate the Virtual Environment:

To activate the virtual environment, use:

pipenv shell

This command works on both Mac and Windows, as pipenv will automatically locate and activate the correct environment.

5. Install Additional Dependencies(If Needed):

If you need to add more dependencies later, you can use the following commands:

• For production dependencies:

  pipenv install <package-name>
  

• For development dependencies (e.g., testing or debugging tools):

  pipenv install --dev <package-name>
  

6. Exit the Virtual Environment:

To exit the virtual environment, simply type:

exit

Or press Ctrl + D.

7. Remove the Virtual Environmen:

If you need to delete the virtual environment, use:

pipenv --rm

This will remove the virtual environment associated with the Pipfile.

Building and Testing

• Run Tests:

  We use pytest for testing.

  pytest
  

• Build Package:

  Use build to create the package artifacts.

  For Mac:

  python3 -m build
  

  For Windows:

  python -m build
  

• Upload to PyPI (For maintainers):

  Use twine to upload the package.

  twine upload dist/*
  

  Note that API key should only be acquired by contacting administrators

Git Workflow

All code changes must be done in feature branches and not directly in the main branch.

To merge code from a feature branch into main:

1. Create a pull request from the feature branch to main.
2. Request a code review from a team member.
3. Review and approve the code after ensuring all tests pass.
4. Merge the pull request into main.
5. Delete the feature branch.

Note: Regularly merge feature branches to avoid merge conflicts.

Contributors

• Alex
• Haoyi
• Keven
• Nicole

Instructions for Running the Project

For Developers

1. Ensure Python 3.11 or higher is installed on your system.

2. Clone the repository and set up the environment as described in the Contributing section.

3. Run the example program:

For Mac:

python3 example_program.py

For Windows:

python example_program.py

For Users

1. Install the package via pip:

   install riddle-handler==1.0.3
   

2. Use the package in your Python scripts as shown in the Usage examples.

Configuration and Setup

Environment Variables

No environment variables are required for basic usage.

Importing Starter Data

The package uses a riddleLibrary.json file to store riddles. Ensure that this file is in the root directory of your project. You can use our library from this link or you can build your own by creating a riddleLibrary.json file.

Update Log

v1.0.3 Bug Fix: Resolved an issue where the package has no attribute.

v1.0.2 Bug Fix: Resolved an issue where the package appeared empty after installation. Documentation: Updated README with clearer instructions and added installation and usage details specific to Windows. Compatibility: Added a method for Windows users to ensure compatibility.

v1.0.1 Updated Package Structure: Reorganized the package structure to follow best practices for module organization, enhancing maintainability and usability. Bug Fixes: Resolved several issues related to imports and file path references, improving the stability and reliability of the package.

v1.0.0 Initial Release: Launched the riddle_handler package, offering core functionalities for managing and interacting with a JSON-based riddle library. This includes generating riddles, checking answers, providing hints, and submitting new riddles.