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

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

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

### 2. Installer les dépendances

```powershell
pip install -r requirements.txt
```

### 3. Configuration

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

```powershell
Copy-Item env.example .env
```

Modifiez le fichier `.env` avec vos informations Nextcloud :

```env
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

```powershell
# 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 :**
```json
{
  "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 :**
```powershell
# 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 :**
```json
{
  "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 :**
```powershell
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 :**
```powershell
# 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 :**
```json
{
  "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 :**
```python
# 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 :
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

## 📝 Licence

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