Iniziale implementazione API Directa con supporto simulazione

Author: NiccoloSalvini

.github/workflows/python-tests.yml

@@ -0,0 +1,29 @@
+name: Python Tests
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.7, 3.8, 3.9, '3.10']
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pytest pytest-cov
+        pip install -e .
+    - name: Test with pytest
+      run: |
+        pytest tests/ --cov=directa_api 

.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+.env
+.venv
+venv/
+ENV/
+.coverage
+.pytest_cache/
+
+# IDE and editor files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Local configs
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Directa specific
+*.session
+credentials.json 

.python-version

@@ -0,0 +1 @@
+3.10.4

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Niccolò Salvini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,100 @@
+# Directa Trading API
+
+Un wrapper Python per interagire con l'API Trading di Directa SIM tramite la piattaforma Darwin.
+
+## Caratteristiche
+
+- Connessione all'API Trading di Directa SIM (porta 10002)
+- Gestione automatica della connessione e monitoraggio dello stato
+- Supporto per le operazioni di base (acquisto/vendita, cancellazione ordini)
+- Supporto per query di portfolio, disponibilità e informazioni account
+- Modalità simulazione per testare operazioni senza utilizzare denaro reale
+- Parser dettagliati per le risposte dell'API
+
+## Installazione
+
+```bash
+git clone https://github.com/TUOUSERNAME/directa-api-python.git
+cd directa-api-python
+pip install -e .
+```
+
+## Requisiti
+
+- Python 3.7+
+- Piattaforma di trading Darwin in esecuzione
+
+## Utilizzo base
+
+```python
+from directa_api import DirectaTrading
+
+# Connessione all'API
+api = DirectaTrading()
+if api.connect():
+    # Verifica dello stato
+    status = api.get_darwin_status()
+    print(f"Stato connessione: {status['data']['connection_status']}")
+    
+    # Ottieni informazioni account
+    account = api.get_account_info()
+    print(f"Codice account: {account['data']['account_code']}")
+    print(f"Liquidità: {account['data']['liquidity']}")
+    
+    # Ottieni portfolio
+    portfolio = api.get_portfolio()
+    if portfolio['success']:
+        for position in portfolio['data']:
+            print(f"{position['symbol']}: {position['quantity_portfolio']} azioni")
+    
+    # Chiusura connessione
+    api.disconnect()
+```
+
+## Modalità Simulazione
+
+È possibile utilizzare la modalità simulazione per testare operazioni senza utilizzare denaro reale:
+
+```python
+# Crea un'istanza in modalità simulazione
+api = DirectaTrading(simulation_mode=True)
+api.connect()
+
+# Simula acquisto di azioni
+order = api.place_order("INTC", "BUY", 100, 50.25)
+order_id = order["data"]["order_id"]
+
+# Simula esecuzione dell'ordine
+api.simulate_order_execution(order_id, executed_price=50.00)
+
+# Verifica portfolio simulato
+portfolio = api.get_portfolio()
+print(portfolio)
+
+# Chiusura
+api.disconnect()
+```
+
+Vedere `examples/simulation_example.py` per un esempio completo.
+
+## Esempi
+
+Nella directory `examples` sono presenti diversi script di esempio:
+
+- `trading_example.py`: Esempio base di utilizzo dell'API
+- `simulation_example.py`: Esempio di utilizzo della modalità simulazione
+- `raw_socket_test.py`: Test di connessione socket semplice per diagnostica
+
+## Note sull'API Directa
+
+- L'API Trading di Directa è accessibile solo quando la piattaforma Darwin è in esecuzione
+- L'API utilizza la porta 10002 per le operazioni di trading
+- È necessario avere un account Directa attivo per utilizzare l'API in modalità reale
+
+## Licenza
+
+Questo progetto è distribuito con licenza MIT. Vedere il file `LICENSE` per i dettagli.
+
+## Disclaimer
+
+Questo software è fornito "così com'è", senza garanzie di alcun tipo. L'autore e i contributori non sono responsabili per eventuali perdite finanziarie derivanti dall'uso di questo software. Utilizzare a proprio rischio e pericolo. Non è affiliato ufficialmente a Directa SIM.

directa_api/__init__.py

@@ -0,0 +1,10 @@
+from directa_api.trading import DirectaTrading
+from directa_api.errors import ERROR_CODES, ORDER_STATUS_CODES, get_error_message, get_order_status
+
+__all__ = [
+    'DirectaTrading',
+    'ERROR_CODES',
+    'ORDER_STATUS_CODES',
+    'get_error_message',
+    'get_order_status'
+] 

directa_api/errors.py

@@ -0,0 +1,125 @@
+"""
+Error codes and messages for Directa Trading API
+"""
+
+ERROR_CODES = {
+    "0": "ERR_UNKNOWN - Errore generico",
+    "1000": "ERR_MAX_SUBSCRIPTION_OVERFLOW - Limite massimo di titoli sottoscritti raggiunto",
+    "1001": "ERR_ALREADY_SUBSCRIBED - Titolo richiesto già sottoscritto",
+    "1002": "ERR_EMPTY_LIST - Nessun titolo inviato nel comando",
+    "1003": "ERR_UNKNOWN_COMMAND - Comando sconosciuto",
+    "1004": "ERR_COMMAND_NOT_EXECUTED - Comando non eseguito",
+    "1005": "ERR_NOT_SUBSCRIBED - Errore sottoscrizione",
+    "1006": "ERR_DARWIN_STOP - Chiusura Darwin in corso",
+    "1007": "ERR_BAD_SUBSCRIPTION - Errore titolo inesistente",
+    "1008": "ERR_DATA_UNAVAILABLE - Flusso richiesto non disponibile",
+    "1009": "ERR_TRADING_CMD_INCOMPLETE - Comando trading non completo",
+    "1010": "ERR_TRADING_CMD_ERROR - Comando trading errato",
+    "1011": "ERR_TRADING_UNAVAILABLE - Trading non abilitato",
+    "1012": "ERR_TRADING_REQUEST_ERROR - Errore immissione ordine",
+    "1013": "ERR_HISTORYCALL_PARAMS - Errore numero paramentri nel comando",
+    "1015": "ERR_HISTORYCALL_RANGE_INTRADAY - Errore range per chiamate intraday",
+    "1016": "ERR_HISTORYCALL_DAY_OR_RANGE - Errore nei giorni o nel range date nel comando inviato",
+    "1018": "ERR_EMPTY_STOCKLIST - Nessuno strumento nel portafoglio",
+    "1019": "ERR_EMPTY_ORDERLIST - Nessun ordine presente",
+    "1020": "ERR_DUPLICATED_ID - ID Ordine duplicato",
+    "1021": "ERR_INVALID_ORDER_STATE - Stato ordine incongruente con l'operazione richiesta",
+    "1024": "ERR_TRADING_PUSH_DISCONNECTED - Segnala la disconnessione del trading",
+    "1025": "ERR_TRADING_PUSH_RECONNECTION_OK - Segnale di riconnessione",
+    "1026": "ERR_TRADING_PUSH_RELOAD - Segnala il reload del trading",
+    "1027": "ERR_DATAFEED_DISCONNECTED - Segnala la disconessione del datafeed",
+    "1028": "ERR_DATAFEED_RELOAD - Segnala il reload del datafeed",
+    "1030": "ERR_MARKET_UNAVAILABLE - Mercato non abilitato per il ticker richiesto",
+    "1031": "CONTATTO_NON_ATTIVO - Contatto verso il nostro server di trading scaduto, necessario riavviare l'applicazione",
+    "1032": "DATAFEED NON ABILITATO - Quotazioni non abilitate"
+}
+
+ORDER_STATUS_CODES = {
+    "2000": "In negoziazione",
+    "2001": "Errore immissione",
+    "2002": "In negoziazione dopo conferma ricevuta",
+    "2003": "Eseguito",
+    "2004": "Revocato",
+    "2005": "In attesa di conferma",
+    "2006": "Modificato"
+}
+
+def get_error_message(error_code: str) -> str:
+    """
+    Get the error message for an error code
+    
+    Args:
+        error_code: The error code
+        
+    Returns:
+        The error message or a generic message if not found
+    """
+    if error_code in ERROR_CODES:
+        return ERROR_CODES[error_code]
+    return f"Codice errore sconosciuto: {error_code}"
+
+def get_order_status(status_code: str) -> str:
+    """
+    Get the order status description for a status code
+    
+    Args:
+        status_code: The status code
+        
+    Returns:
+        The status description or a generic message if not found
+    """
+    if status_code in ORDER_STATUS_CODES:
+        return ORDER_STATUS_CODES[status_code]
+    return f"Stato ordine sconosciuto: {status_code}"
+
+def is_error_response(response: str) -> bool:
+    """
+    Check if a response is an error response
+    
+    Args:
+        response: The API response
+        
+    Returns:
+        True if it's an error response, False otherwise
+    """
+    return response.strip().startswith("ERR;") or response.strip()[0:4].isdigit() and response.strip()[4] == ":"
+
+def parse_error_response(response: str) -> dict:
+    """
+    Parse an error response into a JSON-compatible dictionary
+    
+    Args:
+        response: The error response string
+        
+    Returns:
+        A dictionary with error information in JSON format
+    """
+    # Handle the format ERR;CMD;ERROR_CODE
+    if response.strip().startswith("ERR;"):
+        parts = response.strip().split(';')
+        if len(parts) >= 3:
+            error_code = parts[2]
+            return {
+                "success": False,
+                "error_code": error_code,
+                "error_message": get_error_message(error_code),
+                "raw_response": response
+            }
+    
+    # Handle the format ERROR_CODE:ERROR_MESSAGE
+    elif response.strip()[0:4].isdigit() and response.strip()[4] == ":":
+        error_code = response.strip()[0:4]
+        return {
+            "success": False,
+            "error_code": error_code,
+            "error_message": get_error_message(error_code),
+            "raw_response": response
+        }
+    
+    # Generic error format
+    return {
+        "success": False,
+        "error_code": "unknown",
+        "error_message": "Formato di errore sconosciuto",
+        "raw_response": response
+    }