{"id":29567321,"url":"https://github.com/marcusmqf/umpaper-fetch","last_synced_at":"2025-07-18T23:32:49.975Z","repository":{"id":300418449,"uuid":"1006090589","full_name":"MarcusMQF/umpaper-fetch","owner":"MarcusMQF","description":"One-click bulk download solution for University Malaya (UM) past year exam papers in terminal.","archived":false,"fork":false,"pushed_at":"2025-06-29T19:49:09.000Z","size":73,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-29T20:35:21.561Z","etag":null,"topics":["bulk","package","pip","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/umpaper-fetch/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MarcusMQF.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-21T13:23:37.000Z","updated_at":"2025-06-29T19:49:12.000Z","dependencies_parsed_at":"2025-06-21T15:47:16.981Z","dependency_job_id":null,"html_url":"https://github.com/MarcusMQF/umpaper-fetch","commit_stats":null,"previous_names":["marcusmqf/umpaper-fetch"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MarcusMQF/umpaper-fetch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarcusMQF%2Fumpaper-fetch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarcusMQF%2Fumpaper-fetch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarcusMQF%2Fumpaper-fetch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarcusMQF%2Fumpaper-fetch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MarcusMQF","download_url":"https://codeload.github.com/MarcusMQF/umpaper-fetch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarcusMQF%2Fumpaper-fetch/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265853581,"owners_count":23839203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bulk","package","pip","python"],"created_at":"2025-07-18T23:30:57.124Z","updated_at":"2025-07-18T23:32:49.965Z","avatar_url":"https://github.com/MarcusMQF.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎓 Open Source UM PastYear Paper Downloader\n\n**One-click bulk download solution for University Malaya (UM) past year exam papers**\n\nAutomate the tedious process of manually downloading past year papers one by one. Simply provide your UM credentials and subject code, and get all available papers in a single organized ZIP file.\n\n[![PyPI version](https://badge.fury.io/py/umpaper-fetch.svg)](https://badge.fury.io/py/umpaper-fetch)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n---\n\n## 🚀 Quick Start (For Regular Users)\n\n### **Installation**\n```bash\n# Install from PyPI\npip install umpaper-fetch\n\n# Upgrade to latest version\npip install --upgrade umpaper-fetch\n```\n\n### **Basic Usage**\n```bash\n# See all available commands and options\npython -m umpaper_fetch.cli --help\n\n# Run the downloader interactively\npython -m umpaper_fetch.cli\n\n# Or with command-line shortcut (if install inside venv and activated)\num-papers --help\num-papers\n```\n\n### **First Run**\nFollow the interactive prompts:\n1. Enter your UM username (without @siswa.um.edu.my)\n2. Enter your password securely\n3. Enter subject code (e.g., WIA1005)\n4. Choose download location\n5. Confirm download of found papers\n\n---\n\n## ✨ Key Features\n\n### 🚀 **Core Functionality**\n- **🔄 One-Click Bulk Download**: Download all past year papers for any subject code automatically\n- **📦 Smart ZIP Organization**: Automatically organizes papers by year and creates a structured ZIP archive\n- **🔐 Secure Authentication**: Handles complex UM OpenAthens authentication flow seamlessly\n- **⚡ Concurrent Downloads**: Multi-threaded downloading for faster performance\n- **🔄 Auto-Retry Logic**: Robust error handling with configurable retry attempts\n- **📊 Real-time Progress**: Live progress bars and detailed status updates\n\n### 📁 **File Organization**\n- **📂 Hierarchical Structure**: Papers organized by subject → year → semester\n- **🏷️ Smart File Naming**: Automatically detects and preserves meaningful filenames\n- **📋 Auto-Generated README**: Includes download summary and paper inventory in ZIP\n- **🗂️ Organized Output**: Individual PDFs + consolidated ZIP file\n- **🧹 Optional Cleanup**: Choice to keep individual files or ZIP only\n\n### 🖥️ **User Experience**\n- **📱 Terminal-Based Interface**: Clean, intuitive command-line interface\n- **🎯 Interactive Mode**: Prompts for credentials and settings when needed\n- **⚙️ Command-Line Mode**: Full automation with command-line arguments\n- **📍 Custom Download Locations**: Choose where to save your papers\n- **🔍 Browser Options**: Support for Edge, Chrome with auto-detection\n- **📝 Comprehensive Logging**: Detailed logs for troubleshooting\n\n---\n\n## 📋 Complete Command Reference\n\n### **For Regular Users**\n\n#### **Interactive Mode (Recommended for beginners)**\n```bash\n# See all available options first\npython -m umpaper_fetch.cli --help\n\n# Run interactive mode\npython -m umpaper_fetch.cli\n```\n*Prompts for all required information*\n\n#### **Quick Commands**\n```bash\n# With username and subject code\npython -m umpaper_fetch.cli --username john_doe --subject-code WIA1005\n\n# With custom output directory\npython -m umpaper_fetch.cli -u student123 -s WXES1116 -o \"C:/Downloads/Papers\"\n\n# Skip location prompt for automation\npython -m umpaper_fetch.cli -s WIA1005 --no-location-prompt\n```\n\n#### **Available Options**\n| Command | Short | Description | Default |\n|---------|-------|-------------|---------|\n| `--help` | `-h` | Available command to use |  |\n| `--username` | `-u` | UM username (without @siswa.um.edu.my) | *prompted* |\n| `--subject-code` | `-s` | Subject code to search for (e.g., WIA1005) | *prompted* |\n| `--output-dir` | `-o` | Custom download directory | `./downloads` |\n| `--browser` | `-b` | Browser choice: `auto`, `chrome`, `edge` | `edge` |\n| `--timeout` | | Session timeout in seconds | `30` |\n| `--max-retries` | | Maximum retry attempts for failed downloads | `3` |\n| `--no-location-prompt` | | Skip interactive location selection | `false` |\n| `--verbose` | `-v` | Enable detailed debug logging | `false` |\n\n### **For Developers \u0026 Advanced Users**\n\n#### **Development Installation**\n```bash\n# Clone repository\ngit clone https://github.com/MarcusMQF/umpaper-fetch.git\ncd umpaper-fetch\n\n# Install in development mode\npip install -e .\n\n# Install development dependencies\npip install -e .[dev]\n```\n\n#### **Debug Commands**\n```bash\n# Show browser window for debugging\npython -m umpaper_fetch.cli --show-browser --verbose --subject-code WIA1005\n\n# High-performance mode with extended timeouts\npython -m umpaper_fetch.cli -s WIA1005 --max-retries 5 --timeout 60\n\n# Force specific browser\npython -m umpaper_fetch.cli --browser chrome --subject-code CSC1025\n```\n\n#### **Developer Options**\n| Command | Description | Use Case |\n|---------|-------------|----------|\n| `--show-browser` | Show browser window (disable headless mode) | Debugging authentication |\n| `--verbose` | Enable detailed debug logging | Troubleshooting issues |\n| `--timeout 60` | Extended session timeout | Slow connections |\n| `--max-retries 5` | More retry attempts | Unstable connections |\n\n---\n\n## 💡 Tips for Best Experience\n\n### **Choose the Right Browser**\n```bash\n# Windows users (recommended)\npython -m umpaper_fetch.cli --browser edge --subject-code WIA1005\n\n# Mac/Linux users\npython -m umpaper_fetch.cli --browser chrome --subject-code WIA1005\n\n# Auto-detect (fallback)\npython -m umpaper_fetch.cli --browser auto --subject-code WIA1005\n```\n\n### **Optimize for Your Connection**\n```bash\n# For slow/unstable connections\npython -m umpaper_fetch.cli --timeout 90 --max-retries 5 --subject-code WIA1005\n\n# For fast connections\npython -m umpaper_fetch.cli --timeout 15 --max-retries 2 --subject-code WIA1005\n```\n\n### **Batch Processing Multiple Subjects**\n```bash\n# Process multiple subjects\npython -m umpaper_fetch.cli -s WIA1005 --no-location-prompt -o \"./Papers/WIA1005\"\npython -m umpaper_fetch.cli -s WIX1116 --no-location-prompt -o \"./Papers/WXES1116\"\npython -m umpaper_fetch.cli -s CSC1025 --no-location-prompt -o \"./Papers/CSC1025\"\n```\n\n### **Automation-Friendly Commands**\n```bash\n# Fully automated (only prompts for password)\npython -m umpaper_fetch.cli -u your_username -s WIA1005 --no-location-prompt -o \"./Papers\"\n\n# Silent mode with custom browser\npython -m umpaper_fetch.cli -u your-username -s WXES1116 --browser edge --no-location-prompt\n```\n\n---\n\n## 📊 What You Get\n\n### **Organized File Structure**\n```\n📁 downloads/\n├── 📁 WIA1005/\n│   ├── 📁 Year_2023/\n│   │   ├── WIA1005_Final_2023_S1.pdf\n│   │   └── WIA1005_Final_2023_S2.pdf\n│   ├── 📁 Year_2022/\n│   │   ├── WIA1005_Final_2022_S1.pdf\n│   │   └── WIA1005_Final_2022_S2.pdf\n│   └── 📁 Unsorted/\n│       └── WIA1005_Additional_Papers.pdf\n├── 📦 WIA1005_past_years.zip\n└── 📄 WIA1005_README.txt\n```\n\n### **ZIP Archive Contents**\n- **Hierarchical Organization**: Subject → Year → Files\n- **Automatic README**: Download summary and file inventory\n- **Optimized Compression**: Balanced compression for size/speed\n- **Preserve Metadata**: Original filenames and dates maintained\n\n---\n\n## 🔧 Prerequisites \u0026 Setup\n\n### **System Requirements**\n- **Python 3.8+** installed\n- **Internet connection** (stable recommended)\n- **UM student account** with active credentials\n- **Browser**: Microsoft Edge (Windows) or Google Chrome (Mac/Linux)\n\n### **Browser Setup**\n- **Windows**: Microsoft Edge (pre-installed, recommended)\n- **Mac/Linux**: Google Chrome (install from google.com/chrome)\n- **Auto-detection**: Tool will find the best available browser\n\n### **Firewall/Network**\n- Tool connects to `exampaper.um.edu.my` via HTTPS\n- No special firewall configuration needed\n- Works on UM campus network and external networks\n\n---\n\n## 🎯 Quick Command Cheat Sheet\n\n### **For Regular Users**\n```bash\n# Install and run\npip install umpaper-fetch\npython -m umpaper_fetch.cli\n\n# Get help and see all options\npython -m umpaper_fetch.cli --help\n\n# Quick download with subject code\npython -m umpaper_fetch.cli -s WIA1005\n\n# Custom download location\npython -m umpaper_fetch.cli -s WIA1005 -o \"C:/MyPapers\"\n\n# Batch mode (no prompts except password)\npython -m umpaper_fetch.cli -u your_username -s WIA1005 --no-location-prompt\n```\n\n### **For Developers**\n```bash\n# Development setup\ngit clone https://github.com/MarcusMQF/umpaper-fetch.git\ncd umpaper-fetch\npip install -e .[dev]\n\n# Debug mode\npython -m umpaper_fetch.cli --show-browser --verbose -s WIA1005\n\n# Performance testing\npython -m umpaper_fetch.cli --max-retries 5 --timeout 60 -s WXES1116\n```\n\n---\n\n## 🔒 Security \u0026 Privacy\n\n### **What We Do**\n- ✅ Use secure HTTPS connections only\n- ✅ Handle UM authentication through official channels\n- ✅ Clean up browser data after each session\n- ✅ Never store or log passwords\n- ✅ Respect server rate limits\n\n### **What We Don't Do**\n- ❌ Store credentials anywhere\n- ❌ Bypass security measures\n- ❌ Access unauthorized content\n- ❌ Share or transmit personal data\n- ❌ Violate UM terms of service\n\n---\n\n## ⚖️ Legal \u0026 Academic Use\n\n**Educational Purpose Only**: This tool is designed for UM students to efficiently access past year papers for their studies. Users must:\n- Have valid UM credentials\n- Comply with UM's terms of service\n- Use papers for academic purposes only\n- Respect copyright and intellectual property rights\n\n**Disclaimer**: This is an unofficial tool not affiliated with University Malaya.\n\n---\n\n## 🤝 Support \u0026 Contributing\n\n### **Get Help**\n- 📖 Check this README for common usage patterns\n- 🐛 Report issues on [GitHub Issues](https://github.com/MarcusMQF/umpaper-fetch/issues)\n- 💡 Request features via GitHub Issues\n\n### **Contributing**\nContributions welcome! Please:\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes with tests\n4. Submit a pull request\n5. Follow existing code style\n\n### **Development Setup**\n```bash\ngit clone https://github.com/MarcusMQF/umpaper-fetch.git\ncd umpaper-fetch\npip install -e .[dev]\npytest  # Run tests\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcusmqf%2Fumpaper-fetch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcusmqf%2Fumpaper-fetch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcusmqf%2Fumpaper-fetch/lists"}