Python Web Application

A sample Flask web application that demonstrates both web development and API integration in Python. This application showcases how to build web pages, handle user interactions, and make calls to external APIs.

🌟 Features

• Flask Web Framework: Modern Python web development
• External API Integration: Makes calls to weather, jokes, and cat facts APIs
• Responsive Design: Bootstrap-based responsive UI
• Interactive Frontend: JavaScript-powered user interactions
• Error Handling: Graceful error handling with fallback responses
• RESTful API Endpoints: JSON API endpoints for data access
• Template System: Jinja2 templating for dynamic content

📁 Project Structure

python-web-app/
├── app/
│   ├── __init__.py           # Package initialization
│   ├── main.py              # Main Flask application
│   ├── api_client.py        # API client modules
│   ├── templates/           # HTML templates
│   │   ├── base.html        # Base template
│   │   ├── index.html       # Home page
│   │   ├── weather.html     # Weather page
│   │   ├── jokes.html       # Jokes page
│   │   ├── cat_facts.html   # Cat facts page
│   │   ├── 404.html         # 404 error page
│   │   └── 500.html         # 500 error page
│   └── static/
│       └── css/
│           └── style.css    # Custom styles
├── requirements.txt         # Python dependencies
├── run.py                  # Application entry point
└── README.md               # This file

🚀 Getting Started

Prerequisites

• Python 3.7 or higher
• pip (Python package installer)

Installation

1. Clone or navigate to the project directory:

   cd python-web-app

2. Create a virtual environment (recommended):

   python3 -m venv venv

3. Activate the virtual environment:

   On macOS/Linux:

   source venv/bin/activate

   On Windows:

   venv\Scripts\activate

4. Install dependencies:

   pip install -r requirements.txt

Running the Application

1. Start the development server:

   python3 run.py

   Or alternatively:

   python3 -m flask --app app.main run

2. Open your browser and navigate to:

   http://localhost:5000
   

🔧 Configuration

Environment Variables

You can set the following environment variables to customize the application:

• SECRET_KEY: Flask secret key (default: 'dev-secret-key-change-in-production')
• PORT: Port to run the application on (default: 5000)
• DEBUG: Enable debug mode (default: True)

API Keys

For production use with real weather data, you'll need to:

1. Sign up for a free API key at OpenWeatherMap
2. Update the WeatherAPI class in app/api_client.py to use your real API key
3. Uncomment the real API call code in the get_weather method

📋 API Endpoints

The application provides the following API endpoints:

• GET /api/status - Check application status
• GET /weather/api/<city> - Get weather data for a city
• GET /api/joke - Get a random joke
• GET /api/cat-fact - Get a random cat fact

🎯 Features Demonstrated

Web Development

• Flask Routes: Multiple routes for different pages and API endpoints
• Template Rendering: Using Jinja2 templates for dynamic HTML generation
• Static Files: Serving CSS and JavaScript files
• Form Handling: Processing user input from web forms
• Error Pages: Custom 404 and 500 error pages

API Integration

• HTTP Requests: Making GET requests to external APIs
• Error Handling: Graceful handling of API failures with fallback responses
• JSON Processing: Parsing and processing JSON responses
• Timeout Handling: Request timeout configuration
• Multiple APIs: Integration with weather, jokes, and cat facts APIs

Frontend Features

• Responsive Design: Bootstrap-based mobile-friendly design
• Interactive UI: JavaScript-powered dynamic content updates
• Loading States: User feedback during API calls
• Error Display: User-friendly error messages
• History Tracking: Client-side history for jokes and facts

🧪 Testing the Application

Manual Testing

1. Home Page: Visit the home page and check all navigation links
2. Weather Feature: Try searching for different cities
3. Jokes Feature: Click the joke button multiple times
4. Cat Facts Feature: Test the cat facts functionality
5. API Status: Check the API status from the home page

API Testing

You can test the API endpoints directly using curl:

# Check application status
curl http://localhost:5000/api/status

# Get weather data
curl http://localhost:5000/weather/api/London

# Get a random joke
curl http://localhost:5000/api/joke

# Get a cat fact
curl http://localhost:5000/api/cat-fact

🔧 Development

Adding New Features

1. New API Client: Add new API client classes to api_client.py
2. New Routes: Add new routes to main.py
3. New Templates: Create HTML templates in the templates/ directory
4. New Styles: Add CSS to static/css/style.css

Best Practices

• Use environment variables for configuration
• Implement proper error handling
• Add logging for debugging
• Use virtual environments
• Keep API keys secure
• Test thoroughly

🐛 Troubleshooting

Common Issues

1. Import Errors: Make sure you're in the virtual environment and have installed dependencies
2. Port Already in Use: Change the port using the PORT environment variable
3. API Timeouts: Check your internet connection; the app will fall back to mock data
4. Template Not Found: Ensure all templates are in the app/templates/ directory

Logs

The application uses Python's logging module. Check the console output for error messages and debugging information.

📚 Learning Resources

This project demonstrates several key concepts in Python web development:

• Flask Documentation
• Requests Library
• Jinja2 Templates
• Bootstrap CSS Framework

🤝 Contributing

Feel free to fork this project and add your own features! Some ideas for enhancements:

• Add user authentication
• Implement a database for storing favorites
• Add more API integrations
• Create a mobile app version
• Add unit tests
• Implement caching for API responses

📄 License

This project is for educational purposes. Feel free to use and modify as needed.

---

Happy Coding! 🐍✨