iziproxy 0.4.0__tar.gz → 0.4.2__tar.gz

iziproxy-0.4.2/PKG-INFO

@@ -0,0 +1,398 @@
+Metadata-Version: 2.4
+Name: iziproxy
+Version: 0.4.2
+Summary: Une bibliothèque Python pour la gestion simplifiée des proxys d'entreprise
+Author: sanjuant
+License: MIT License
+        
+        Copyright (c) 2025 IziProxy Contributors
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/sanjuant/iziproxy
+Project-URL: Bug Tracker, https://github.com/sanjuant/iziproxy/issues
+Keywords: proxy,enterprise,authentication,ntlm,requests,configuration,development,pac
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: keyring>=23.0.0
+Requires-Dist: cryptography>=36.0.0
+Requires-Dist: importlib_metadata>=4.0.0; python_version < "3.8"
+Provides-Extra: ntlm
+Requires-Dist: ntlm-auth>=1.5.0; extra == "ntlm"
+Requires-Dist: pycryptodomex>=3.14.1; extra == "ntlm"
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.12.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Requires-Dist: sphinx>=4.0.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# IziProxy
+
+Une bibliothèque Python pour la gestion simplifiée des proxys d'entreprise.
+
+[![PyPI version](https://img.shields.io/pypi/v/iziproxy.svg)](https://pypi.org/project/iziproxy/)
+[![Python versions](https://img.shields.io/pypi/pyversions/iziproxy.svg)](https://pypi.org/project/iziproxy/)
+[![License](https://img.shields.io/github/license/sanjuant/iziproxy.svg)](https://github.com/sanjuant/iziproxy/blob/main/LICENSE)
+
+## 🚀 Fonctionnalités
+
+- 🔍 **Détection intelligente** - Reconnaissance automatique de l'environnement (local, dev, prod)
+- 🌐 **Proxy système** - Détection automatique des configurations de proxy système et support des fichiers PAC
+- 🔐 **Gestion sécurisée** - Stockage des identifiants via keyring, variables d'environnement et fichiers .env
+- 🔄 **Support complet** - Compatible avec l'authentification basique et NTLM pour les proxys d'entreprise
+- 🛠️ **API flexible** - Multiples façons d'intégrer le proxy dans vos applications Python
+- 🔌 **Intégration transparente** - Patching dynamique du module requests pour les applications existantes
+
+## 📦 Installation
+
+Installation standard :
+```bash
+pip install iziproxy
+```
+
+Avec support NTLM (recommandé pour les environnements Windows d'entreprise) :
+```bash
+pip install iziproxy[ntlm]
+```
+
+Avec outils de développement :
+```bash
+pip install iziproxy[dev]
+```
+
+## 🚦 Utilisation rapide
+
+```python
+from iziproxy import IziProxy
+
+# Création avec détection automatique
+proxy = IziProxy()
+
+# Méthode 1: Obtenir une session requests préconfigurée
+session = proxy.create_session()
+response = session.get('https://example.com')
+
+# Méthode 2: Utiliser comme dictionnaire de proxy standard
+proxies = proxy.get_proxy_dict()
+response = requests.get('https://example.com', proxies=proxies)
+
+# Méthode 3: Configurer les variables d'environnement
+proxy.set_environment_variables()
+# Les bibliothèques qui respectent les variables d'environnement utiliseront le proxy
+# N'oubliez pas de nettoyer après utilisation avec proxy.clear_environment_variables()
+
+# Méthode 4: Patcher le module requests (monkey patching)
+proxy.patch_requests()
+# Désormais, toutes les requêtes requests utiliseront le proxy
+import requests
+response = requests.get('https://example.com')
+# Pour restaurer le comportement d'origine: proxy.unpatch_requests()
+```
+
+## ⚙️ Configuration
+
+IziProxy fonctionne sans configuration, mais vous pouvez personnaliser son comportement :
+
+### Configuration par code
+
+```python
+from iziproxy import IziProxy
+
+proxy = IziProxy(
+    proxy_url="http://proxy.example.com:8080",  # URL spécifique du proxy
+    pac_url="http://pac.example.com/proxy.pac", # URL d'un fichier PAC
+    username="user",                            # Nom d'utilisateur
+    password="pass",                            # Mot de passe
+    domain="DOMAIN",                            # Domaine (pour NTLM)
+    environment="prod",                         # Forcer l'environnement
+    debug=True                                  # Activer les logs détaillés
+)
+```
+
+### Configuration par fichier YAML
+
+Créez un fichier `iziproxy.yml` dans votre répertoire courant ou dans `~/.config/` :
+
+```yaml
+environments:
+  local:
+    proxy_url: "http://proxy.example.com:8080"
+    requires_auth: true
+    auth_type: "ntlm"                     # Authentification NTLM en local (poste Windows)
+  dev:
+    proxy_url: "http://dev-proxy.example.com:8080"
+    requires_auth: true
+    auth_type: "basic"                    # Authentification basique
+  prod:
+    proxy_url: "http://prod-proxy.example.com:8080"
+    requires_auth: false                  # Souvent pas d'authentification en prod (réseau sécurisé)
+
+environment_detection:
+  method: "auto"                          # Méthodes: auto, env_var, hostname, ip, ask
+  hostname_patterns:                      # Patterns pour la détection par hostname
+    dev: ["dev-", "-dev", "development"]
+    prod: ["prod-", "-prod", "production"]
+  hostname_regex:                         # Expressions régulières pour la détection par nom d'hôte
+    local: ["^laptop-\\w+$", "^pc-\\w+$", "^desktop-\\w+$"]
+    dev: ["^dev\\d*-", "^staging\\d*-", "^test\\d*-"]
+    prod: ["^prod\\d*-", "^production\\d*-"]
+  ip_ranges:                              # Plages IP pour la détection
+    dev: ["10.0.0.0/8"]
+    prod: ["192.168.0.0/16"]
+  env_var_name: "APP_ENV"                 # Variable d'environnement pour la détection
+
+system_proxy:
+  detect_pac: true                        # Détecter les fichiers PAC
+  detect_env_vars: true                   # Détecter les variables d'environnement
+```
+
+### Configuration des identifiants
+
+Pour la sécurité, les identifiants (nom d'utilisateur, mot de passe, domaine) ne doivent pas être stockés dans le fichier de configuration. Utilisez plutôt :
+
+#### Variables d'environnement
+
+IziProxy recherche les variables d'environnement suivantes :
+
+```bash
+# Format recommandé
+IZI_USERNAME=mon_utilisateur
+IZI_PASSWORD=mon_mot_de_passe
+IZI_DOMAIN=mon_domaine
+
+# Format alternatif (rétrocompatibilité)
+PROXY_USERNAME=mon_utilisateur
+PROXY_PASSWORD=mon_mot_de_passe
+PROXY_DOMAIN=mon_domaine
+```
+
+#### Fichier .env
+
+Vous pouvez également définir ces variables dans un fichier `.env` :
+
+```bash
+# Identifiants pour l'authentification proxy
+IZI_USERNAME=mon_utilisateur
+IZI_PASSWORD=mon_mot_de_passe
+IZI_DOMAIN=mon_domaine
+```
+
+Le fichier `.env` peut être placé :
+- Dans le répertoire courant (`./.env`)
+- Dans le répertoire de configuration utilisateur (`~/.config/.env`)
+- Dans le répertoire personnel de l'utilisateur (`~/.env`)
+
+#### Stockage sécurisé avec keyring
+
+Si un nom d'utilisateur est défini mais que le mot de passe est manquant, IziProxy tentera de récupérer le mot de passe depuis le trousseau de clés du système (via `keyring`).
+
+Lorsque vous fournissez un mot de passe la première fois, il sera automatiquement enregistré dans le trousseau de clés pour les utilisations futures.
+
+## 🧠 Fonctionnalités avancées
+
+### Authentification NTLM
+
+L'authentification NTLM est souvent utilisée dans les environnements Windows d'entreprise et nécessite une configuration spécifique :
+
+```python
+# Installation avec le support NTLM
+# pip install iziproxy[ntlm]
+
+from iziproxy import IziProxy
+
+# Configuration explicite pour NTLM
+proxy = IziProxy(
+    proxy_url="http://proxy.example.com:8080",
+    username="utilisateur",
+    password="mot_de_passe",
+    domain="DOMAIN"  # Domaine Windows requis pour NTLM
+)
+
+# Le type d'authentification est détecté automatiquement depuis la configuration
+session = proxy.create_session()
+```
+
+### Détection d'environnement
+
+IziProxy peut automatiquement détecter l'environnement d'exécution :
+
+```python
+from iziproxy import IziProxy
+
+proxy = IziProxy()
+env = proxy.get_current_environment()  # 'local', 'dev', 'prod'
+print(f"Environnement détecté : {env}")
+
+# Forcer un rafraîchissement de toutes les détections
+proxy.refresh()
+```
+
+### Récupération des informations de proxy
+
+```python
+from iziproxy import IziProxy
+
+proxy = IziProxy()
+
+# Obtenir l'hôte et le port du proxy
+host = proxy.get_proxy_host()
+port = proxy.get_proxy_port()
+print(f"Proxy : {host}:{port}")
+
+# Obtenir le dictionnaire complet
+proxy_dict = proxy.get_proxy_dict()
+print(f"Configuration complète : {proxy_dict}")
+```
+
+### Intégration avec des bibliothèques tierces
+
+L'une des fonctionnalités les plus puissantes d'IziProxy est sa capacité à s'intégrer avec des bibliothèques tierces via le monkey patching :
+
+```python
+from iziproxy import IziProxy
+
+# Patch global du module requests
+IziProxy().patch_requests()
+
+# À partir de maintenant, toutes les bibliothèques utilisant requests bénéficieront
+# automatiquement de la configuration proxy, sans modification du code source
+import requests
+import pandas as pd
+import boto3
+import any_library_using_requests
+
+# Pour restaurer le comportement d'origine
+IziProxy().unpatch_requests()
+```
+
+### Gestion du cache
+
+IziProxy met en cache les détections pour optimiser les performances. Vous pouvez contrôler ce comportement :
+
+```python
+from iziproxy import IziProxy
+
+proxy = IziProxy()
+
+# Obtenir une configuration spécifique pour une URL donnée (peut utiliser le cache)
+config = proxy.get_proxy_config(url="https://api.example.com")
+
+# Forcer un rafraîchissement du cache
+fresh_config = proxy.get_proxy_config(url="https://api.example.com", force_refresh=True)
+```
+
+### Mode débogage
+
+Pour diagnostiquer les problèmes, activez le mode débogage :
+
+```python
+from iziproxy import IziProxy
+
+# À l'initialisation
+proxy = IziProxy(debug=True)
+
+# Ou plus tard
+proxy.set_debug(enabled=True)  # Désactiver avec False
+```
+
+## 🛠️ Compatibilité
+
+IziProxy fonctionne avec Python 3.7 et versions ultérieures, et est compatible avec :
+
+- Windows, Linux et macOS
+- Proxys standards HTTP/HTTPS
+- Authentification Basic et NTLM
+- Fichiers de configuration automatique de proxy (PAC)
+- Proxys avec ou sans authentification
+
+## 📚 Exemples
+
+### Utilisation avec une API wrapper
+
+```python
+from some_api_library import ApiClient
+from iziproxy import IziProxy
+
+# Créer une session configurée
+session = IziProxy().create_session()
+
+# Utiliser cette session avec l'API
+client = ApiClient(session=session)
+```
+
+### Utilisation avec un fichier PAC
+
+```python
+from iziproxy import IziProxy
+
+# Configurer avec un fichier PAC explicite
+proxy = IziProxy(pac_url="http://intranet.example.com/proxy.pac")
+
+# Ou laisser IziProxy détecter automatiquement le fichier PAC système
+proxy = IziProxy()  # Détection automatique si disponible
+```
+
+## 🔄 Migration depuis CNTLM
+
+Si vous utilisez actuellement CNTLM, IziProxy offre une alternative 100% Python :
+
+1. Installez IziProxy avec support NTLM: `pip install iziproxy[ntlm]`
+2. Sur Windows, IziProxy détecte automatiquement votre domaine et nom d'utilisateur Windows
+3. Pour les autres systèmes, configurez vos identifiants via les variables d'environnement
+4. Utilisez IziProxy directement dans votre code Python sans avoir à configurer un proxy local
+
+La détection automatique sur Windows simplifie considérablement la transition depuis CNTLM, puisque vous n'avez généralement pas besoin de configuration supplémentaire pour l'authentification.
+
+## 🤝 Contribuer
+
+Les contributions sont les bienvenues ! Consultez notre [guide de contribution](CONTRIBUTING.md) pour plus d'informations.
+
+## 📚 Documentation
+
+Une documentation complète est disponible sur Read the Docs :
+
+[![Documentation Status](https://readthedocs.org/projects/iziproxy/badge/?version=latest)](https://iziproxy.readthedocs.io/fr/latest/?badge=latest)
+
+Visitez [iziproxy.readthedocs.io](https://iziproxy.readthedocs.io/) pour accéder à :
+- Guide de démarrage rapide
+- Exemples détaillés
+- Documentation complète de l'API
+- Guides de migration
+- Tutoriels et cas d'usage
+
+## 📄 Licence
+
+Ce projet est sous licence MIT - voir le fichier [LICENSE](LICENSE) pour plus de détails.
+
+---
+
+Développé avec ❤️ pour simplifier la vie des développeurs dans les environnements d'entreprise.