Pacchetto PyPI: olostep | Requisiti: Python 3.11+
Installazione
Autenticazione
Ottieni la tua chiave API dal Dashboard di Olostep.Inizio Rapido
L’SDK fornisce due opzioni di client a seconda del tuo caso d’uso:Client Sincrono (`Olostep`)
Ideale per: Script e casi d’uso semplici dove preferisci operazioni bloccanti.
Il client sincrono offre un’interfaccia più semplice e bloccante, più facile da iniziare se sei nuovo a async/await.
Il client sincrono offre un’interfaccia più semplice e bloccante, più facile da iniziare se sei nuovo a async/await.
Client Asincrono (`AsyncOlostep`)
Ideale per: Applicazioni in produzione e gestione di molte richieste concorrenti.
Il client asincrono offre operazioni non bloccanti ed è la scelta consigliata per applicazioni in produzione che necessitano di un alto throughput.
Il client asincrono offre operazioni non bloccanti ed è la scelta consigliata per applicazioni in produzione che necessitano di un alto throughput.
Client Sincrono (Olostep)
Il client sincrono (Olostep) fornisce un’interfaccia bloccante perfetta per script e casi d’uso semplici.
Web Scraping di Base
Elaborazione in Batch
Web Crawling Intelligente
Mappatura del Sito
Risposte Potenziate dall’AI
Client Asincrono (AsyncOlostep)
Il client asincrono (AsyncOlostep) è il client consigliato per applicazioni ad alte prestazioni, servizi backend e quando hai bisogno di gestire molte richieste concorrenti.
Web Scraping di Base
Elaborazione in Batch
Web Crawling Intelligente
Mappatura del Sito
Risposte Potenziate dall’AI
Riferimento SDK
Struttura dei Metodi
Entrambi i client SDK forniscono la stessa interfaccia pulita e pythonica organizzata in spazi dei nomi logici:| Namespace | Scopo | Metodi Chiave |
|---|---|---|
scrapes | Estrazione singolo URL | create(), get() |
batches | Elaborazione multi-URL | create(), info(), items() |
crawls | Traversata del sito | create(), info(), pages() |
maps | Estrazione link | create(), urls() |
answers | Estrazione potenziata dall’AI | create(), get() |
retrieve | Recupero contenuti | get() |
Gestione degli Errori
Cattura tutti gli errori SDK utilizzando la classe di eccezione base:Riprovi Automatici
L’SDK riprova automaticamente in caso di errori transitori (problemi di rete, problemi temporanei del server) basati sulla configurazione diRetryStrategy. Puoi personalizzare il comportamento di riprova passando un’istanza di RetryStrategy quando crei il client:
Funzionalità Avanzate
Coercizione Intelligente degli Input
L’SDK gestisce in modo intelligente vari formati di input per la massima comodità:Opzioni Avanzate di Scraping
Elaborazione in Batch con ID Personalizzati
Crawling Intelligente
Mappatura del Sito con Filtri
Recupero delle Risposte
Recupero dei Contenuti
Logging
Abilita il logging per eseguire il debug dei problemi:INFO (consigliato), DEBUG (verboso), WARNING, ERROR
Configurazione della Strategia di Riprova
La classeRetryStrategy controlla come l’SDK Olostep gestisce gli errori API transitori tramite riprove automatiche con backoff esponenziale e jitter. Questo aiuta a garantire un funzionamento affidabile in ambienti di produzione dove problemi di rete temporanei, limiti di velocità e sovraccarico del server possono causare fallimenti intermittenti.
Comportamento Predefinito
Per impostazione predefinita, l’SDK utilizza la seguente configurazione di riprova:- Max riprove: 5 tentativi
- Ritardo iniziale: 2 secondi
- Backoff: Esponenziale (2^tentativo)
- Jitter: 10-90% del ritardo (randomizzato)
- Tentativo 1: Immediato
- Tentativo 2: ~2-3.6s di ritardo
- Tentativo 3: ~4-7.2s di ritardo
- Tentativo 4: ~8-14.4s di ritardo
- Tentativo 5: ~16-28.8s di ritardo
Configurazione Personalizzata
Quando Avvengono le Riprova
L’SDK riprova automaticamente su:- Problemi temporanei del server (
OlostepServerError_TemporaryIssue) - Risposte di timeout (
OlostepServerError_NoResultInResponse)
Riprova di Trasporto vs Chiamante
L’SDK ha due livelli di riprova:- Livello di trasporto: Gestisce i fallimenti di connessione a livello di rete (DNS, timeout, ecc.)
- Livello di chiamante: Gestisce gli errori transitori a livello di API (controllato da
RetryStrategy)
Calcolare la Durata Massima
Esempi di Configurazione
Ecco alcuni esempi di come configurare la strategia di riprova per diversi casi d’uso.Strategia Conservativa
Strategia Aggressiva
Nessuna Riprova (Fallimento Immediato)
Strategia ad Alto Throughput
Comprendere il Jitter
Il jitter aggiunge randomizzazione per prevenire problemi di “thundering herd” quando molti client riprovano contemporaneamente. Il jitter è calcolato come:initial_delay=2.0, jitter_min=0.1, jitter_max=0.9:
- Tentativo 0: base=2.0s, jitter=0.2-1.8s, finale=2.2-3.8s
- Tentativo 1: base=4.0s, jitter=0.4-3.6s, finale=4.4-7.6s
- Tentativo 2: base=8.0s, jitter=0.8-7.2s, finale=8.8-15.2s
Migliori Pratiche
Per Applicazioni in Produzione
Per Sviluppo/Test
Per Operazioni in Batch
Monitoraggio e Debug
L’SDK registra le informazioni di riprova al livello DEBUG:Gestione degli Errori
Quando tutte le riprove sono esaurite, viene sollevato l’errore originale:Considerazioni sulle Prestazioni
- Memoria: Ogni tentativo di riprova utilizza memoria aggiuntiva per oggetti di richiesta/risposta
- Tempo: Il tempo totale dell’operazione può essere significativamente più lungo con le riprove abilitate
- Limiti API: Le riprove contano contro i tuoi limiti di utilizzo dell’API
- Rete: Più traffico di rete a causa dei tentativi di riprova
Gestione Dettagliata degli Errori
Gerarchia delle Eccezioni
L’SDK Olostep fornisce una gerarchia completa di eccezioni per diversi scenari di fallimento. Tutte le eccezioni ereditano daOlostep_BaseError.
Ci sono tre tipi principali di errori che ereditano direttamente da Olostep_BaseError:
Olostep_APIConnectionError- Fallimenti di connessione a livello di reteOlostepServerError_BaseError- Errori sollevati (in qualche modo) dal server APIOlostepClientError_BaseError- Errori sollevati dal client SDK
Perché gli Errori di Connessione Sono Separati
Olostep_APIConnectionError è separato dagli errori del server perché rappresenta fallimenti a livello di rete che si verificano prima che l’API possa elaborare la richiesta. Questi sono problemi a livello di trasporto (fallimenti DNS o HTTP, timeout, connessione rifiutata, ecc.) piuttosto che errori a livello di API. I codici di stato HTTP (4xx, 5xx) sono considerati risposte API e sono categorizzati come errori del server, anche se indicano problemi.
Gestione degli Errori Consigliata
Per la maggior parte dei casi d’uso, cattura l’errore base e stampa il nome dell’errore:OlostepServerError_AuthFailed) è abbastanza descrittivo per comprendere il problema.
Gestione degli Errori Granulare
Se hai bisogno di una gestione degli errori più specifica, cattura direttamente i tipi di errore specifici. Evita di usareOlostepServerError_BaseError o OlostepClientError_BaseError - queste classi base indicano solo chi ha sollevato l’errore (server vs client), non chi è responsabile di risolverlo. Questo è un dettaglio di implementazione che non aiuta con la logica di gestione degli errori.
Invece, cattura i tipi di errore specifici che indicano il problema reale:
Configurazione
Variabili d’Ambiente
| Variabile | Descrizione | Predefinito |
|---|---|---|
OLOSTEP_API_KEY | La tua chiave API | Richiesto |
OLOSTEP_BASE_API_URL | URL base dell’API | https://api.olostep.com/v1 |
OLOSTEP_API_TIMEOUT | Timeout della richiesta (secondi) | 150 |
Ottenere Aiuto
Risorse
Pacchetto PyPI
Visualizza su PyPI
Ottieni Chiave API
Iscriviti gratuitamente