fortune-teller2607555 0.1.1
A fun Python package that generates random fortunes with a date.
License: MIT
Requires Python: >=3.9

# fortune_package
![CI Status](https://github.com/software-students-spring2025/3-python-package-parallax/actions/workflows/build.yaml/badge.svg)

## Description
A small Python package to make your day just a bit brighter while coding! Test your luck and explore the many fortunes we've included. If you're lucky (or unlucky), the fortune you receive might just come true.

## PyPI Link
[fortune-package2607555](https://pypi.org/project/fortune-teller2607555/)

## Installation & Setup

### Installing Dependencies & Setting Up a Virtual Environment
To install the required dependencies and set up a virtual environment:

1. **Install pipenv** (if you haven’t already):
    ```bash
    pip install pipenv
    ```
2. **Create and enter a virtual environment**, then install dependencies:
    ```bash
    pipenv install
    pipenv shell
    ```
3. **Install our fortune-teller package**:
    ```bash
    pip install fortune-teller2607555==0.1.1
    ```

## Overview of Provided Functions

1. **`cs_fortune(category: str)`**  
   - Returns a computer science-themed fortune from one of these categories: `tech`, `startup`, `open source`, `ai`, or `career`. 
   - If the category is invalid, it returns an `"Oops:"` error message.
   ```python
   from fortune_teller.cs_fortune import cs_fortune
   fortune = cs_fortune("tech")
   print(fortune)
   ```
2. **`mood_fortune(mood: str)`**
    - Returns a fortune based on your mood:
    `positive`, `funny`, `cursed`, `motivational`).
    - If the mood is invalid, it returns an `"Oops:"` error message.
    ```python
    from fortune_teller.mood_fortune import mood_fortune
    fortune = mood_fortune("funny")
    print(fortune)
    ```
3. **`fortune_story(name: str)`**
    - Returns a personalized fortune story that includes the name you provide.
    - If the name is invalid (empty), it returns an error message.
    ```python
    from fortune_teller.fortune_stories import fortune_story
    story = fortune_story("Alice")
    print(story)
    ```
4. **`rand_date_time(current_date_str: str, fortune: str)`**
    - Combines a given fortune message with a random future date (up to December 31, 2060).
    - The `fortune` parameter must come from one of the other functions: `cs_fortune`, `mood_fortune`, or `fortune_story`).
    - If the user-supplied date is beyond December 31, 2060 or invalid, it returns an error message.
    ```python
    from fortune_teller.date_time import rand_date_time
    from fortune_teller.cs_fortune import cs_fortune

    my_cs_fortune = cs_fortune("tech")
    dated_fortune = rand_date_time("2025-01-01", my_cs_fortune)
    print(dated_fortune)
    ```

## Usage Examples

1. **Direct Function Import**
If you simply want to call a fortune function, `cs_fortune`, for instance:
```python
from fortune_teller.cs_fortune import cs_fortune

fortune = cs_fortune("ai")
print("AI Fortune:", fortune)
```
2. **Try Our Interactive CLI**
We include a `get_started.py` script that lets you interactively pick any fortune type from the command line, combine it with a random future date, and see the final result printed with fun ASCII art. To try it:
- Navigate to your project folder
- Run:
```bash
python -m fortune_teller.get_started
```
- Follow the menu prompts to select your fortune type: `mood_fortune`, `fortune_story`, or `cs_fortune`) or quit. You’ll see a fun ASCII “cookie” and your fortune each time!

For a complete example of all functions, check out [get_started.py](https://github.com/software-students-spring2025/3-python-package-parallax/blob/main/fortune_teller/get_started.py).

## Contribution Guidelines
We welcome contributions! If you'd like to contribute:
1. Fork the repository.
2. Create a new branch for your feature or fix.
3. Ensure your changes integrate well with existing tests and add new tests if necessary.
4. Submit a pull request for review.

### Code Testing
Run tests locally before submitting your new code:

```sh
pipenv install --dev pytest
pipenv run python -m pytest tests/
```

## The Team
- [brian105](https://github.com/brian105)
- [Jibril1010](https://github.com/Jibril1010)
- [polinapianina](https://github.com/polinapianina)
- [naseem-student](https://github.com/naseem-student)