emojiguessr 1.3.1

A tiny emoji guessing game

EmojiGuessr

Link to PyPI: Emojiguessr

EmojiGuessr is a Python package that turns emoji strings into quick guessing games. Pick a theme, get an emoji clue and guess the name!

Features

• Multiple Themes: Choose from 7 different themes including food, animals, movies, games, cities, feelings, and dev
• Customizable Difficulty: Adjust the number of questions, attempts per question, and matching rules
• Flexible Matching: Support for partial matches and case-sensitive/insensitive answers
• Easy CLI: Simple command-line interface with helpful flags and options

Team Members

Jason Liu

David Shen

Leon Lian

member4

member5

Installation

1. Create a pipenv-managed virtual environment and install the latest version: pipenv install -i https://test.pypi.org/simple/emojiguessr. (Note that if you've previously created a pipenv virtual environment in the same directory, you may have to delete the old one first. Find out where it is located with the pipenv --venv command.)
2. Activate the virtual environment: pipenv shell.
3. Create a Python program file that imports the package and uses it, e.g. from emojiguessr import quiz and then print(quiz.make_quiz_item()).
4. Run the program: python3 my_program_filename.py.
5. Exit the virtual environment: exit.

Try running the package directly:

1. Create and activate up the pipenv virtual environment as before.
2. Run the package directly from the command line: python3 -m emojiguessr. This should run the code in the __main__.py file.
3. Exit the virtual environment.

From Test PyPI

pipenv install -i https://test.pypi.org/simple/emojiguessr

From Source

git clone https://github.com/swe-students-fall2025/3-python-package-team_saffron.git
cd 3-python-package-team_saffron
pipenv install -e .

Usage

Basic Usage

Run the game with default settings (3 questions, food theme):

pipenv run emojiguessr

Advanced Usage

Choose a different theme:

pipenv run emojiguessr --theme animals

Customize the number of questions:

pipenv run emojiguessr -n 5

Allow multiple attempts per question:

pipenv run emojiguessr --max-attempts 3

Enable case-sensitive matching:

pipenv run emojiguessr --case-sensitive

Disable partial matches (require exact answers):

pipenv run emojiguessr --no-partial

Combine multiple options:

pipenv run emojiguessr -t movies -n 10 -a 2

Available Themes

You can list all available themes using:

pipenv run emojiguessr --list-themes

Current themes include:

• food - Pizza, sushi, burger, and more
• animals - Dog, cat, panda, lion, etc.
• movies - Famous movies represented by emojis
• games - Various types of games
• cities - World cities
• feelings - Different emotions
• dev - Programming and development concepts

Command Reference

List of flags you can add to customize the behavior of emojiguessr

Available commands:
  --num-questions, -n    : Number of questions to ask (default: 3)
  --theme, -t            : Emoji theme to use (default: food)
  --case-sensitive       : Make answers case-sensitive (default: off)
  --no-partial           : Disable partial matches
  --max-attempts, -a     : Maximum number of attempts per question (default: 1)
  --list-themes, -lt     : List available themes and exit
  --list-commands, -lc   : List available commands and exit

Code Example

A short demo showcasing all features of the emojiguessr package can be found here: https://github.com/swe-students-fall2025/3-python-package-team_saffron/blob/main/src/examples/demo.py

Develop and Contribute

Local build & run (using pipenv)

1. Get pipenv installed
2. cd into the project directory
3. Install dependencies: pipenv install
4. Install the package in editable mode: pipenv install -e .
5. Run the command line interface: pipenv run emojiguessr followed by flags and configurations

Project Structure

.github/
  workflows/
    build.yaml
    deliver.yaml
    event-logger.yml
    Pipfile
    Pipfile.lock
    requirements.txt
  note.txt
src/
  emojiguessr/
    __init__.py
    __main__.py
    data.py
    quiz.py
    score.py
tests/
  __init__.py
  test_data.py
examples/
  demo.py
pyproject.toml
Pipfile
Pipfile.lock
LICENSE
README.md
instructions.md
.gitignore

Testing

Testing is implemented with pytest and runs automatically on every pull request. If you wish to run tests locally anytime, simply run

pytest -v

if you have pytest installed through pipenv, do

pipenv run pytest -v

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests to ensure everything works
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.