umpaper-fetch 1.0.0__tar.gz → 1.0.1__tar.gz

umpaper_fetch-1.0.1/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Project specific
+downloads/
+logs/
+*.zip
+*.pdf
+*.tmp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Credentials (never commit these)
+credentials.txt
+config.ini 

umpaper_fetch-1.0.1/DEMO.md

@@ -0,0 +1,170 @@
+# UM Paper Fetch - Live Demo
+
+This document shows how to use the `umpaper-fetch` package after installation.
+
+## 🚀 Installation
+
+```bash
+pip install umpaper-fetch
+```
+
+## 📋 Quick Start
+
+### Basic Usage (Interactive Mode)
+
+```bash
+um-papers
+```
+
+This will prompt you for:
+1. Username (your UM student/staff ID without @siswa.um.edu.my)
+2. Password (entered securely, no echo)
+3. Subject code (e.g., WIA1005, WXES1116)
+4. Download location (option to use default or custom path)
+
+### Advanced Usage
+
+```bash
+# Specify username and subject code upfront
+um-papers --username your_username --subject-code WIA1005
+
+# Use custom output directory
+um-papers --output-dir "C:/My Downloads/UM Papers"
+
+# Non-interactive mode (good for automation)
+um-papers --username your_username --subject-code WXES1116 --no-location-prompt
+
+# Show browser for debugging/monitoring
+um-papers --show-browser --verbose
+
+# Use specific browser
+um-papers --browser edge --timeout 60
+
+# Increase retry attempts for unstable connections
+um-papers --max-retries 5
+```
+
+## 🎯 What Happens When You Run It
+
+1. **Authentication**: Logs into UM OpenAthens system
+2. **Search**: Finds all papers for your subject code
+3. **Download**: Downloads each paper with progress tracking
+4. **Organization**: Creates organized folder structure
+5. **Archive**: Bundles everything into a ZIP file
+
+## 📁 Output Structure
+
+After running `um-papers --subject-code WIA1005`, you'll get:
+
+```
+downloads/
+├── WIA1005/
+│   ├── Y2023_S1_Final_Exam.pdf
+│   ├── Y2023_S1_Mid_Term_Test.pdf
+│   ├── Y2022_S2_Final_Exam.pdf
+│   ├── Y2022_S1_Final_Exam.pdf
+│   └── ... (all available papers)
+└── WIA1005_papers.zip  (contains all the above)
+```
+
+## 🔧 Common Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--username` | UM username (without @domain) | `--username 24012345` |
+| `--subject-code` | Subject to download | `--subject-code WIA1005` |
+| `--output-dir` | Where to save files | `--output-dir "C:/Downloads"` |
+| `--no-location-prompt` | Skip location selection | `--no-location-prompt` |
+| `--show-browser` | Show browser window | `--show-browser` |
+| `--browser` | Choose browser | `--browser edge` |
+| `--verbose` | Detailed logging | `--verbose` |
+
+## 🚨 Troubleshooting
+
+### Browser Issues
+```bash
+# If Chrome fails (common on Windows)
+um-papers --browser edge
+
+# Show browser to see what's happening
+um-papers --show-browser --verbose
+```
+
+### Authentication Issues
+```bash
+# Increase timeout for slow connections
+um-papers --timeout 60
+
+# Check credentials by viewing browser
+um-papers --show-browser
+```
+
+### Download Issues
+```bash
+# Increase retries for unstable connections
+um-papers --max-retries 5
+
+# Use verbose mode to see detailed progress
+um-papers --verbose
+```
+
+## 💡 Tips
+
+1. **First-time users**: Use `--show-browser` to see what's happening
+2. **Windows users**: Edge browser works better than Chrome
+3. **Slow connections**: Use `--timeout 60` and `--max-retries 5`
+4. **Automation**: Use `--no-location-prompt` to skip interactive prompts
+5. **Debugging**: Always use `--verbose` when troubleshooting
+
+## 🎓 Example Session
+
+```bash
+$ um-papers --subject-code WIA1005 --verbose
+
+=== UM Past Year Paper Downloader ===
+Enter your UM username (without @siswa.um.edu.my): 24012345
+Enter your UM password: [hidden]
+
+📋 Configuration Summary
+==================================================
+Username: 24012345
+Subject Code: WIA1005
+Output Directory: C:\Users\User\downloads
+Browser: edge
+Headless Mode: True
+Timeout: 30s
+Max Retries: 3
+
+🚀 Ready to start downloading papers for WIA1005
+Continue? (y/N): y
+
+============================================================
+🔄 Starting download process...
+============================================================
+Step 1: Authenticating with UM portal...
+✅ Authentication successful
+Step 2: Searching for papers with subject code: WIA1005
+✅ Found 12 papers
+Step 3: Downloading papers...
+Downloading papers: 100%|████████████| 12/12 [00:45<00:00,  3.78s/file]
+Step 4: Creating ZIP archive...
+✅ ZIP archive created: C:\Users\User\downloads\WIA1005_papers.zip
+
+🎉 Success! All papers downloaded and zipped:
+📦 ZIP file: C:\Users\User\downloads\WIA1005_papers.zip
+📁 Individual files: C:\Users\User\downloads\WIA1005
+
+✅ Download completed successfully!
+Total papers downloaded: 12
+```
+
+## 📞 Support
+
+If you encounter issues:
+1. Run with `--verbose` flag for detailed logs
+2. Try `--browser edge` if Chrome fails
+3. Check your UM credentials
+4. Ensure you have internet connectivity
+5. Report bugs to the package maintainer
+
+Happy downloading! 🎉 

{umpaper_fetch-1.0.0/umpaper_fetch.egg-info → umpaper_fetch-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: umpaper-fetch
-Version: 1.0.0
+Version: 1.0.1
 Summary: Automated downloader for University Malaya past year exam papers
 Home-page: https://github.com/MarcusMQF/umpaper-fetch
 Author: Marcus Mah

umpaper_fetch-1.0.1/PUBLISHING_GUIDE.md

@@ -0,0 +1,253 @@
+# Publishing Guide for umpaper-fetch
+
+This guide will help you build and publish the `umpaper-fetch` package to PyPI so users can install it with `pip install umpaper-fetch`.
+
+## 📋 Prerequisites
+
+### 1. Install Build Tools
+
+```bash
+pip install --upgrade pip
+pip install build twine setuptools wheel
+```
+
+### 2. Create PyPI Account
+
+1. Go to [PyPI.org](https://pypi.org) and create an account
+2. Verify your email address
+3. (Optional) Go to [TestPyPI.org](https://test.pypi.org) for testing
+
+### 3. Set Up API Tokens
+
+1. Go to your PyPI account settings
+2. Create an API token for uploading packages
+3. Save the token securely (starts with `pypi-`)
+
+## 🔧 Pre-Publishing Setup
+
+### 1. Update Package Information
+
+Edit these files with your actual information:
+
+**setup.py**:
+```python
+author="Your Actual Name",
+author_email="your.actual.email@example.com",
+url="https://github.com/yourusername/umpaper-fetch",
+```
+
+**pyproject.toml**:
+```toml
+authors = [
+    {name = "Your Actual Name", email = "your.actual.email@example.com"}
+]
+[project.urls]
+Homepage = "https://github.com/yourusername/umpaper-fetch"
+Repository = "https://github.com/yourusername/umpaper-fetch"
+"Bug Reports" = "https://github.com/yourusername/umpaper-fetch/issues"
+```
+
+### 2. Choose Package Name
+
+Check if `umpaper-fetch` is available on PyPI:
+```bash
+pip install umpaper-fetch
+# If it fails, the name is available
+```
+
+If taken, modify the name in:
+- `setup.py` → `name="your-chosen-name"`
+- `pyproject.toml` → `name = "your-chosen-name"`
+
+### 3. Update README for PyPI
+
+Replace the current README.md with PYPI_README.md:
+```bash
+cp PYPI_README.md README.md
+```
+
+## 🚀 Building the Package
+
+### 1. Clean Previous Builds
+
+```bash
+# Remove old build artifacts
+rm -rf build/ dist/ *.egg-info/
+```
+
+### 2. Build the Package
+
+```bash
+# Build source distribution and wheel
+python -m build
+```
+
+This creates:
+- `dist/umpaper-fetch-1.0.0.tar.gz` (source distribution)
+- `dist/umpaper_fetch-1.0.0-py3-none-any.whl` (wheel)
+
+### 3. Verify the Build
+
+```bash
+# Check package contents
+tar -tzf dist/umpaper-fetch-1.0.0.tar.gz
+unzip -l dist/umpaper_fetch-1.0.0-py3-none-any.whl
+```
+
+## 🧪 Testing Before Publishing
+
+### 1. Test Local Installation
+
+```bash
+# Install locally in development mode
+pip install -e .
+
+# Test the command
+python -m umpaper_fetch.cli --help
+```
+
+### 2. Test with TestPyPI (Recommended)
+
+```bash
+# Upload to TestPyPI first
+twine upload --repository testpypi dist/*
+
+# Install from TestPyPI
+pip install --index-url https://test.pypi.org/simple/ umpaper-fetch
+
+# Test the installation
+um-papers --version
+```
+
+## 📦 Publishing to PyPI
+
+### 1. Upload to PyPI
+
+```bash
+# Upload to real PyPI
+twine upload dist/*
+```
+
+When prompted:
+- Username: `__token__`
+- Password: Your PyPI API token (including `pypi-` prefix)
+
+### 2. Verify Publication
+
+```bash
+# Wait a few minutes, then test installation
+pip install umpaper-fetch
+
+# Test the command
+um-papers --help
+```
+
+## 🔄 Updating the Package
+
+### 1. Update Version Number
+
+Update version in:
+- `setup.py`: `version="1.0.1"`
+- `pyproject.toml`: `version = "1.0.1"`
+- `umpaper_fetch/__init__.py`: `__version__ = "1.0.1"`
+- `umpaper_fetch/cli.py`: `version='%(prog)s 1.0.1'`
+
+### 2. Build and Upload New Version
+
+```bash
+# Clean and build
+rm -rf build/ dist/ *.egg-info/
+python -m build
+
+# Upload
+twine upload dist/*
+```
+
+## 📁 Project Structure for PyPI
+
+```
+PastYear Accessor/
+├── umpaper_fetch/                 # Main package directory
+│   ├── __init__.py               # Package initialization
+│   ├── cli.py                    # Command-line interface
+│   ├── auth/                     # Authentication module
+│   ├── scraper/                  # Scraping module
+│   ├── downloader/               # Download module
+│   └── utils/                    # Utility modules
+├── setup.py                      # Setup configuration
+├── pyproject.toml                # Modern Python project config
+├── requirements.txt              # Dependencies
+├── README.md                     # PyPI description
+├── LICENSE                       # MIT license
+├── MANIFEST.in                   # Include/exclude files
+└── PUBLISHING_GUIDE.md           # This guide
+```
+
+## 🔒 Security Best Practices
+
+### 1. Use API Tokens
+- Never use username/password for uploading
+- Use scoped API tokens for better security
+
+### 2. Two-Factor Authentication
+- Enable 2FA on your PyPI account
+- Use app-based authentication (not SMS)
+
+### 3. Environment Variables
+```bash
+# Set token as environment variable
+export TWINE_USERNAME=__token__
+export TWINE_PASSWORD=pypi-your-api-token-here
+
+# Upload without entering credentials
+twine upload dist/*
+```
+
+## 🐛 Troubleshooting
+
+### Build Errors
+```bash
+# If build fails, check:
+python setup.py check
+python -m build --verbose
+```
+
+### Upload Errors
+```bash
+# If upload fails:
+twine check dist/*
+twine upload --verbose dist/*
+```
+
+### Import Errors After Installation
+```bash
+# Check if package is properly installed
+pip show umpaper-fetch
+pip list | grep umpaper
+```
+
+## 📈 After Publishing
+
+### 1. Monitor Downloads
+- Check PyPI package page for download statistics
+- Monitor for issues/feedback
+
+### 2. Documentation
+- Update GitHub README with PyPI installation instructions
+- Create GitHub releases for version tags
+
+### 3. Maintenance
+- Respond to user issues
+- Keep dependencies updated
+- Regular security updates
+
+## 🎉 Success!
+
+Once published, users can install your package with:
+
+```bash
+pip install umpaper-fetch
+um-papers --help
+```
+
+Your package will be available at: https://pypi.org/project/umpaper-fetch/ 

umpaper_fetch-1.0.1/PYPI_README.md

@@ -0,0 +1,120 @@
+# UM Paper Fetch
+
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Automated downloader for University Malaya past year exam papers. No more manual navigation through multiple systems - just one command to download all papers for any subject!
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install umpaper-fetch
+```
+
+### Usage
+
+After installation, use the `um-papers` command:
+
+```bash
+# Interactive mode (recommended for first-time users)
+um-papers
+
+# With subject code
+um-papers --subject-code WIA1005
+
+# With username and subject code
+um-papers --username 24056789 --subject-code WXES1116
+
+# Non-interactive mode
+um-papers --username 24012345 --subject-code WIA1005 --no-location-prompt
+
+# Show browser for debugging
+um-papers --show-browser --verbose
+```
+
+## ✨ Features
+
+- **One-command download**: Get all past year papers for any UM subject
+- **Automatic authentication**: Handles complex UM OpenAthens/SAML login
+- **Smart organization**: Papers organized by subject code with proper naming
+- **ZIP archive creation**: All papers bundled in a convenient ZIP file
+- **Progress tracking**: Real-time download progress with retry logic
+- **Cross-platform**: Works on Windows, macOS, and Linux
+- **Browser flexibility**: Supports Chrome, Edge, and auto-detection
+
+## 📋 Requirements
+
+- Python 3.8 or higher
+- Valid UM student/staff credentials
+- Internet connection
+- Chrome or Edge browser installed
+
+## 🎯 How it Works
+
+1. **Authentication**: Automatically logs into UM systems via OpenAthens proxy
+2. **Search**: Finds all past year papers for the specified subject code
+3. **Download**: Downloads all papers with proper naming and organization
+4. **Archive**: Creates a ZIP file containing all downloaded papers
+
+## 📖 Command Options
+
+```
+Options:
+  -u, --username TEXT         UM username (without @siswa.um.edu.my)
+  -s, --subject-code TEXT     Subject code (e.g., WIA1005, WXES1116)
+  -o, --output-dir TEXT       Output directory (default: ./downloads)
+  --no-location-prompt        Skip location selection prompt
+  --show-browser              Show browser window (default: headless)
+  -b, --browser [auto|chrome|edge]  Browser choice (default: edge)
+  --timeout INTEGER           Session timeout in seconds (default: 30)
+  --max-retries INTEGER       Maximum retry attempts (default: 3)
+  -v, --verbose               Enable verbose logging
+  --version                   Show version information
+  -h, --help                  Show help message
+```
+
+## 📁 Output Structure
+
+```
+downloads/
+└── WIA1005/
+    ├── Y2023_S1_Final_Exam.pdf
+    ├── Y2023_S1_Mid_Term_Test.pdf
+    ├── Y2022_S2_Final_Exam.pdf
+    └── ...
+└── WIA1005_papers.zip
+```
+
+## 🔧 Troubleshooting
+
+### Browser Issues
+- **Windows**: Tool prefers Edge browser (better compatibility)
+- **Chrome driver errors**: Try using `--browser edge`
+- **Browser not found**: Ensure Chrome or Edge is installed
+
+### Authentication Issues
+- **Login failed**: Verify your UM credentials
+- **Timeout**: Increase timeout with `--timeout 60`
+- **Network issues**: Check your internet connection
+
+### Download Issues
+- **No papers found**: Verify the subject code is correct
+- **Download failures**: Use `--max-retries 5` for unstable connections
+
+For detailed troubleshooting, run with `--verbose` flag.
+
+## 🤝 Support
+
+- **Issues**: Report bugs or request features
+- **Documentation**: Full documentation available in the repository
+- **Contributions**: Pull requests welcome!
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## ⚠️ Disclaimer
+
+This tool is for educational purposes only. Please respect University Malaya's terms of service and use responsibly. Only download papers you have legitimate access to as a registered student or staff member.