Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/Jejis06/PeachBtcApiWrapper/blob/main/README.md) - [main.py](https://github.com/Jejis06/PeachBtcApiWrapper/blob/main/main.py) - [test_peach_wrapper.py](https://github.com/Jejis06/PeachBtcApiWrapper/blob/main/test_peach_wrapper.py) - [test_integration.py](https://github.com/Jejis06/PeachBtcApiWrapper/blob/main/test_integration.py) - [requirements.txt](https://github.com/Jejis06/PeachBtcApiWrapper/blob/main/requirements.txt)

# Contributing Guidelines This document provides guidelines for contributing to the PeachBtcApiWrapper project. The goal is to maintain code quality, ensure comprehensive API coverage, and make the contribution process clear for all developers. The guidelines are derived from the existing structure, coding style, and testing philosophy of the project. The project is a Python wrapper for the Peach Bitcoin P2P trading API, aiming for complete coverage of all public and private endpoints. Key features include full type annotations, automatic token refreshing, and a comprehensive test suite. Adhering to these established patterns is crucial for any contribution. Sources: [README.md:1-21](), [main.py:1-38]() ## Getting Started Before you begin, you must set up your local development environment. This involves cloning the repository, creating a virtual environment, and installing the required dependencies. 1. **Clone the repository:** ```bash git clone https://github.com/Jejis06/PeachBtcApiWrapper.git cd PeachBtcApiWrapper ``` 2. **Create and activate a virtual environment:** ```bash # For macOS/Linux python -m venv env source env/bin/activate # For Windows python -m venv env env\Scripts\activate ``` 3. **Install dependencies:** ```bash pip install -r requirements.txt ``` This setup ensures you have all the necessary packages, such as `requests`, `ecdsa`, `pgpy`, and `pytest`, to run and test the wrapper. Sources: [README.md:29-39](), [requirements.txt]() ## Project Structure The project is organized into a few key files. Understanding their roles is essential for making contributions. ```mermaid graph TD subgraph "Source Code" main_py["main.py
Core wrapper logic and API methods"] end subgraph "Testing" test_unit["test_peach_wrapper.py
Unit tests (mocked)"] test_integration["test_integration.py
Integration tests (real API)"] priv_py["priv.py
Credentials (user-created, gitignored)"] end subgraph "Configuration & Docs" readme["README.md
Project documentation"] reqs["requirements.txt
Dependencies"] end main_py --> test_unit main_py --> test_integration test_integration --> priv_py ``` This diagram shows the relationship between the core logic, testing files, and documentation. | File | Description | | --------------------- | --------------------------------------------------------------------------- | | `main.py` | Contains the main `PeachWrapper` class and all API endpoint implementations. | | `test_peach_wrapper.py` | Unit tests that mock API responses to test wrapper logic in isolation. | | `test_integration.py` | Integration tests that hit the real Peach API, requiring credentials. | | `priv.py` | A local, untracked file for storing credentials needed for integration tests. | | `requirements.txt` | A list of all Python dependencies for the project. | | `README.md` | The main documentation, including setup, quick start, and API coverage. | Sources: [README.md:203-211](), [test_integration.py:25-36]() ## Coding Standards New contributions should align with the existing code style, which emphasizes clarity, type safety, and robust error handling. ### Core Classes The wrapper is built around three main classes. New features should extend these classes or interact with them appropriately. ```mermaid classDiagram direction LR class PeachWrapper { -private_key_hex: str -access_token: str -expiry: int -session: rq.Session +set_access_token() +refresh_token_if_expired() +__send_request(method, suburl, data, params, requires_auth) +market_prices() +get_self_user() +post_buy_offer() +post_sell_offer() +... 63 total methods } class PeachPaymentData { -payment_type: str -payment_fields: dict +create_hash(): tuple } class PeachMeansOfPayment { -payment_type: dict +add_new_type(currency, methods) +get(): dict } class PeachBTCError { +message: str +status_code: int +error_id: str } PeachWrapper ..> PeachPaymentData : uses PeachWrapper ..> PeachMeansOfPayment : uses PeachWrapper ..> PeachBTCError : raises ``` This diagram illustrates the primary classes and their relationship. `PeachWrapper` is the main entry point, using `PeachPaymentData` and `PeachMeansOfPayment` as data containers for creating offers. Sources: [main.py:70-200](), [main.py:59-68]() ### Key Implementation Details - **Type Hinting**: All function signatures and class attributes must include Python type hints. - **Docstrings**: Public methods should have clear docstrings explaining their purpose, arguments, and what they return. - **Error Handling**: API errors or request failures should raise a `PeachBTCError` with a descriptive message, status code, and error ID if available. - **Private Methods**: Internal helper functions, like `__send_request` or `__sign_message`, should be prefixed with a double underscore. Sources: [main.py:70-79](), [main.py:382-401](), [main.py:233-242]() ## Testing Philosophy The project maintains a high standard of testing with two distinct layers: unit tests and integration tests. Any new feature or bug fix must be accompanied by relevant tests. ### Testing Workflow The diagram below shows the recommended workflow for running tests. ```mermaid flowchart TD A[Start] --> B{Run Tests}; B --> C[pytest test_peach_wrapper.py
Run Unit Tests (fast, no network)]; C --> D{All Pass?}; D -- Yes --> E[Create priv.py with credentials]; D -- No --> F[Fix Code/Tests]; F --> C; E --> G[pytest test_integration.py -m "not slow"
Run Integration Tests (real API)]; G --> H{All Pass?}; H -- Yes --> I[Contribution Ready]; H -- No --> F; ``` Sources: [README.md:213-222](), [test_integration.py:25-36]() ### Unit Tests (`test_peach_wrapper.py`) Unit tests are designed to be fast and run without any external dependencies like network access or API keys. They use `unittest.mock.patch` to mock the `__send_request` method, allowing verification of: - Correct endpoint URL and HTTP method. - Correct payload data and parameters. - Proper handling of mocked API responses. Example of a mocked unit test: ```python # From test_peach_wrapper.py @patch.object(PeachWrapper, '_PeachWrapper__send_request') def test_system_status(self, mock_request): """Test system status endpoint.""" mock_request.return_value = { "error": None, "status": "online", "serverTime": 1692788403879 } wrapper = PeachWrapper() result = wrapper.system_status() mock_request.assert_called_once_with('GET', 'system/status') assert result["status"] == "online" ``` Sources: [test_peach_wrapper.py:302-315]() ### Integration Tests (`test_integration.py`) Integration tests hit the live Peach Bitcoin API to ensure the wrapper works with the real system. These tests are slower and require credentials. **Setup for Integration Tests:** To run them, you must create a `priv.py` file in the root directory with your credentials. This file is ignored by Git. ```python # priv.py pkey = "your_private_key_hex" unique_id = "your_unique_id" pkeywall = "wallet_private_key_hex" pubkeywall = "bc1q..." pgp_public_key_str = "..." pgp_private_key_str = "..." pgp_passphrase_str = "..." ``` Sources: [README.md:224-245](), [test_integration.py:25-36]() Tests that perform write operations (like creating offers) are marked as `slow` and can be skipped. ```bash # Run all tests except slow ones pytest test_integration.py -v -s -m "not slow" # Run only slow tests (use with caution) pytest test_integration.py -v -s -m "slow" ``` Sources: [README.md:219-222](), [test_integration.py:650-658]() ## How to Add a New API Endpoint Adding a new endpoint is a common contribution. Follow these steps to ensure it is integrated correctly. ### Step-by-Step Guide This sequence diagram illustrates the development process for adding a new endpoint. ```mermaid sequenceDiagram participant Dev as Developer participant main_py as "main.py" participant test_unit as "test_peach_wrapper.py" participant test_integration as "test_integration.py" participant README_md as "README.md" Dev->>main_py: 1. Add new method to PeachWrapper Note over main_py: Implement call to __send_request Dev->>test_unit: 2. Add unit test with @patch Note over test_unit: Mock response and assert call arguments Dev->>test_integration: 3. Add integration test Note over test_integration: Call real API and assert response structure Dev->>README_md: 4. Update API Coverage table ``` 1. **Add Method to `PeachWrapper`**: In `main.py`, add a new public method to the `PeachWrapper` class. The method should call `self.__send_request` with the correct HTTP method, sub-URL, data, and authentication requirements. 2. **Add Unit Test**: In `test_peach_wrapper.py`, create a new test function that uses `@patch.object(PeachWrapper, '_PeachWrapper__send_request')` to mock the API call. Assert that `mock_request` was called with the expected arguments. 3. **Add Integration Test**: In `test_integration.py`, add a test that calls your new method on an `authenticated_wrapper` or `public_wrapper` instance. Assert that the response from the real API is structured as expected. Mark it as `@pytest.mark.slow` if it modifies data. 4. **Update Documentation**: In `README.md`, add a new row to the appropriate "API Coverage" table to reflect the new endpoint and its corresponding wrapper method. Sources: [main.py](), [test_peach_wrapper.py](), [test_integration.py](), [README.md:65-201]() ## Summary Contributions are welcome and essential for keeping the wrapper up-to-date with the Peach API. By following the established patterns for code structure, documentation, and especially testing, you can ensure your contributions are integrated smoothly. Always ensure your changes pass both the unit and integration test suites before submitting a pull request.