Add comprehensive README

README.md

@@ -0,0 +1,80 @@
+```markdown
+# PyZon
+
+## Overview
+PyZon is a Python-based project designed to interact with the Amazon Product Advertising API (PAAPI). It allows users to perform product searches and retrieve detailed product information through a command-line interface. This project is set up to handle various systems and their peculiarities, especially in the context of network operations and input handling.
+
+## Features
+- **Character-by-character input handling**: Custom implementation to read single characters without echoing them to standard input.
+- **Network request handling**: Custom logic to handle URL fetching and to circumvent App Engine quirks.
+- **Amazon PAAPI Integration**: Search and retrieve product information from Amazon using PAAPI.
+- **Logging**: Configured logging for better traceability of operations.
+
+## Installation Instructions
+To set up and run PyZon, follow these steps:
+1. **Clone the Repository**:
+   ```bash
+   git clone https://github.com/yourgithubusername/pyzon.git
+   cd pyzon
+   ```
+2. **Install Dependencies**:
+   Ensure you have Python 2.5 or above. Install necessary Python packages (if any are listed in requirements.txt or similar documentation):
+   ```bash
+   pip install -r requirements.txt
+   ```
+3. **Set Up Amazon Credentials**:
+   Edit the `paa.py` file to include your Amazon Associate Tag, AWS Key, and AWS Secret:
+   ```python
+   ASSOCIATE_TAG = "<your associate tag>"
+   AWS_KEY = "<your aws key>"
+   AWS_SECRET = "<your aws secret>"
+   ```
+
+## Usage Examples
+To use PyZon, run the `productproto.py` script. This script will take user input character by character and perform search operations using the PAAPI:
+```bash
+python productproto.py
+```
+
+Example:
+```python
+# Initiate a search
+# Type product keywords and see results in real-time.
+```
+
+## Code Summary
+### Directory Structure
+- `getch.py`: Implements single-character input reading for both Windows and Unix-based systems.
+- `net.py`: Handles URL fetching, with special handling for Google App Engine.
+- `paa.py`: Contains integration logic for Amazon's Product Advertising API and product-related classes.
+- `productproto.py`: Main script for running the command-line interface to interact with PAAPI.
+- `__init__.py`: An empty file to mark this directory as a Python package.
+
+### Key Files
+- **`getch.py`**: Provides `_Getch` class for reading single characters without echoing to stdout.
+- **`net.py`**: Manages network operations and includes workaround for App Engine's quirky behavior with `urllib2`.
+- **`paa.py`**: Defines the `Product` class and handles API interactions, including signing requests and parsing XML responses.
+- **`productproto.py`**: Entry-point script that uses the `getch` and `paa` modules to perform real-time product searches.
+
+## Contributing Guidelines
+We welcome contributions to enhance PyZon. To contribute:
+1. **Fork the repository**.
+2. **Create a new branch** for your feature or bugfix:
+   ```bash
+   git checkout -b feature-name
+   ```
+3. **Commit your changes**:
+   ```bash
+   git commit -m "Describe the feature or fix"
+   ```
+4. **Push to the branch**:
+   ```bash
+   git push origin feature-name
+   ```
+5. **Create a Pull Request** and describe your changes.
+
+## License
+This project is licensed under the MIT License. See the `LICENSE` file for more details.
+```
+
+This README.md provides a comprehensive guide to the PyZon project, covering all key sections and providing context for each part of the code.