study-pet 0.1.0
A Python package to gamify your study sessions by raising a virtual ball python
License: MIT
Requires Python: >=3.10
Keywords: study, productivity, gamification, pet, cli, ball-python

[![CI](https://github.com/swe-students-fall2025/3-python-package-team_cascade/actions/workflows/ci.yml/badge.svg?branch=pipfile-experiment)](https://github.com/swe-students-fall2025/3-python-package-team_cascade/actions/workflows/ci.yml)

# 🐍 SsstudyPet

**SsstudyPet** is a Python package that provides an interactive command-line application to gamify your study sessions by letting you raise and care for a virtual ball python. The more you study, the more your snake grows! Track your study time, earn coins, feed your python, and watch it level up as you build consistent study habits.

## Features

- **📚 Study Session Tracking**: Start and end study sessions with automatic time tracking
- **✅ Task-Based Rewards**: Set tasks at the start of each session and earn 75 coins per completed task
- **🐍 Virtual Ball Python**: Your snake levels up based on total study hours (1 level per 5 hours)
- **🌡️ Mood System**: Keep your python happy by logging in regularly and feeding it
- **💰 Earn Coins**: Complete tasks to earn coins that can be used to purchase food for your python
- **🐭 Feed Your Python**: Choose from various prey (mouse, rat, quail, rabbit, cricket) to boost mood
- **📈 Progress Tracking**: Monitor your study streaks, total study time, and python status
- **🔄 Auto-save**: Sessions automatically save on exit or interruption
- **🎮 Interactive Menu**: Easy-to-use CLI menu for all features

## Team Members

- [Catherine Yu](https://github.com/catherineyu2014)
- [Leo Fu](https://github.com/LeoFYH)
- [JunHao Chen](https://github.com/JunHaoChen16)
- [Majo Salgado](https://github.com/mariajsalgadoq)
- [Zeba Shafi](https://github.com/Zeba-Shafi)

## Installation

Install from PyPI:

```bash
pip install ssstudy-pet
```

Or install from source:

```bash
git clone https://github.com/swe-students-fall2025/3-python-package-team_cascade.git
cd team_cascade
pipenv install --dev
```

## Examples

Want to see SsstudyPet in action? We provide **two complete demo options**:

### 📓 Option 1: Interactive Jupyter Notebook

Perfect for visual learners and live demonstrations!

**Location:** [`notebook_demo.ipynb`](notebook_demo.ipynb)

**Features:**
- Step-by-step walkthrough of all features
- Live code examples you can run and modify
- Mock input functions for smooth demo flow
- Complete demonstration of study sessions, feeding, customization, and more

**To run:**
```bash
# Install Jupyter if you haven't already
pip install jupyter

# Open the demo notebook
jupyter notebook notebook_demo.ipynb
```

### 🐍 Option 2: Python Script Demo

Complete Python program you can run from the command line!

**Location:** [`full_program_demo.py`](full_program_demo.py)

**Features:**
- Full demonstration of all SsstudyPet functions
- Shows study sessions, task tracking, rewards, feeding, and customization
- Easy to read and modify for your own use
- No Jupyter required - just run with Python

**To run:**
```bash
python full_program_demo.py
```

### 💻 Using SsstudyPet in Your Code

You can import and use SsstudyPet's functions in your own Python programs. Here's documentation for all available functions:

### Study Session Management

```python
from study_pet.tracker import start_session, end_session, show_encouragement

# Start a study session with task planning
start_session()
# Prompts: "How many tasks do you plan to complete this session?"
# Sets session_tasks_planned and records start time
# Automatically shows an encouragement message to motivate you

# End a study session with task completion
end_session()
# Prompts: "How many tasks did you complete this session?"
# Rewards 75 coins per completed task
# Updates total study time and saves progress
# Automatically shows a congratulatory encouragement message

# Get encouragement during an active study session
show_encouragement()
# Shows elapsed study time and a motivational message
# Only works during an active session (after start_session, before end_session)
# Example output:
#   ⏱️  You've been studying for 15.3 minutes!
#   🐍 Monty says: "Sssstay focused! You're on a roll!"
```

### Pet Care Functions

```python
from study_pet.pet import feed_pet, rename_pet, set_morph, get_encouragement

# Feed your ball python (costs coins, boosts mood)
feed_pet("mouse")   # Costs 50 coins, +10 mood
# ... (rest of feed_pet examples) ...

# Rename your ball python
rename_pet("Slithers")

# Set your ball python's morph (color pattern)
set_morph("Banana")
# ... (rest of set_morph examples) ...

# Get an encouraging phrase from your pet
encouragement = get_encouragement()
print(encouragement)  # Outputs: 🐍 Guido says: "Sssstay focused!"

# Get your ball python's current status
status = get_status()
print(status)  # Returns formatted status string
```

### Status and Data Functions

```python
from study_pet.pet import get_status
from study_pet.data_manager import load_state, save_state, reset_data

# Get your ball python's current status
status = get_status()
print(status)  # Returns formatted status string with all pet info

# Load current saved data
state = load_state()
print(f"Level: {state['level']}")
print(f"Coins: {state['coins']}")
print(f"Morph: {state['morph']}")

# Manually save data (normally done automatically)
save_state(state)

# Reset all data (use with caution!)
reset_data()
```

### Example Programs

We provide two example options:

1. **📓 Interactive Demo Notebook** ([`notebook_demo.ipynb`](notebook_demo.ipynb)) - Jupyter notebook with step-by-step demonstrations
2. **🐍 Python Script** ([`full_program_demo.py`](https://github.com/swe-students-fall2025/3-python-package-team_cascade/blob/main/full_program_demo.py)) - Complete Python program showcasing all functions

```python
# full_program_demo.py - Complete demonstration of SsstudyPet
from study_pet.tracker import start_session, end_session
from study_pet.pet import feed_pet, rename_pet, set_morph, get_status, get_encouragement
from study_pet.data_manager import load_state

# Start a study session
print("Starting study session...")
start_session()  # Will prompt for task count

# Do some studying... (simulated)
print("\n📚 Studying...\n")

# End the session and earn rewards
end_session()  # Will prompt for completed tasks

# Get encouragement
print("\n" + get_encouragement())

# Check your ball python's status
print("\n" + get_status())

# Name your python
rename_pet("Monty")
print("\n🐍 Your ball python is now named Monty!")

# Set a morph
set_morph("Banana")
print("\n✨ Your python is now a beautiful Banana morph!")

# Feed your python
feed_pet("mouse")
print("\n🐭 Fed your python a mouse!")

# Check final status
print("\n" + get_status())

# Access raw data
state = load_state()
print(f"\n💰 Total coins: {state['coins']}")
print(f"⏱️  Total study time: {state['total_minutes']} minutes")
```

## Command Line Usage

### Quick Start Commands

```bash
# Start a study session (automatic encouragement!)
study-pet start

# Get encouragement during your session
study-pet encourage

# End your session (automatic congratulation!)
study-pet end

# Check your pet's status
study-pet status

# Feed your pet
study-pet feed mouse

# Interactive menu
study-pet menu
```

### All Available Commands

- `study-pet start` - Start a study session with task planning
- `study-pet end` - End session and get rewards
- `study-pet status` - Check your ball python's status
- `study-pet feed [food]` - Feed your python (mouse, rat, quail, rabbit, cricket)
- `study-pet rename [name]` - Rename your ball python
- `study-pet morph [type]` - Change your python's morph/color pattern
- `study-pet encourage` - Get an encouraging message (during active session)
- `study-pet menu` - Interactive menu interface

## Contributing to SsstudyPet

Want to help make SsstudyPet better? Here's how to set up your development environment:

### Prerequisites

- Python 3.10 or higher (Python 3.13 recommended)
- pipenv for dependency management

### Setup Instructions

1. **Clone the repository**
   ```bash
   git clone https://github.com/swe-students-fall2025/3-python-package-team_cascade.git
   cd 3-python-package-team_cascade-4
   ```

2. **Install pipenv** (if not already installed)
   ```bash
   pip install pipenv
   ```

3. **Set up the virtual environment and install dependencies**
   ```bash
   # Install all dependencies including dev dependencies
   pipenv install --dev
   
   # This installs:
   # - pytest (for testing)
   # - build (for building the package)
   # - twine (for publishing to PyPI)
   ```

4. **Activate the virtual environment**
   ```bash
   pipenv shell
   ```

5. **Run the tests**
   ```bash
   # Run all tests
   pytest tests/ -v
   
   # Run tests with coverage
   pytest tests/ --cov=study_pet --cov-report=html
   
   # Run specific test file
   pytest tests/test_actions.py -v
   ```

6. **Build the package**
   ```bash
   # Build distribution files
   python -m build
   
   # This creates dist/ directory with:
   # - .tar.gz (source distribution)
   # - .whl (wheel distribution)
   ```

7. **Test the package locally**
   ```bash
   # Install in editable mode for development
   pip install -e .
   
   # Run the CLI
   study-pet menu
   ```

### Development Workflow

1. Create a new feature branch:
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. Make your changes and test thoroughly:
   ```bash
   pytest tests/ -v
   ```

3. Commit your changes:
   ```bash
   git add .
   git commit -m "Add your descriptive commit message"
   ```

4. Push to GitHub and create a pull request:
   ```bash
   git push origin feature/your-feature-name
   ```

5. Wait for CI tests to pass (GitHub Actions automatically runs tests)

### Project Structure

```
study_pet/
├── __init__.py           # Package initialization
├── __main__.py           # CLI entry point
├── data_manager.py       # Data persistence functions
├── tracker.py            # Study session tracking
└── pet/
    ├── __init__.py       # Pet module exports
    ├── core.py           # Pet status and leveling
    └── actions.py        # Pet interaction functions
tests/
├── test_actions.py       # Tests for pet actions
├── test_core.py          # Tests for pet core functions
├── test_data_manager.py  # Tests for data management
├── test_tracker.py       # Tests for session tracking
├── test_main.py          # Tests for CLI commands
└── test_morph.py         # Tests for morph system
```

### Running Specific Tests

```bash
# Test specific functionality
pytest tests/test_morph.py::test_set_morph_valid -v
pytest tests/test_tracker.py -v
pytest tests/test_actions.py::test_feed_pet -v

# Test with output
pytest tests/ -v -s

# Generate coverage report
pytest tests/ --cov=study_pet --cov-report=term-missing
```

## PyPI Package

This package is available on TestPyPI: [study-pet](https://test.pypi.org/project/study-pet/0.1.1/)