11.3 `urllib` --- Ouvre des ressources quelconques d'après l'URL

Ce module fournit une interface de haut niveau pour récupérer des données sur le Web. En particulier, la fonction urlopen() est similaire à la fonction intégrée open(), mais accepte les Universal Resource Locators (URLs) au lieu des noms de fichiers. Certaines restrictions s'appliquent - on ne peut ouvrir des URL qu'en lecture, et on ne peut pas effectuer d'opération de recherche.

Il définit les fonctions publiques suivantes:

urlopen(url[, data])

Ouvre un objet réseau désigné par son URL en lecture. Si l'URL n'a pas d'identificateur de protocole, ou si cet identificateur est file:, la fonction ouvre un fichier local; sinon elle ouvre une socket vers un serveur quelque part sur le réseau. Si la connection ne paut pas être établie, ou si le serveur renvoie un code d'erreur, l'exception IOError est déclenchée. Si tout s'est bien passé, un objet de type fichier est retourné. On peut lui appliquer les méthodes suivantes: read(), readline(), readlines(), fileno(), close(), info() et geturl().

Sauf pour les méthodes info() et geturl(), ces méthodes ont la même interface que les objets fichiers - voir la section 2.1.7.9 dans ce manuel. (Ce n'est pas un vrai objet fichier intégré, cependant, donc on ne peut pas s'en servir dans les quelques rares cas où il faut un vrai objet fichier intégré.)

La méthode info() retourne une instance de la classe mimetools.Message contenant des méta-informations associées à l'URL. Quand le protocole est HTTP, ces entêtes sont ceux renvoyés par le serveur au début de la page HTML récupérée (y compris Content-Length et Content-Type). Quand le protocole est FTP, un entête Content-Length sera présent si (comme c'est maintenant habituel) le serveur a envoyé une longueur de fichier en réponse à la requête de récupération FTP. Quand le protocole est file (fichier local), les entêtes renvoyés incluent une Date, représentant la date de dernière modification du fichier, un Content-Length qui donne la taille du fichier, et un Content-Type qui est un pronostic sur le type de fichier. Voir aussi la description du module mimetools.

La méthode geturl() retourne l'URL réelle de la page. Dans certains cas, le serveur HTTP redirige un client vers une autre URL. La fonction urlopen() gère ceci de façon transparente, mais dans certains cas l'appelant a besoin de ssavoir vers quelle URL le client a été redirigé. La méthode geturl() sert à connaître cette URL redirigée.

Si l'url utilise l'identificateur http:, on peut donner l'argument optionnel data pour spécifier une requête POST (normalement le type de requête est GET). L'argument data doit être dans le format standard application/x-www-form-urlencoded; voir la fonction urlencode() ci-dessous.

La fonction urlopen() marche de façon transparente avec les proxies qui ne requièrent pas l'authentification. Dans un environnement Unix ou Windows, donnez aux variables d'environnement $http_proxy, $ftp_proxy ou $gopher_proxy la valeur d'une URL qui identifie le serveur proxy avant de lancer l'interpréteur Python. Par exemple (le caractère "%" est l'invite de commande):

...

Dans un environnement Macintosh, urlopen() retrouvera l'information sur le proxy depuis Internet Config.

Les proxies qui requièrent l'authentification pour fonctionner ne sont pas pris en compte pour l'instant; ceci est considéré comme une limitation de l'implémentation.

urlretrieve(url[, nomfichier[, accroche]])

Copie un objet réseau désigné par une URL dans un fichier local, si nécessaire. Si l'URL pointe vers un fichier local, ou qu'une copie cachée valide de l'objet existe, l'objet n'est pas copié. Retourne un tuple (nomfichier, entetes) où nomfichier est le nom du fichier local sous lequel on peut trouver l'objet, et entetesest soit None (pour un objet local), soit ce que la méthode info() de l'objet retourné par urlopen() donne comme résultat (pour un objet distant, éventuellement caché). Les exceptions sont les mêmes que pour urlopen().

Le second argument, s'il est présent, spécifie l'emplacement du fichier vers lequel copier (s'il est absent, l'emplacement sera un fichier temporaire avec un nom généré par le système). Le troisième argument, s'il est présent, est une fonction d'accroche qui sera appelée une fois à l'établissement de la connexion réseau et une fois après chaque lecture de bloc ultérieure. On passera à la fonction d'accroche trois arguments: un compteur du nombre de blocs transférés jusque là, une taille de bloc en octets, et la taille totale du bloc. Le troisième argument peut valoir -1 sur les anciens serveurs FTP qui ne renvoient pas une taille de fichier en réponse à une requête de récupération.

urlcleanup()

Efface le cache qui peut avoir été constitué par des appels précédents à urlretrieve().

quote(chaine[, garde])

Remplace les caractères spéciaux dans chaine en utilisant l'échappement par "%xx". Les lettres, les chiffres et les caractères "_,.-" ne sont jamais remplacés. Le paramètre optionnel garde spécifie des caractères supplémentaires qui ne doivent pas être remplacés - sa valeur par défaut est '/'.

Exemple: quote('/~connolly/') produit '/%7econnolly/'.

quote_plus(chaine[, garde])

Comme quote(), mais remplace aussi les espaces par des signes plus, comme c'est requis pour coder les valeurs dans les formulaires HTML. Les signes plus dans la chaîne d'origine sont échappés, sauf s'ils sont inclus dans garde.

unquote(chaine)

Remplace les échappements "%xx" par leur équivalent sur un seul caractère.

Exemple: unquote('/%7Econnolly/') produit '/~connolly/'.

unquote_plus(chaine)

Comme unquote(), mais remplace aussi les signes plus par des espaces, comme c'est requis pour décoder les valeurs dans les formulaires HTML.

urlencode(dict)

Convertit un dictionnaire en une chaîne ``url-encodée'', propre à être passé à la fonction urlopen() ci-dessus comme argument optionnel data. Ceci est utile pour passer un dictionnaire de champs de formulaire à une requête POST. La chaîne résultante est une série de paires cle=valeur séparatées par des caractères "&", où cle et valeur sont codées avec la fonction quote_plus() ci-dessus.

Les fonctions publiques urlopen() et urlretrieve() créent une instance de la classe FancyURLopener et l'utilisent pour effectuer les actions demandées. Pour surcharger cette fonctionnalité, les programmeurs peuvent créer une classe dérivée de URLopener ou FancyURLopener, puis assigner une instance de cette classe comme valeur de la variable urllib._urlopener avant d'appeler la fonction désirée. Par exemple, les applications peuvent demander à spécifier un entête user-agent différent de celui que URLopener définit. Ceci peut être réalisé avec le code suivant:

class AppURLopener(urllib.FancyURLopener):
    def __init__(self, *args):
        self.version = "App/1.7"
        apply(urllib.FancyURLopener.__init__, (self,) + args)


urllib._urlopener = AppURLopener()

URLopener([proxies[, **x509]]): Classe de base class pour ouvrir et lire des URLs. Sauf si vous avez besoin de prendre en charge des objets utilisant d'autres schémas que http:, ftp:, gopher: ou file:, vous préfèrerez probablement utiliser FancyURLopener.
Par défaut, la classe URLopener envoie comme entête user-agent "urllib/VVV", où VVV est le numéro de version de urllib. Les applications peuvent définir leur propre entête user-agent en dérivant URLopener ou FancyURLopener et en donnant à l'attribut d'instance version la valeur appropriée avant d'appeler la méthode open().
Des mots-clés supplémentaires, rassemblés dans x509, servent à l'authentification pour le protocole https:. Les mos-clés key_file et cert_file sont pris en charge; les deux sont nécessaires pour récupérer effectivement une ressource désignée par une URL https:.

FancyURLopener(...): FancyURLopener est dérivée de URLopener et fournit une gestion par défaut des codes de réponse HTTP suivants: 301, 302 ou 401. Pour les codes de réponse 301 et 302, l'entête location sert à récupérer l'URL effective. Pour les codes de réponse 401 (authentification requise), une authentification HTTP basique est effectuée.
Les paramètres pour le constructeur sont les mêmes que pour URLopener.

Restrictions:

Pour l'instant, seuls les protocoles suivants sont pris en charge: HTTP (versions 0.9 et 1.0), Gopher (mais pas Gopher-+), FTP, et les fichiers locaux.
La fonctionnalité de cache de urlretrieve() a été désactivée jusqu'à ce que je trouve le temps de bidouiller un traitement correct des entêtes de temps d'expiration.
Il faudrait une fonction pour demander si une URL donnée est dans le cache.
Pour la compatibilité ascendante, si une URL pointe vers un fichier local mais que le fichier ne peut pas être ouvert, l'URL est réinterprétée en utilisant le protocole FTP. Ceci peut parfois produire des messages d'erreur déroutants.
Les fonctions urlopen() et urlretrieve() peuvent occasionner des temps d'attente d'une longueur arbitraire pendant l'établissement d'une connection réseau. Par conséquent, il est difficile de créer un client web interactif à partir de ces fonctions sans se servir des threads.
Les données retournées par urlopen() ou urlretrieve() sont les données brutes retournées par le serveur. Il peut s'agir de données binaires (par exemple une image), de texte simple ou (par exemple) de HTML HTML . Le protocole HTTP fournit le type d'information dans l'entête de la réponse, qu'on peut analyser en regardant l'entête content-type. Pour le protocole Gopher , le type d'information est encodé dans l'URL; il n'y a pas pour l'instant de moyen simple de l'extraire. Si les données retournées sont du HTML, vous pouvez utiliser le module htmllib pour les analyser.
Ce module ne prend pas en charge l'utilisation des proxies qui requièrent l'authentification. Il se peut que ceci soit implémenté dans le futur.
Bien que le module urllib contienne des routines (non documentées) pour analyser et encoder des chaînes d'URL, l'interface recommandée pour la manipulation des URL est dans le module urlparse.

Sous-sections

11.3 urllib --- Ouvre des ressources quelconques d'après l'URL

11.3 `urllib` --- Ouvre des ressources quelconques d'après l'URL