PyNextcloud/README.md

PyNextcloud - API FastAPI pour Nextcloud

API REST construite avec FastAPI pour interagir avec un serveur Nextcloud et lister les fichiers et dossiers.

📋 Prérequis

• Python 3.8 ou supérieur
• Un serveur Nextcloud avec accès API
• Identifiants Nextcloud (username et password)

🚀 Installation

1. Créer un environnement virtuel

# Créer l'environnement virtuel
python -m venv venv

# Activer l'environnement virtuel
.\venv\Scripts\Activate.ps1

2. Installer les dépendances

pip install -r requirements.txt

3. Configuration

Créez un fichier .env à la racine du projet (vous pouvez copier env.example) :

Copy-Item env.example .env

Modifiez le fichier .env avec vos informations Nextcloud :

NEXTCLOUD_URL=https://votre-serveur-nextcloud.com
NEXTCLOUD_USERNAME=votre_username
NEXTCLOUD_PASSWORD=votre_password

APP_HOST=0.0.0.0
APP_PORT=8000

🎯 Utilisation

Démarrer le serveur

# Méthode 1 : Avec uvicorn directement
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Méthode 2 : Avec Python
python main.py

Le serveur démarre sur http://localhost:8000

Documentation interactive

Une fois le serveur démarré, accédez à :

• Documentation Swagger UI : http://localhost:8000/docs
• Documentation ReDoc : http://localhost:8000/redoc

📡 Endpoints disponibles

1. Route racine

GET /

Retourne un message d'accueil et le lien vers la documentation.

2. Health Check

GET /health

Vérifie l'état de l'API et la connexion à Nextcloud.

Réponse exemple :

{
  "status": "healthy",
  "nextcloud_connected": true
}

3. Lister un répertoire

GET /list/{path}

Liste tous les fichiers et dossiers d'un répertoire Nextcloud.

Paramètres :

• path : Chemin du répertoire (utilisez / pour la racine)

Exemples :

# Lister la racine
curl http://localhost:8000/list/

# Lister le dossier Documents
curl http://localhost:8000/list/Documents

# Lister un sous-dossier
curl http://localhost:8000/list/Documents/MonDossier

Réponse exemple :

{
  "path": "/Documents",
  "total_items": 5,
  "summary": {
    "directories": 2,
    "files": 3
  },
  "items": [
    {
      "name": "rapport.pdf",
      "path": "/Documents/rapport.pdf",
      "is_dir": false,
      "size": 1024567,
      "content_type": "application/pdf",
      "last_modified": "2025-10-20T10:30:00",
      "etag": "abc123"
    },
    {
      "name": "Images",
      "path": "/Documents/Images",
      "is_dir": true,
      "size": 0,
      "content_type": null,
      "last_modified": "2025-10-19T15:20:00",
      "etag": "def456"
    }
  ]
}

4. Informations sur un fichier/dossier

GET /info/{path}

Obtient les informations détaillées d'un fichier ou dossier spécifique.

Exemples :

curl http://localhost:8000/info/Documents/rapport.pdf

5. Upload un fichier

POST /upload

Upload un fichier vers un dossier Nextcloud.

Paramètres (form-data) :

• file : Le fichier à uploader
• path : Chemin du dossier de destination (ex: /Documents)
• filename : Nom du fichier (optionnel, utilise le nom original si non spécifié)

Exemples :

# Upload un fichier avec PowerShell
$file = Get-Item "C:\chemin\vers\monfichier.pdf"
$form = @{
    file = $file
    path = "/Documents"
}
Invoke-WebRequest -Uri "http://localhost:8000/upload" -Method POST -Form $form

# Upload avec un nom personnalisé
$form = @{
    file = Get-Item "C:\chemin\vers\monfichier.pdf"
    path = "/Documents"
    filename = "nouveau_nom.pdf"
}
Invoke-WebRequest -Uri "http://localhost:8000/upload" -Method POST -Form $form

Réponse exemple :

{
  "success": true,
  "message": "Fichier uploadé avec succès",
  "file": {
    "name": "rapport.pdf",
    "path": "/Documents/rapport.pdf",
    "size": 1024567,
    "content_type": "application/pdf"
  }
}

🔧 Structure du projet

PyNextcloud/
│
├── main.py              # Application FastAPI avec auto-chargement des contrôleurs
├── config.py            # Configuration de l'application
├── utils.py             # Fonctions utilitaires
├── controllers/         # 📁 Dossier des contrôleurs (auto-chargés)
│   ├── __init__.py
│   ├── root.py         # Route racine
│   ├── health.py       # Health check
│   ├── list.py         # Lister les fichiers/dossiers
│   ├── info.py         # Informations d'un fichier/dossier
│   └── upload.py       # Upload de fichiers
├── requirements.txt     # Dépendances Python
├── env.example         # Exemple de fichier de configuration
├── .env                # Configuration (à créer, non versionné)
└── README.md           # Ce fichier

🎯 Architecture modulaire avec auto-chargement

Le projet utilise une architecture modulaire où tous les contrôleurs dans le dossier controllers/ sont automatiquement chargés au démarrage.

Pour ajouter un nouveau endpoint :

1. Créez un nouveau fichier dans controllers/, par exemple controllers/mon_endpoint.py
2. Créez un router FastAPI dans ce fichier
3. C'est tout ! Le contrôleur sera automatiquement chargé au démarrage

Exemple de nouveau contrôleur :

# controllers/mon_endpoint.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/mon-endpoint")
async def mon_endpoint():
    return {"message": "Mon nouveau endpoint"}

🛠️ Dépendances principales

• FastAPI : Framework web moderne et rapide
• Uvicorn : Serveur ASGI
• nc-py-api : Client Python pour l'API Nextcloud
• python-dotenv : Gestion des variables d'environnement
• pydantic : Validation des données

⚠️ Notes importantes

1. Sécurité : Ne committez jamais votre fichier .env dans Git. Il contient vos identifiants.
2. Chemins : Les chemins doivent être relatifs à la racine de votre espace Nextcloud.
3. Authentification : L'API utilise l'authentification basique avec username/password.

🐛 Dépannage

Erreur de connexion à Nextcloud

• Vérifiez que l'URL de votre serveur Nextcloud est correcte
• Vérifiez vos identifiants
• Assurez-vous que votre serveur Nextcloud est accessible

Erreur 404 sur un répertoire

• Vérifiez que le chemin existe dans votre Nextcloud
• Les chemins sont sensibles à la casse

Problèmes d'activation de l'environnement virtuel

Si vous avez une erreur de sécurité PowerShell, exécutez :

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

📝 Licence

Ce projet est libre d'utilisation pour vos besoins personnels et professionnels.