Configura le impostazioni del modulo mssql-python

Il driver mssql-python fornisce una Settings classe che controlla il comportamento a livello di modulo. Queste impostazioni influenzano tutte le connessioni e le operazioni del cursore. Configurali una volta all'avvio dell'applicazione, prima di creare qualsiasi connessione.

Impostazioni di accesso

Recupera l'oggetto corrente Settings e ispeziona o modifica le sue proprietà:

import mssql_python

# Get settings object
settings = mssql_python.get_settings()

# Check current values
print(settings.lowercase)
print(settings.decimal_separator)

Impostazioni disponibili

Le seguenti impostazioni controllano come il driver restituisce i dati e formatta i risultati.

Minuscolo

L'impostazione lowercase controlla se i nomi delle colonne in cursor.description appaiono in minuscolo. Abilita questa impostazione quando la tua applicazione accede alle colonne per nome e vuoi evitare disallineamenti di maiuscole. Framework web come Flask e FastAPI spesso convertono le righe in dizionari, il che rende importante la coerenza nell’uso di maiuscole e minuscole:

settings = mssql_python.get_settings()

# Enable lowercase column names (default: False)
settings.lowercase = True

# Column names in cursor.description are now lowercased:
# ('productid', ...) instead of ('ProductID', ...)

Separatore decimale

Il driver fornisce funzioni a livello di modulo per controllare il separatore decimale per conversioni numeriche. Cambia questa impostazione solo se la tua istanza di SQL Server utilizza una località con una virgola come separatore decimale, come località francesi o tedesche. La maggior parte delle applicazioni non deve modificare questa impostazione:

import mssql_python

# Get current separator
sep = mssql_python.getDecimalSeparator()
print(f"Current separator: {sep}")  # Usually "."

# Set custom separator (for locales using comma)
mssql_python.setDecimalSeparator(",")

Per maggiori informazioni sulla gestione decimale, vedi Data Type Mapings.

native_uuid

L'impostazione native_uuid determina se UNIQUEIDENTIFIER le colonne vengono restituite come oggetti Python uuid.UUID o come stringhe maiuscole compatibili con pyodbc. Questa impostazione è utile per i team che migrano da pyodbc e dipendono dai valori UUID della stringa:

settings = mssql_python.get_settings()

# Return UUIDs as uuid.UUID objects (default: True)
settings.native_uuid = True

# Return UUIDs as uppercase strings (pyodbc-compatible)
settings.native_uuid = False

Puoi anche impostare native_uuid per connessione:

# Override for a specific connection
conn = mssql_python.connect(connection_string, native_uuid=False)

Costanti a livello di modulo

Il driver espone costanti di sola lettura di conformità a DB-API 2.0 che ne descrivono le funzionalità. Usa queste costanti per scrivere codice che si adatta a diversi driver DB-API:

import mssql_python

# DB-API 2.0 compliance level
print(mssql_python.apilevel)      # '2.0'

# Thread safety level
print(mssql_python.threadsafety)  # 1

# Parameter style
print(mssql_python.paramstyle)    # 'pyformat'

Apilevel

Il apilevel costante riporta il livello di conformità DB-API:

Sicurezza della filettatura

Il threadsafety costante riporta il livello di sicurezza del thread:

Il driver mssql-python usa threadsafety = 1, che significa:

• Puoi importare e usare il modulo tra thread.
• Ogni connessione deve appartenere a un solo thread alla volta.
• Crea una connessione separata per thread, oppure usa un pool di connessione (abilitato di default). Per maggiori informazioni, vedere pool di connessioni.

paramstyle

La paramstyle costante riporta il formato segnaposto dei parametri:

Il driver mssql-python utilizza paramstyle = 'pyformat'. Usa sempre parametri nominati per prevenire l'iniezione SQL. Non creare mai query con input dell'utente tramite la formattazione di stringhe o le f-string:

# Use named parameters with %(name)s syntax
cursor.execute(
    "SELECT * FROM Production.Product WHERE ProductSubcategoryID = %(cat)s AND ListPrice > %(price)s",
    {"cat": 5, "price": 10.00}
)

Informazioni sulla versione

Controlla quale versione del driver è installata:

import mssql_python

# Driver version
print(mssql_python.__version__)  # e.g., '1.5.0'

Configura le impostazioni all'avvio

Imposta la configurazione del modulo una volta all'avvio dell'applicazione, prima di creare qualsiasi connessione. Impostare i valori precocemente previene comportamenti incoerenti tra le connessioni:

import mssql_python

def configure_driver():
    """Configure mssql-python settings for this application."""
    settings = mssql_python.get_settings()
    
    # Use lowercase column names in cursor.description
    settings.lowercase = True

# Call at application startup
configure_driver()

# All subsequent connections use these settings
conn = mssql_python.connect(connection_string)

Considerazioni sulla sicurezza della filettatura

Le impostazioni del modulo sono globali e influenzano tutte le connessioni tra tutti i thread. Se cambi un'impostazione dopo che le connessioni sono già aperte, le connessioni esistenti potrebbero non riflettere il cambiamento in modo coerente. Imposta tutti i valori di configurazione prima di creare la tua prima connessione:

import mssql_python
import threading

# Settings changes affect all threads
settings = mssql_python.get_settings()
settings.lowercase = True  # Affects all connections in all threads

def worker():
    # This connection uses the global settings
    conn = mssql_python.connect(connection_string)
    cursor = conn.cursor()
    cursor.execute("SELECT Name FROM Production.Product")
    row = cursor.fetchone()
    print(cursor.description[0][0])  # 'name' due to global setting

threads = [threading.Thread(target=worker) for _ in range(5)]
for t in threads:
    t.start()
for t in threads:
    t.join()

Configurazione specifica per la connessione

Puoi sovrascrivere alcune impostazioni per connessione senza cambiare il valore predefinito globale. Usa override specifici per connessione quando parti diverse della tua applicazione necessitano di comportamenti diversi. Ad esempio, un modulo di report potrebbe aver bisogno di UUID stringa mentre il resto dell'applicazione utilizza uuid.UUID oggetti:

# Per-connection native_uuid override
conn = mssql_python.connect(connection_string, native_uuid=False)

# Use the autocommit property
conn.autocommit = True

Contenuti correlati

• Stringhe di connessione
• Gestione delle connessioni
• Mapping dei tipi di dati