🏁 ✅ Final v0.5.1

docs/contributing.md

@@ -0,0 +1,75 @@
+# Contributing to ListSync
+
+We're thrilled that you're interested in contributing to ListSync! This document provides guidelines for contributing to the project. By participating in this project, you agree to abide by its terms.
+
+## Table of Contents
+
+1. [Code of Conduct](#code-of-conduct)
+2. [Getting Started](#getting-started)
+3. [How to Contribute](#how-to-contribute)
+4. [Style Guidelines](#style-guidelines)
+5. [Commit Messages](#commit-messages)
+6. [Pull Requests](#pull-requests)
+7. [Reporting Bugs](#reporting-bugs)
+8. [Suggesting Enhancements](#suggesting-enhancements)
+9. [Questions](#questions)
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [[email protected]].
+
+## Getting Started
+
+1. Fork the repository on GitHub.
+2. Clone your fork locally: `git clone https://github.com/your-username/list-sync.git`
+3. Create a branch for your changes: `git checkout -b your-branch-name`
+4. Make your changes and commit them (see [Commit Messages](#commit-messages)).
+5. Push your changes to your fork: `git push origin your-branch-name`
+6. Create a pull request (see [Pull Requests](#pull-requests)).
+
+## How to Contribute
+
+- Fix bugs or implement new features.
+- Improve documentation.
+- Write tests to increase code coverage.
+- Review pull requests.
+
+## Style Guidelines
+
+- Follow PEP 8 style guide for Python code.
+- Use meaningful variable and function names.
+- Write clear, concise comments and docstrings.
+- Keep functions small and focused on a single task.
+
+## Commit Messages
+
+- Use the present tense ("Add feature" not "Added feature").
+- Use the imperative mood ("Move cursor to..." not "Moves cursor to...").
+- Limit the first line to 72 characters or less.
+- Reference issues and pull requests liberally after the first line.
+
+## Pull Requests
+
+1. Ensure your code adheres to the style guidelines.
+2. Update the README.md with details of changes, if applicable.
+3. Increase version numbers in any examples files and the README.md to the new version that this Pull Request would represent.
+4. You may merge the Pull Request once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.
+
+## Reporting Bugs
+
+1. Use the GitHub issue tracker to report bugs.
+2. Describe the bug in detail, including steps to reproduce.
+3. Include information about your environment (OS, Python version, etc.).
+4. If possible, provide a minimal code example that demonstrates the issue.
+
+## Suggesting Enhancements
+
+1. Use the GitHub issue tracker to suggest enhancements.
+2. Provide a clear and detailed explanation of the feature you want to see.
+3. Explain why this enhancement would be useful to most ListSync users.
+
+## Questions
+
+If you have any questions about contributing, please open an issue with your question. We'll do our best to provide guidance and clarification.
+
+Thank you for contributing to ListSync! Your efforts help make this project better for everyone.

docs/how-it-works.md

@@ -0,0 +1,51 @@
+# How ListSync Works
+
+ListSync is a powerful tool that bridges your IMDB and Trakt lists with Overseerr, automating the process of importing and managing your media requests. Here's a detailed breakdown of its functionality:
+
+## 1. Authentication and Security
+
+- ListSync uses the `cryptography` library's Fernet symmetric encryption to secure your credentials.
+- Your encrypted data is stored locally, ensuring that your sensitive information remains protected.
+
+## 2. List Fetching and Parsing
+
+### IMDB Lists
+
+- The tool uses the `requests` library to fetch the HTML content of your IMDB list.
+- It then employs `BeautifulSoup` to parse the HTML and extract structured data about movies and TV shows.
+
+### Trakt Lists
+
+- A similar process is used for Trakt lists.
+- The HTML response is parsed to extract media information.
+
+## 3. Overseerr Integration
+
+- ListSync interacts with the Overseerr API using the `requests` library.
+- It implements minimal rate limiting to prevent overwhelming the Overseerr server and webhooks.
+- The tool performs media searches, status checks, and request submissions via API endpoints.
+
+## 4. Intelligent Processing
+
+- ListSync differentiates between movies and TV shows for appropriate handling.
+- For TV shows, it determines the number of seasons and requests all available seasons.
+- The tool checks if media is already available or requested before submitting new requests.
+
+## 5. Error Handling and Logging
+
+- Comprehensive error handling is implemented for network issues, API errors, and parsing problems.
+- ListSync uses Python's `logging` module to maintain detailed logs for troubleshooting.
+- Real-time status updates are provided in the console using the `colorama` and `halo` libraries.
+
+## 6. Periodic Syncing
+
+- Users can set up recurring syncs at user-defined intervals.
+- A sleep mechanism is implemented that can be interrupted for on-demand actions.
+
+## 7. User Interface
+
+- ListSync presents a user-friendly command-line interface with color-coded outputs.
+- ASCII art and banners are displayed for an engaging user experience.
+- Summary statistics are provided after each sync operation.
+
+By leveraging these components, ListSync provides a seamless, automated solution for managing your media library through Overseerr.

docs/installation.md

@@ -0,0 +1,116 @@
+# Installation Guide
+
+This guide provides detailed instructions for installing and setting up ListSync using different methods. Choose the method that best suits your needs and technical expertise.
+
+## Table of Contents
+
+1. [Docker Installation (Recommended)](#docker-installation-recommended)
+2. [Standard Python Environment](#standard-python-environment)
+3. [Poetry Installation](#poetry-installation)
+4. [Configuration](#configuration)
+
+## Docker Installation (Recommended)
+
+Docker ensures ListSync runs consistently across different environments.
+
+### Prerequisites
+
+- Docker installed on your system. If not, follow the [official Docker installation guide](https://docs.docker.com/get-docker/).
+
+### Steps
+
+1. **Create a working directory:**
+   Make a folder to house the application's log files (e.g., list-sync)
+
+2. **Pull and Run the Docker Image:**
+   Navigate to your directory and use the following command:
+
+   ```sh
+   sudo docker pull ghcr.io/woahai321/list-sync:main && sudo docker run -it --rm -v "$(pwd)/data:/usr/src/app/data" -e TERM=xterm-256color ghcr.io/woahai321/list-sync:main
+   ```
+
+3. **For subsequent runs:**
+   Use this command:
+
+   ```sh
+   sudo docker run -it --rm -v "$(pwd)/data:/usr/src/app/data" -e TERM=xterm-256color ghcr.io/woahai321/list-sync:main
+   ```
+
+## Standard Python Environment
+
+If you prefer running ListSync in a standard Python environment:
+
+### Prerequisites
+
+- Python 3.9 or higher installed on your system
+
+### Steps
+
+1. **Clone the Repository:**
+
+   ```sh
+   git clone https://github.com/woahai321/list-sync.git
+   cd list-sync
+   ```
+
+2. **Install Dependencies:**
+
+   ```sh
+   pip install -r requirements.txt
+   ```
+
+3. **Run the Script:**
+   ```sh
+   python add.py
+   ```
+
+## Poetry Installation
+
+Poetry offers advantages in dependency management and environment isolation.
+
+### Prerequisites
+
+- Python 3.9 or higher installed on your system
+
+### Steps
+
+1. **Install Poetry:**
+
+   ```sh
+   curl -sSL https://install.python-poetry.org | python3 -
+   ```
+
+2. **Clone the Repository:**
+
+   ```sh
+   git clone https://github.com/woahai321/list-sync.git
+   cd list-sync
+   ```
+
+3. **Install Dependencies:**
+
+   ```sh
+   poetry install
+   ```
+
+4. **Run the Script:**
+   ```sh
+   poetry run python add.py
+   ```
+
+## Configuration
+
+After installation, follow these steps to configure ListSync:
+
+1. Run the script using your chosen installation method.
+2. You will be prompted to enter the following information:
+   - Overseerr URL: Your Overseerr instance's base URL
+   - API Key: The API key from your Overseerr account
+   - IMDB List ID(s): The ID(s) of the IMDB list(s) you want to import
+   - Trakt List ID(s): The ID(s) of the Trakt list(s) you want to import
+3. Enter a password to encrypt your configuration when prompted.
+4. Your encrypted configuration will be saved for future use.
+
+For more information on obtaining list IDs, refer to the [Obtaining List IDs](/docs/obtaining-list-ids.md) guide.
+
+If you encounter any issues during installation or configuration, please refer to our [Troubleshooting Guide](/docs/troubleshooting.md).

docs/legal-disclamer.md

@@ -0,0 +1,45 @@
+# Legal Disclaimer
+
+This legal disclaimer applies to the use of ListSync, a tool designed to automate the import of IMDB and Trakt lists into Overseerr. By using ListSync, you agree to comply with this disclaimer and all applicable laws and regulations.
+
+## Terms of Use
+
+1. **Compliance with Third-Party Terms of Service:**
+   Users of ListSync must adhere to the Terms of Service (ToS) of all third-party services utilized by the tool, including but not limited to Overseerr, IMDB, and Trakt. It is your responsibility to review and comply with these terms.
+
+2. **Prohibited Activities:**
+   ListSync should not be used for any unauthorized or illegal activities, including but not limited to:
+
+   - Spamming or abusive behavior
+   - Unauthorized access to third-party services
+   - Violation of copyright or other intellectual property rights
+
+3. **Rate Limiting and Responsible Use:**
+   Users must use ListSync responsibly and be mindful of rate limits set by third-party services. Excessive use that leads to rate limiting or bans is solely the responsibility of the user.
+
+4. **User Consent and Permissions:**
+   Ensure you have the necessary rights and permissions to import and manage media from IMDB and Trakt lists. Do not import or manage media that you do not have the legal right to access or distribute.
+
+5. **Security and API Credentials:**
+   Protect your API credentials and never share them publicly. You are responsible for maintaining the security of your account and credentials.
+
+6. **No Warranty:**
+   ListSync is provided "as is" without any warranties of any kind, either express or implied. The creators and contributors of ListSync do not warrant that the tool will be error-free or uninterrupted.
+
+7. **Limitation of Liability:**
+   The creators and contributors of ListSync shall not be liable for any direct, indirect, incidental, special, consequential, or exemplary damages resulting from the use or inability to use the tool.
+
+8. **Indemnification:**
+   You agree to indemnify, defend, and hold harmless the creators and contributors of ListSync from any claims, liabilities, damages, losses, and expenses arising from your use of the tool or violation of this disclaimer.
+
+9. **Changes to the Tool and Disclaimer:**
+   The creators of ListSync reserve the right to modify, suspend, or discontinue the tool at any time without notice. This disclaimer may also be updated periodically, and continued use of the tool constitutes acceptance of any changes.
+
+10. **Governing Law:**
+    This disclaimer shall be governed by and construed in accordance with the laws of [Your Jurisdiction], without regard to its conflict of law provisions.
+
+## Responsibility
+
+By using ListSync, you acknowledge that you are solely responsible for your actions while using this tool. The creators and contributors of ListSync are not liable for any misuse, legal consequences, or damages arising from its use.
+
+If you do not agree with any part of this disclaimer, please refrain from using ListSync.

docs/roadmap.md

@@ -0,0 +1,55 @@
+# ListSync Roadmap
+
+This document outlines our plans for future development and features for ListSync. Our roadmap is divided into small, medium, and big tasks to give you an idea of what to expect in upcoming releases.
+
+## ✅ Completed Tasks
+
+### Small Tasks
+
+- Enhanced Error Messages: Improved error descriptions for easier troubleshooting.
+- Advanced Error Handling: Implemented more robust error handling for clearer troubleshooting.
+- Secure User Profiles: Added ability to save and load Overseerr details from an encrypted configuration file.
+- Real-time Progress Updates: Implemented real-time progress updates for importing movies and TV shows.
+
+### Medium Tasks
+
+- Integration with Trakt: Successfully integrated Trakt list support.
+- Interruptible Sleep Mode: Added functionality for interrupting sleep mode for on-demand sync or clean exit.
+- Configuration Management: Implemented save and reuse of configuration setups.
+- Batch Processing: Enabled batch processing for multiple lists simultaneously.
+- Support for TV Shows: Extended functionality to import TV shows from IMDB and Trakt lists.
+- Database Integration: Implemented a real database to track sync history and metrics.
+
+### Big Tasks
+
+- Automated Syncing: Implemented scheduled automatic syncing between IMDB/Trakt and Overseerr.
+- Movie Status Identification: Added ability to identify movies already available, already requested, or to be requested.
+- TV Series Status Identification: Added ability to identify TV series already available, already requested, or to be requested.
+- Encrypted Configuration Storage: Implemented encrypted storage for Overseerr API credentials.
+
+## 🚀 Upcoming Features
+
+### Short-term Goals
+
+- [ ] Improve error handling for network connectivity issues
+- [ ] Add support for custom list naming conventions
+- [ ] Implement a command-line interface for advanced users
+
+### Medium-term Goals
+
+- [ ] Integration with Letterboxd
+- [ ] Customization Options: Allow users to fully customize the UI and behavior of the tool
+- [ ] Add support for additional media management systems (e.g., Jellyfin, Emby)
+
+### Long-term Goals
+
+- [ ] External Notifications: Add webhook notifications for sync status and errors
+- [ ] Web Dashboard: Create a web-based interface for more user-friendly interaction
+- [ ] Advanced Analytics Dashboard: Provide detailed analytics and insights into the sync operations
+- [ ] Machine Learning Suggestions: Use ML to suggest movies and TV shows based on user preferences and history
+
+## 💡 Feature Requests
+
+We welcome feature requests from our users! If you have an idea for a new feature or improvement, please submit it as an issue on our GitHub repository. We'll review all suggestions and update this roadmap accordingly.
+
+Please note that this roadmap is subject to change based on user feedback, technical constraints, and project priorities. We'll do our best to keep this document updated as we progress.