API Reference

Facade client qui regroupe les clients spécifiques par ressource.

Fournit un accès simple aux sous-clients : dataset, analysis, configuration, et des méthodes pour l’authentification (login/logout) et l’accès à l’utilisateur courant.

class pygroundedweb.client.client.GroundedWebClient(base_url, check_connection=True)

Client principal à utiliser par les consommateurs de la bibliothèque.

Exemple d’utilisation :

client = GroundedWebClient( »http://example.com ») client.login(email, password) ds = client.dataset.create(« Mon dataset », photos_before=[« a.jpg »])

Attributs exposés :

dataset: DatasetClient analysis: AnalysisClient configuration: ConfigurationClient

Paramètres:

• base_url (str)

• check_connection (bool)

login(email, password)

Authentifie l’utilisateur auprès de l’API.

Paramètres:

• email (str) – adresse email.

• password (str) – mot de passe en clair.

logout()

Déconnecte la session courante et nettoie les cookies locaux.

property is_authenticated: bool

Indique si la session courante est authentifiée.

property current_user: User | None

Retourne l’objet User courant si authentifié, sinon None.

Client HTTP de base et clients de modèles pour l’API Grounded Web.

Ce module expose : - BaseAPIClient : client HTTP basique qui gère la session et les appels REST. - APIModelClient : base abstraite pour les clients de ressources (create/retrieve/update/delete).

Les docstrings détaillent les paramètres et le comportement attendu pour faciliter la génération de documentation.

class pygroundedweb.client.base.BaseAPIClient(base_url, default_headers=None, check_connection=True)

Client HTTP générique qui conserve une session persistante et fournit des utilitaires pour effectuer des requêtes vers l’API Grounded Web.

Ce client gère : - la construction des URLs (ajoute « /api » si nécessaire), - la ré-essai automatique sur erreurs réseau, - le rafraîchissement de tokens lorsque nécessaire, - la sérialisation/désérialisation minimale des réponses JSON.

Params

base_url: str

URL de base de l’API (ex: « http://localhost:8000 » ou « http://localhost:8000/api »).

default_headers: Optional[Dict[str, str]]

Headers par défaut pour chaque requête (Accept/Content-Type par défaut si None).

check_connection: bool

Si True, effectue une validation initiale de l’API en interrogeant l’endpoint /schema.

request(method, endpoint='', *, params=None, json=None, data=None, headers=None, allow_refresh=True, max_retries=3, full_url=None, **kwargs)

Effectue une requête HTTP vers l’API en gérant les erreurs communes.

Paramètres:

• method (str) – Méthode HTTP (GET, POST, PATCH, …).

• endpoint (str) – Chemin relatif de la ressource (ex: “datasets”).

• params (Optional[Dict[str, Any]]) – Paramètres de requête (querystring).

• json (Optional[Any]) – Payload JSON si applicable.

• data (Optional[Any]) – Payload non-JSON si nécessaire.

• headers (Optional[Dict[str, str]]) – En-têtes supplémentaires pour cette requête.

• allow_refresh (bool) – Si True, tentera un rafraîchissement du token sur 401.

• max_retries (int) – Nombre maximal de tentatives en cas d’erreur réseau.

• full_url (Optional[str]) – Utiliser une URL absolue plutôt que base_url/endpoint.

Renvoie:

objet Response déjà vérifié et sans status HTTP erreur.

Type renvoyé:

requests.Response

Lève:

APIError, NetworkError, PermissionDenied –

get(endpoint, **kwargs)

Raccourci pour effectuer une requête GET.

Lève:

APIError, NetworkError, PermissionDenied –

Type renvoyé:

Response

Paramètres:

endpoint (str)

post(endpoint, **kwargs)

Raccourci pour effectuer une requête POST.

Lève:

APIError, NetworkError, PermissionDenied –

Type renvoyé:

Response

Paramètres:

endpoint (str)

patch(endpoint, **kwargs)

Raccourci pour effectuer une requête PATCH.

Lève:

APIError, NetworkError, PermissionDenied –

Type renvoyé:

Response

Paramètres:

endpoint (str)

put(endpoint, **kwargs)

Raccourci pour effectuer une requête PUT.

Lève:

APIError, NetworkError, PermissionDenied –

Type renvoyé:

Response

Paramètres:

endpoint (str)

delete(endpoint, **kwargs)

Raccourci pour effectuer une requête DELETE.

Lève:

APIError, NetworkError, PermissionDenied –

Type renvoyé:

Response

Paramètres:

endpoint (str)

login(email, password)

Effectue l’authentification auprès de l’API.

Paramètres:

• email (str) – adresse email de l’utilisateur.

• password (str) – mot de passe en clair.

Lève:

• PermissionDenied – si les identifiants sont invalides.

• APIError – pour d’autres erreurs retournées par l’API.

logout()

Se déconnecte de l’API et nettoie la session locale (cookies).

refresh()

Tente de rafraîchir le token d’authentification via l’endpoint standard.

Retourne True si le rafraîchissement a réussi, False sinon.

Type renvoyé:

bool

property is_authenticated: bool

Indique si une session est actuellement authentifiée (user chargé).

get_by_id(resource, id)

Récupère un objet JSON par ID pour la ressource donnée.

Paramètres:

• resource (str) – nom de la ressource (ex: “datasets”).

• id (int) – identifiant numérique.

Type renvoyé:

Any

Renvoie:

Le JSON (dictionnaire) retourné par l’API.

update(resource, model)

Met à jour une ressource en envoyant un PATCH avec le model.serialized.

Paramètres:

• resource (str) – nom de la ressource.

• model (APIModel) – instance héritant de APIModel.

Type renvoyé:

Any

Renvoie:

Le JSON résultant de la mise à jour.

create(resource, data)

Crée une ressource en POSTant les données JSON fournies.

Paramètres:

• resource (str) – nom de la ressource (ex: “datasets”).

• data (Dict[str, Any]) – dict contenant les champs à créer.

Type renvoyé:

Any

Renvoie:

Le JSON de la ressource créée (typiquement contient l’ID).

delete_by_id(resource, id)

Supprime une ressource par ID et retourne la réponse JSON.

Paramètres:

• resource (str) – nom de la ressource.

• id (int) – identifiant de la ressource.

get_all(resource, query_string=None)

Récupère la liste d’objets pour une ressource en utilisant query string.

Paramètres:

• resource (str) – nom de la ressource.

• query_string (Optional[Dict[str, Any]]) – dictionnaire de paramètres de filtrage/pagination (optionnel).

Type renvoyé:

List[Any]

Renvoie:

Liste d’objets JSON.

Lève:

APIError, NetworkError, PermissionDenied –

close()

Ferme la session HTTP (libère les connexions).

Paramètres:

• base_url (str)

• default_headers (Dict[str, str] | None)

• check_connection (bool)

class pygroundedweb.client.base.APIModelClient(client)

Base abstraite pour les clients de ressources CRUD.

Les implémentations doivent exposer les méthodes create/retrieve/update/delete.

Paramètres:

client (BaseAPIClient)

abstractmethod create(**kwargs)

Crée une nouvelle ressource.

Type renvoyé:

APIModel

abstractmethod retrieve(resource_id)

Récupère une ressource par son ID.

Type renvoyé:

APIModel

Paramètres:

resource_id (int)

abstractmethod update(instance)

Met à jour une instance existante.

Type renvoyé:

APIModel

Paramètres:

instance (APIModel)

abstractmethod delete(resource_id)

Supprime une ressource.

Type renvoyé:

None

Paramètres:

resource_id (int)

Client pour la gestion des datasets (création, lecture, mise à jour, suppression)

Ce module contient DatasetClient qui offre des helpers pour créer un dataset en uploadant les photos (avec gestion de l’upload multi-thread et de la confirmation serveur).

class pygroundedweb.client.dataset.DatasetClient(client)

Client CRUD pour les datasets.

Fournit des helpers pour créer, récupérer, mettre à jour et supprimer des datasets, y compris l’upload des photos associé (upload parallèle et confirmation côté serveur).

Notes

• Les méthodes publiques peuvent lever : APIError, NetworkError, PermissionDenied, UploadError ou pydantic.ValidationError selon le contexte.

Paramètres:

client (BaseAPIClient)

create(dataset_name, photos_before=None, photos_after=None, max_workers=5, progress_callback=None)

Crée un dataset et upload les photos associées.

Paramètres:

• dataset_name (str) – nom du dataset à créer.

• photos_before (List[str]) – liste de chemins vers les photos « before ».

• photos_after (List[str]) – liste de chemins vers les photos « after ».

• max_workers (int) – nombre maximum de threads pour l’upload parallèle.

• progress_callback (Optional[Callable[[int, int], None]]) – fonction(optionnelle) appelée avec (uploaded, total) pour suivre la progression.

Type renvoyé:

Dataset

Renvoie:

Instance Dataset représentant l’objet créé côté serveur.

Lève:

• ValueError – si aucune photo n’est fournie.

• FileNotFoundError – si un chemin de photo est introuvable.

• UploadError – si l’upload de l’un des fichiers échoue.

• APIError, NetworkError, PermissionDenied – pour les erreurs HTTP retournées par le serveur.

retrieve(dataset_id)

Récupère un dataset par son identifiant et le convertit en objet Dataset.

Lève:

APIError, NetworkError, PermissionDenied, pydantic.ValidationError –

Paramètres:

dataset_id (int)

update(dataset)

Met à jour un dataset existant et renvoie l’objet mis à jour.

Lève:

APIError, NetworkError, PermissionDenied, pydantic.ValidationError –

Paramètres:

dataset (Dataset)

delete(dataset_id)

Supprime un dataset par identifiant.

Lève:

APIError, NetworkError, PermissionDenied –

Paramètres:

dataset_id (int)

Client pour gérer les analyses (création, lecture, mise à jour, suppression).

Fournit des helpers pour créer une analyse à partir d’une configuration et d’un dataset.

class pygroundedweb.client.analysis.AnalysisClient(client)

Client CRUD pour les ressources Analysis côté API.

Les méthodes exposées effectuent les appels réseau via BaseAPIClient et peuvent propager APIError, NetworkError, PermissionDenied ou pydantic.ValidationError en cas d’erreur.

Paramètres:

client (BaseAPIClient)

create(analysis_name, configuration, dataset=None, dataset_id=None, selected_photos_id=None, notify_by_email=False)

Crée une analyse côté API.

Paramètres:

• analysis_name (str) – nom de l’analyse.

• configuration (Configuration) – instance de Configuration à utiliser.

• dataset (Optional[Dataset]) – (optionnel) instance de Dataset.

• dataset_id (Optional[int]) – (optionnel) identifiant du dataset (alternative à dataset).

• selected_photos_id (Optional[List[int]]) – liste d’IDs de photos sélectionnées pour l’analyse.

• notify_by_email (Optional[bool]) – si True, le serveur enverra une notification par e-mail en fin de traitement.

Type renvoyé:

Analysis

Renvoie:

Instance Analysis correspondant à la ressource créée.

Lève:

• ValueError – si ni dataset ni dataset_id ne sont fournis ou si les deux le sont.

• APIError, NetworkError, PermissionDenied, pydantic.ValidationError –

retrieve(analysis_id)

Récupère une analyse par son identifiant et renvoie une instance Analysis.

Lève:

APIError, NetworkError, PermissionDenied, pydantic.ValidationError –

Paramètres:

analysis_id (int)

update(analysis)

Met à jour une analyse existante et retourne l’objet mis à jour.

Lève:

APIError, NetworkError, PermissionDenied, pydantic.ValidationError –

Type renvoyé:

Analysis

Paramètres:

analysis (Analysis)

delete(analysis_id)

Supprime une analyse par identifiant.

Lève:

APIError, NetworkError, PermissionDenied –

Paramètres:

analysis_id (int)

class pygroundedweb.client.configuration.ConfigurationClient(client)

Client CRUD pour les configurations d’analyse.

Fournit les opérations de création, lecture, mise à jour, suppression et liste des Configuration côté API.

Les méthodes peuvent lever des exceptions liées aux appels HTTP ou à la validation des modèles côté client.

Paramètres:

client (BaseAPIClient)

create(configuration)

Crée une configuration côté API.

Paramètres:

configuration (Configuration) – instance Configuration à envoyer.

Type renvoyé:

Configuration

Renvoie:

L’instance Configuration créée telle que renvoyée par l’API.

Lève:

• APIError – si l’API retourne une erreur lors de la création.

• NetworkError – en cas de problème réseau persistant.

• PermissionDenied – si les droits sont insuffisants.

• pydantic.ValidationError – si la validation du modèle côté client échoue.

retrieve(config_id)

Récupère une configuration par son identifiant.

Paramètres:

config_id (int) – identifiant numérique de la configuration.

Type renvoyé:

Configuration

Renvoie:

Instance Configuration correspondant à la ressource distante.

Lève:

• APIError – si l’API retourne une erreur.

• NetworkError – en cas de problème réseau.

• PermissionDenied – si l’accès est interdit.

• pydantic.ValidationError – si la réponse ne peut être validée en Configuration.

update(configuration)

Met à jour une configuration existante.

Paramètres:

configuration (Configuration) – instance Configuration contenant les modifications.

Type renvoyé:

Configuration

Renvoie:

Instance Configuration mise à jour.

Lève:

APIError, NetworkError, PermissionDenied, pydantic.ValidationError –

delete(config_id)

Supprime une configuration par identifiant.

Lève:

APIError, NetworkError, PermissionDenied –

Type renvoyé:

None

Paramètres:

config_id (int)

list()

Liste toutes les configurations disponibles côté API.

Type renvoyé:

List[Configuration]

Renvoie:

Liste d’instances Configuration.

Lève:

APIError, NetworkError, PermissionDenied, pydantic.ValidationError –

Classes de base pour les modèles Pydantic utilisés par le client.

Contient la classe APIModel qui étend pydantic.BaseModel avec : - gestion des champs mutables/immuables par instance, - référence vers le client API pour opérations (refresh).

Ces docstrings servent à produire une documentation claire des comportements attendus lors de l’utilisation des objets retournés par l’API.

class pygroundedweb.models.base.APIModel(*, mutable_fields=None, immutable_fields=None, **data)

Base pour les modèles sérialisés provenant de l’API Grounded Web.

Attributs principaux :

pk: identifiant numérique si présent. _mutable_fields: ensemble des noms de champs modifiables pour cette instance. _client: référence (privée) vers le client API permettant d’effectuer des opérations serveur.

Comportement important :

• Le constructeur accepte mutable_fields ou immutable_fields dans les données pour contrôler quels attributs peuvent être modifiés localement via setattr.

• La méthode refresh() permet de rafraîchir l’objet à partir du serveur en utilisant le client attaché.

Paramètres:

• mutable_fields (set[str])

• immutable_fields (set[str])

• pk (int | None)

is_mutable(field)

Retourne True si le champ donné est modifiable pour cette instance.

Paramètres:

field (str) – nom du champ à tester.

Type renvoyé:

bool

refresh()

Rafraîchit l’instance actuelle avec les données du serveur.

Cette méthode utilise le client attaché (_client) et l’attribut pk pour récupérer la version la plus récente du serveur et mettre à jour l’objet local.

Lève:

RuntimeError – si le client n’est pas attaché ou si pk est None.

Type renvoyé:

None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Paramètres:

• self (BaseModel) – The BaseModel instance.

• context (Any) – The context.

Type renvoyé:

None

Modèle représentant un Dataset retourné par l’API.

Contient le validateur de champ date pour accepter str/datetime.

class pygroundedweb.models.dataset.Dataset(*, mutable_fields=None, immutable_fields=None, **data)

Représente un dataset côté client.

Attributs

name: str

Nom du dataset.

date: date

Date associée au dataset (convertie depuis str/datetime si nécessaire).

user: Union[User, str]

Utilisateur propriétaire (ou identifiant string).

photos: Optional[List[DatasetPhoto]]

Liste facultative des photos associées.

classmethod parse_date(value)

Accepte une datetime ou une chaîne ISO et renvoie une date.

Lève ValueError si la chaîne n’est pas un ISO date valide.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Paramètres:

• self (BaseModel) – The BaseModel instance.

• context (Any) – The context.

Type renvoyé:

None

Paramètres:

• mutable_fields (set[str])

• immutable_fields (set[str])

• pk (int | None)

• name (str)

• date (date)

• user (User | str)

• photos (List[DatasetPhoto] | None)

Modèles relatifs aux analyses (Analysis, Hole, AnalysisStatus).

Ces modèles décrivent l’état et les résultats (liens point cloud, logs) d’une analyse.

class pygroundedweb.models.analysis.AnalysisStatus(*values)

Statut possible d’une analyse.

class pygroundedweb.models.analysis.Hole(*, mutable_fields=None, immutable_fields=None, **data)

Représente un trou détecté avec numéro et volume.

Paramètres:

• mutable_fields (set[str])

• immutable_fields (set[str])

• pk (int | None)

• number (int)

• volume (float)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Paramètres:

• self (BaseModel) – The BaseModel instance.

• context (Any) – The context.

Type renvoyé:

None

class pygroundedweb.models.analysis.Analysis(*, mutable_fields=None, immutable_fields=None, **data)

Modèle représentant une analyse.

Champs importants :

name, date, user, status, selection, configuration, holes, et URLs vers les artefacts produits (point_cloud, logs).

Paramètres:

• mutable_fields (set[str])

• immutable_fields (set[str])

• pk (int | None)

• name (str)

• date (datetime)

• user (str)

• status (AnalysisStatus | None)

• point_cloud_before (HttpUrl | None)

• point_cloud_after (HttpUrl | None)

• result (HttpUrl | None)

• logs (HttpUrl | None)

• selection (Selection)

• notify_by_email (bool)

• configuration (Configuration)

• holes (List[Hole])

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Paramètres:

• self (BaseModel) – The BaseModel instance.

• context (Any) – The context.

Type renvoyé:

None

Modèle de configuration d’analyse et utilitaires de sérialisation.

Ce modèle inclut les sous-modèles pour les detecteurs, cloud-processor et SFM.

class pygroundedweb.models.configuration.Configuration(*, mutable_fields=None, immutable_fields=None, **data)

Configuration complète utilisée pour lancer une analyse.

Champs:

name: nom optionnel de la configuration. scale_bars: liste de ScaleBar. detector: configuration du détecteur. cloud_processor: configuration du traitement du nuage. sfm: configuration SFM. display_padding: option d’affichage facultative.

Paramètres:

• mutable_fields (set[str])

• immutable_fields (set[str])

• pk (int | None)

• name (str | None)

• scale_bars (List[ScaleBar])

• detector (CCTag)

• cloud_processor (CloudCompare)

• sfm (MicMac)

• display_padding (bool | None)

model_dump(**kwargs)

Sérialise le modèle en dict en appliquant une logique pour les sous-modèles.

Cette méthode garantit que detector, cloud_processor et sfm sont eux-mêmes sérialisés via leur model_dump avant d’être envoyés à l’API.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Paramètres:

• self (BaseModel) – The BaseModel instance.

• context (Any) – The context.

Type renvoyé:

None

Modèle pour une photo attachée à un dataset.

Contient le type (before/after) et les URLs vers différentes résolutions/artefacts.

class pygroundedweb.models.dataset_photo.TypePhoto(*values)

Types possibles pour une photo: BEFORE ou AFTER.

class pygroundedweb.models.dataset_photo.DatasetPhoto(*, mutable_fields=None, immutable_fields=None, **data)

Représente une photo de dataset avec différentes URL de rendus.

Champs:

name: nom/fichier de la photo. type: TypePhoto indiquant si c’est « before » ou « after ». thumb/preview/full_compressed/original: URLs optionnelles.

Paramètres:

• mutable_fields (set[str])

• immutable_fields (set[str])

• pk (int | None)

• name (str)

• type (TypePhoto)

• thumb (HttpUrl | None)

• preview (HttpUrl | None)

• full_compressed (HttpUrl | None)

• original (HttpUrl | None)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Paramètres:

• self (BaseModel) – The BaseModel instance.

• context (Any) – The context.

Type renvoyé:

None

Modèle représentant un utilisateur retourné par l’API.

class pygroundedweb.models.user.User(*, mutable_fields=None, immutable_fields=None, **data)

Représentation minimale d’un utilisateur.

Champs:

first_name: prénom. last_name: nom. email: adresse email.

Paramètres:

• mutable_fields (set[str])

• immutable_fields (set[str])

• pk (int | None)

• first_name (str)

• last_name (str)

• email (str)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Paramètres:

• self (BaseModel) – The BaseModel instance.

• context (Any) – The context.

Type renvoyé:

None