From cd7e27f539363ff2f6249461708154d119a9aff0 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 12 Jul 2026 14:20:21 +0000 Subject: [PATCH 1/2] docs: add installation troubleshooting guides and update README.md Added detailed `troubleshooting.md` and `trobshooting.md` files describing common installation issues, virtual environment setup, and C++ compilation fixes. Updated the main `README.md` to link these files under a new 'Troubleshooting Installing Errors' section. Co-authored-by: aidasofialily-cmd <247843425+aidasofialily-cmd@users.noreply.github.com> --- README.md | 12 +++++ trobshooting.md | 113 +++++++++++++++++++++++++++++++++++++++++++++ troubleshooting.md | 113 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 238 insertions(+) create mode 100644 trobshooting.md create mode 100644 troubleshooting.md diff --git a/README.md b/README.md index 4cd8db6..c474814 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,18 @@ A Python-based CLI tool that simulates Bitcoin trading using a 'Golden Cross' mo pip install -r requirements.txt ``` +## Troubleshooting Installing Errors + +If you run into issues during installation, please refer to our troubleshooting guides: +- [Detailed Troubleshooting Guide](troubleshooting.md) +- [Alternative Troubleshooting Reference](trobshooting.md) + +### Common Fixes + +- **ModuleNotFoundError:** Ensure you are installing the requirements in the correct Python environment. +- **pytest Command Not Found:** Run tests with `python -m pytest` instead of just `pytest`. +- **venv installation errors:** Never add standard library modules like `venv` to `requirements.txt`. + ## Usage Run the simulation script with default settings (60 days, $10k initial cash): diff --git a/trobshooting.md b/trobshooting.md new file mode 100644 index 0000000..1330847 --- /dev/null +++ b/trobshooting.md @@ -0,0 +1,113 @@ +# Troubleshooting Installation Errors + +This guide provides solutions to common installation and environment setup errors encountered when running the **Bitcoin Trading Simulation** or the C++ experimental projects in this repository. + +--- + +## 1. Python Environment & Dependency Issues + +### Error: `ModuleNotFoundError: No module named '...'` (e.g., `requests`, `pandas`, `numpy`, `pytest`) +This happens when the required third-party Python modules are not installed in your current active environment. + +**Solution:** +Ensure you install all dependencies using the `requirements.txt` file: +```bash +pip install -r requirements.txt +``` +If you are running tests, ensure `pytest` is installed: +```bash +pip install pytest +``` + +### Error: `pytest` command not found +If you run `pytest` and get a "command not found" error, it means the `pytest` executable is not in your system's PATH. + +**Solution:** +You can invoke `pytest` directly through your Python interpreter, which guarantees it runs within the correct environment: +```bash +python -m pytest +``` + +### Error: `venv` installation failure in CI/CD or via Pip +If you encounter errors trying to install a package named `venv` via pip, or see a build failure regarding `venv` in `requirements.txt`: + +**Solution:** +Do not list `venv` in `requirements.txt`. `venv` is a standard library module that comes pre-packaged with Python 3. It is not a PyPI package, so trying to install it via `pip` will fail. If it was present, remove it from `requirements.txt`. + +### Permission Errors during `pip install` +If you get permission denied or access errors (especially on Linux/macOS): + +**Solution:** +Avoid using `sudo pip install`. Instead, use a virtual environment (recommended) or install the packages for your user only: +```bash +pip install --user -r requirements.txt +``` + +--- + +## 2. Virtual Environment Setup Guide + +Using a virtual environment is highly recommended to isolate dependencies and avoid conflicts with other Python projects on your system. + +### How to Create and Activate a Virtual Environment + +1. **Create the environment:** + ```bash + python -m venv venv + ``` + +2. **Activate the environment:** + - **On macOS/Linux:** + ```bash + source venv/bin/activate + ``` + - **On Windows (PowerShell):** + ```bash + .\venv\Scripts\Activate.ps1 + ``` + - **On Windows (Command Prompt):** + ```bash + .\venv\Scripts\activate.bat + ``` + +3. **Install dependencies:** + ```bash + pip install -r requirements.txt + ``` + +4. **Deactivate when done:** + ```bash + deactivate + ``` + +--- + +## 3. C++ Environment & Compilation Errors (e.g., NumberGuess) + +The repository contains experimental C++ terminal-based projects (such as `NumberGuess`). If you run into build issues: + +### Error: `g++` or `make` command not found +This occurs when the C++ compiler or building utility is not installed. + +**Solution:** +- **On Debian/Ubuntu:** + ```bash + sudo apt update + sudo apt install build-essential + ``` +- **On macOS (via Homebrew or Xcode):** + ```bash + xcode-select --install + ``` +- **On Windows:** + Install MinGW or use MSYS2 to obtain `g++` and `make`. + +### Input validation infinite loops +If the terminal-based C++ application goes into an infinite loop upon entering a non-numeric value: + +**Solution:** +Validate user inputs and clear the stream error states properly in the code: +```cpp +std::cin.clear(); +std::cin.ignore(std::numeric_limits::max(), '\n'); +``` diff --git a/troubleshooting.md b/troubleshooting.md new file mode 100644 index 0000000..1330847 --- /dev/null +++ b/troubleshooting.md @@ -0,0 +1,113 @@ +# Troubleshooting Installation Errors + +This guide provides solutions to common installation and environment setup errors encountered when running the **Bitcoin Trading Simulation** or the C++ experimental projects in this repository. + +--- + +## 1. Python Environment & Dependency Issues + +### Error: `ModuleNotFoundError: No module named '...'` (e.g., `requests`, `pandas`, `numpy`, `pytest`) +This happens when the required third-party Python modules are not installed in your current active environment. + +**Solution:** +Ensure you install all dependencies using the `requirements.txt` file: +```bash +pip install -r requirements.txt +``` +If you are running tests, ensure `pytest` is installed: +```bash +pip install pytest +``` + +### Error: `pytest` command not found +If you run `pytest` and get a "command not found" error, it means the `pytest` executable is not in your system's PATH. + +**Solution:** +You can invoke `pytest` directly through your Python interpreter, which guarantees it runs within the correct environment: +```bash +python -m pytest +``` + +### Error: `venv` installation failure in CI/CD or via Pip +If you encounter errors trying to install a package named `venv` via pip, or see a build failure regarding `venv` in `requirements.txt`: + +**Solution:** +Do not list `venv` in `requirements.txt`. `venv` is a standard library module that comes pre-packaged with Python 3. It is not a PyPI package, so trying to install it via `pip` will fail. If it was present, remove it from `requirements.txt`. + +### Permission Errors during `pip install` +If you get permission denied or access errors (especially on Linux/macOS): + +**Solution:** +Avoid using `sudo pip install`. Instead, use a virtual environment (recommended) or install the packages for your user only: +```bash +pip install --user -r requirements.txt +``` + +--- + +## 2. Virtual Environment Setup Guide + +Using a virtual environment is highly recommended to isolate dependencies and avoid conflicts with other Python projects on your system. + +### How to Create and Activate a Virtual Environment + +1. **Create the environment:** + ```bash + python -m venv venv + ``` + +2. **Activate the environment:** + - **On macOS/Linux:** + ```bash + source venv/bin/activate + ``` + - **On Windows (PowerShell):** + ```bash + .\venv\Scripts\Activate.ps1 + ``` + - **On Windows (Command Prompt):** + ```bash + .\venv\Scripts\activate.bat + ``` + +3. **Install dependencies:** + ```bash + pip install -r requirements.txt + ``` + +4. **Deactivate when done:** + ```bash + deactivate + ``` + +--- + +## 3. C++ Environment & Compilation Errors (e.g., NumberGuess) + +The repository contains experimental C++ terminal-based projects (such as `NumberGuess`). If you run into build issues: + +### Error: `g++` or `make` command not found +This occurs when the C++ compiler or building utility is not installed. + +**Solution:** +- **On Debian/Ubuntu:** + ```bash + sudo apt update + sudo apt install build-essential + ``` +- **On macOS (via Homebrew or Xcode):** + ```bash + xcode-select --install + ``` +- **On Windows:** + Install MinGW or use MSYS2 to obtain `g++` and `make`. + +### Input validation infinite loops +If the terminal-based C++ application goes into an infinite loop upon entering a non-numeric value: + +**Solution:** +Validate user inputs and clear the stream error states properly in the code: +```cpp +std::cin.clear(); +std::cin.ignore(std::numeric_limits::max(), '\n'); +``` From 203448756ea3d2c23dcfc26b346fb9b84033ccd7 Mon Sep 17 00:00:00 2001 From: aidasofialily-cmd Date: Sun, 12 Jul 2026 22:26:56 +0800 Subject: [PATCH 2/2] Delete trobshooting.md --- trobshooting.md | 113 ------------------------------------------------ 1 file changed, 113 deletions(-) delete mode 100644 trobshooting.md diff --git a/trobshooting.md b/trobshooting.md deleted file mode 100644 index 1330847..0000000 --- a/trobshooting.md +++ /dev/null @@ -1,113 +0,0 @@ -# Troubleshooting Installation Errors - -This guide provides solutions to common installation and environment setup errors encountered when running the **Bitcoin Trading Simulation** or the C++ experimental projects in this repository. - ---- - -## 1. Python Environment & Dependency Issues - -### Error: `ModuleNotFoundError: No module named '...'` (e.g., `requests`, `pandas`, `numpy`, `pytest`) -This happens when the required third-party Python modules are not installed in your current active environment. - -**Solution:** -Ensure you install all dependencies using the `requirements.txt` file: -```bash -pip install -r requirements.txt -``` -If you are running tests, ensure `pytest` is installed: -```bash -pip install pytest -``` - -### Error: `pytest` command not found -If you run `pytest` and get a "command not found" error, it means the `pytest` executable is not in your system's PATH. - -**Solution:** -You can invoke `pytest` directly through your Python interpreter, which guarantees it runs within the correct environment: -```bash -python -m pytest -``` - -### Error: `venv` installation failure in CI/CD or via Pip -If you encounter errors trying to install a package named `venv` via pip, or see a build failure regarding `venv` in `requirements.txt`: - -**Solution:** -Do not list `venv` in `requirements.txt`. `venv` is a standard library module that comes pre-packaged with Python 3. It is not a PyPI package, so trying to install it via `pip` will fail. If it was present, remove it from `requirements.txt`. - -### Permission Errors during `pip install` -If you get permission denied or access errors (especially on Linux/macOS): - -**Solution:** -Avoid using `sudo pip install`. Instead, use a virtual environment (recommended) or install the packages for your user only: -```bash -pip install --user -r requirements.txt -``` - ---- - -## 2. Virtual Environment Setup Guide - -Using a virtual environment is highly recommended to isolate dependencies and avoid conflicts with other Python projects on your system. - -### How to Create and Activate a Virtual Environment - -1. **Create the environment:** - ```bash - python -m venv venv - ``` - -2. **Activate the environment:** - - **On macOS/Linux:** - ```bash - source venv/bin/activate - ``` - - **On Windows (PowerShell):** - ```bash - .\venv\Scripts\Activate.ps1 - ``` - - **On Windows (Command Prompt):** - ```bash - .\venv\Scripts\activate.bat - ``` - -3. **Install dependencies:** - ```bash - pip install -r requirements.txt - ``` - -4. **Deactivate when done:** - ```bash - deactivate - ``` - ---- - -## 3. C++ Environment & Compilation Errors (e.g., NumberGuess) - -The repository contains experimental C++ terminal-based projects (such as `NumberGuess`). If you run into build issues: - -### Error: `g++` or `make` command not found -This occurs when the C++ compiler or building utility is not installed. - -**Solution:** -- **On Debian/Ubuntu:** - ```bash - sudo apt update - sudo apt install build-essential - ``` -- **On macOS (via Homebrew or Xcode):** - ```bash - xcode-select --install - ``` -- **On Windows:** - Install MinGW or use MSYS2 to obtain `g++` and `make`. - -### Input validation infinite loops -If the terminal-based C++ application goes into an infinite loop upon entering a non-numeric value: - -**Solution:** -Validate user inputs and clear the stream error states properly in the code: -```cpp -std::cin.clear(); -std::cin.ignore(std::numeric_limits::max(), '\n'); -```