Python Package Exercise

An exercise to create a Python package, build it, test it, distribute it, and use it. See instructions for details.

🔮 Fortunes

👥 Team Members

• Yuhao Sheng (ys4689)
• Ryoma Nagano (rn2247)
• Qiyun Yin (qy765)
• Andrea Tang (xt2073)

Description

Fortunes is a delightful Python package that brings a touch of randomness and inspiration into your projects. Whether you're looking for a daily dose of wisdom, a lucky number, or the ability to send personalized fortunes via email, Fortunes has you covered.

Features

• Random Fortune Generation: Retrieve one or multiple unique fortunes along with lucky numbers.
• Email Integration: Send personalized fortunes to any email address effortlessly.
• Customizable Quotes: Get your own collection of fortunes and quotes.

📦 Installation

Install the latest version of Fortunes from PyPI using pip:

pip install fortune.package

📖 Documentation

Importing Fortunes into Your Project

To start using Fortunes in your Python code, simply import the desired functions:

from fortunes.random_fortune import get_fortune_cookie
from fortunes.get_quotes_by_author import get_quotes_by_author
from fortunes.send_email import send_fortune_email
from fortunes.getMultipleFortunes import getMultipleFortunes

# Example Usage:
fortune = get_fortune_cookie()
print(fortune)

quotes = get_quotes_by_author(quotes_dict)
print(quotes)

send_fortune_email("[email protected]", fortune)

multiple_fortunes = getMultipleFortunes(3)
for f in multiple_fortunes:
    print(f)

Function Documentation

get_fortune_cookie()

Description:
Generates a single random fortune along with a lucky number.

Usage:

from fortunes.random_fortune import get_fortune_cookie

fortune = get_fortune_cookie()
print(fortune)

Output Example:

🔮 Your Fortune: Good luck is on the way!
🍀 Your Lucky Number: 42

get_quotes_by_author(quotes_dict)

Description:
Retrieves quotes from a specified author. Users can choose to get one or multiple quotes.

Usage:

from fortunes.get_quotes_by_author import get_quotes_by_author

quotes_dict = {
    "Albert Claude": [
        "Once Ptolemy and Plato, yesterday Newton, today Einstein, and tomorrow new faiths, new beliefs, and new dimensions.",
        "When I went to the University, the medical school was the only place where one could hope to find the means to study life, its nature, its origins, and its ills.",
        "Looking back 25 years later, what I may say is that the facts have been far better than the dreams. In the long course of cell life on this earth it remained, for our age for our generation, to receive the full ownership of our inheritance.",
    ],
    "Mikhail Bakunin": [
        "The urge to destroy is also a creative urge.",
        "If God really existed, it would be necessary to abolish Him.",
        "People go to church for the same reasons they go to a tavern: to stupefy themselves, to forget their misery, to imagine themselves, for a few minutes anyway, free and happy."
    ]
}

quotes = get_quotes_by_author(quotes_dict)
print(quotes)

Output Example:

🔮 Your Fortune: The urge to destroy is also a creative urge.
🍀 Your Lucky Number: 17
~ Mikhail Bakunin

🔮 Your Fortune: If God really existed, it would be necessary to abolish Him.
🍀 Your Lucky Number: 23
~ Mikhail Bakunin

send_fortune_email(recipient_email, fortune)

Description:
Sends a fortune to the specified email address.

Usage:

from fortunes.send_email import send_fortune_email

recipient = "[email protected]"
fortune = "🔮 Your Fortune: Happiness is around the corner.\n🍀 Your Lucky Number: 12"

send_fortune_email(recipient, fortune)

Note:
Ensure that you have the necessary SMTP configurations and environment variables set up before using this function.

getMultipleFortunes(n)

Description:
Generates multiple unique fortunes based on the number specified.

Usage:

from fortunes.getMultipleFortunes import getMultipleFortunes

fortunes = getMultipleFortunes(3)
for f in fortunes:
    print(f)

Output Example:

🔮 Your Fortune: Fortune 1
🍀 Your Lucky Number: 42

🔮 Your Fortune: Fortune 2
🍀 Your Lucky Number: 88

🔮 Your Fortune: Fortune 3
🍀 Your Lucky Number: 7

📂 Example Programs

For comprehensive examples of how to use Fortunes in real-world scenarios, refer to our examples directory on GitHub.

🤝 Contributing

We welcome contributions from the community! Here's how you can get started:

🛠️ Setup Development Environment

1. Clone the Repository:

   git clone https://github.com/yourusername/fortunes.git
   cd fortunes

2. Create a Virtual Environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows, use venv\Scripts\activate

3. Install Dependencies:

   pip install --upgrade pip
   pip install -e .[dev]

   This installs the package in editable mode along with development dependencies.

4. Install requirements:

pip install -r requirements.txt

5. Run Tests:

   Ensure that all tests pass before making changes.

   pytest

Making Changes

1. Create a New Branch:

   git checkout -b feature/your-feature-name

2. Implement Your Changes:

   Make your desired changes to the codebase.

3. Run Tests:

   Ensure that your changes do not break existing functionality.

   pytest

4. Commit and Push:

   git add .
   git commit -m "Add feature: your-feature-description"
   git push origin feature/your-feature-name

5. Open a Pull Request:

   Navigate to the repository on GitHub and open a pull request detailing your changes.

📝 Guidelines

• Follow PEP 8: Ensure your code adheres to Python's style guidelines.
• Write Tests: Add tests for new features or bug fixes.
• Document Your Code: Update documentation to reflect changes.

🚀 Getting Started

📋 Prerequisites

• Python 3.10+
• pip
• Virtual Environment Tool (optional)

🛠️ Configuration and Setup

1. Clone the Repository:

   git clone https://github.com/yourusername/fortunes.git
   cd fortunes

2. Set Up Virtual Environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows, use venv\Scripts\activate

3. Install Dependencies:

   pip install --upgrade pip
   pip install -e .[dev]

Running the Project

1. Generating a Fortune:

   from fortunes.random_fortune import get_fortune_cookie
   
   fortune = get_fortune_cookie()
   print(fortune)

2. Sending a Fortune via Email:

   from fortunes.send_email import send_fortune_email
   
   recipient = "[email protected]"
   fortune = "🔮 Your Fortune: Happiness is around the corner.\n🍀 Your Lucky Number: 12"
   
   send_fortune_email(recipient, fortune)

3. Retrieving Quotes by Author:

   from fortunes.get_quotes_by_author import get_quotes_by_author
   
   quotes_dict = {
       "Albert Claude": [
           "Once Ptolemy and Plato, yesterday Newton, today Einstein, and tomorrow new faiths, new beliefs, and new dimensions.",
           # Add more quotes...
       ],
       # Add more authors...
   }
   
   quotes = get_quotes_by_author(quotes_dict)
   for q in quotes:
       print(q)

Platform Compatibility

Fortunes is designed to work seamlessly across all major platforms, including:

• Windows
• macOS
• Linux

Ensure that Python 3.10 or higher is installed on your system.

🔒 Handling Secret Configuration Files (Optional)

Important:
Configuration files containing sensitive information, such as .env, are not included in the version control repository for security reasons.

📄 Creating a .env File

1. Create the File:

   In the root directory of your project, create a file named .env.

2. Add the Following Content:

   SMTP_SERVER=smtp.gmail.com
   SMTP_PORT=587
   SMTP_USERNAME=[email protected]
   SMTP_PASSWORD=your_email_password

   Explanation of Variables:

   • SMTP_SERVER: The address of your SMTP server.
   • SMTP_PORT: The port number for your SMTP server (commonly 587 for TLS).
   • SMTP_USERNAME: Your SMTP server username (usually your email address).
   • SMTP_PASSWORD: Your SMTP server password.

3. Secure Your Credentials:

   • Do Not Share: Never share your .env file or its contents publicly.
   • Add to .gitignore: Ensure that your .env file is listed in .gitignore to prevent it from being tracked by Git.

   # .gitignore
   __pycache__/
   *.pyc
   build/
   dist/
   *.egg-info/
   .env