Metadata-Version: 2.1
Name: querycraft
Version: 0.0.29
Summary: Provide usefully SQL classes and functions to execute SQL queries step by step
Home-page: https://gitlab.univ-nantes.fr/ls2n-didactique/querycraft
Author: Emmanuel Desmontils
Author-email: emmanuel.desmontils@univ-nantes.fr
Maintainer: Emmanuel Desmontils
Maintainer-email:  emmanuel.desmontils@univ-nantes.fr
License: GPL V3
Keywords: SQL Step-By-Step Query Database
Platform: ALL
Classifier: Topic :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.24.0
Requires-Dist: argparse>=1.4.0
Requires-Dist: polars>=0.20.31
Requires-Dist: tincan>=1.0.0
Requires-Dist: psycopg2>=2.9.9
Requires-Dist: sqlglot>=25.6.1
Requires-Dist: mysql-connector-python>=9.0.0

# QueryCraft

[TOC]


## Le nom ?

Un nom en anglais qui évoque l'idée de "façonner" ou "construire" des requêtes SQL de manière intuitive, parfait pour une approche pédagogique. (GPT 4o ;-) )

## Objectifs

L'objectif de cette bibliothèque est de proposer des classes Python permettant de manipuler des requêtes SQL. 
Elle propose aussi des applications pour décomposer l'exécution d'une requête SQL sur une base de données PostgreSQL, MySQL ou SQLite.

## Fonctionnalités

- **Analyse de requêtes SQL** : Analysez et comprenez la structure de vos requêtes SQL.
- **Décomposition de requêtes** : Décomposez vos requêtes SQL en étapes simples pour une meilleure compréhension.
- **Support multi-SGBD** : Compatible avec PostgreSQL, MySQL et SQLite.
- **Interface en ligne de commande** : Utilisez l'application en ligne de commande pour analyser et décomposer vos requêtes SQL.

## Limitations

- **Opérateurs SQL non couverts** : Certains opérateurs SQL avancés peuvent ne pas être entièrement pris en charge, en particulier les opérateurs ensemblistes. 
                                    Par exemple, les opérateurs `INTERSECT`, `EXCEPT` et `UNION` ne sont pas pris en charge.
                                    Les sous-requêtes dans le 'From' sont prises en charges, mais pas les sous-requêtes dans le 'Where', le 'Having' et le 'Select' (pas de pas à pas possible).
- **Support limité des fonctions SQL** : Certaines fonctions SQL avancées peuvent ne pas être entièrement prises en charge.
- **Compatibilité avec les versions de SGBD** : La compatibilité avec les versions spécifiques de PostgreSQL, MySQL et SQLite peut varier.


## Installation 

```shell
git clone https://gitlab.univ-nantes.fr/ls2n-didactique/querycraft.git
cd querycraft
pip install -e .
```

ou

```shell
pip install querycraft
```

## Usage

Application qui permet de décomposer l'exécution d'une requête SQL sur une base de données PostgreSQL.

```
usage: pgsql-sbs [-h] [-d DB] [-u USER] [-p PASSWORD] [--host HOST] [--port PORT] [--debug] [-v] [-f FILE | -s SQL]

options:
  -h, --help            show this help message and exit
  -d DB, --db DB        database name
  -u USER, --user USER  database user
  -p PASSWORD, --password PASSWORD
                        database password
  --host HOST           database host
  --port PORT           database port
  --debug               debug mode
  -v, --verbose         verbose mode
  -f FILE, --file FILE  sql file
  -s SQL, --sql SQL     sql string
```

Par exemple :
```
pgsql-sbs -s 'select * from etudiants join notes using(noetu);'   

==================================================================================================
select * FROM  #etudiants#  JOIN notes USING (noetu) ;
┌─────────────────┬───────────────┬──────────────────┐
│ etudiants.noetu ┆ etudiants.nom ┆ etudiants.prenom │
╞═════════════════╪═══════════════╪══════════════════╡
│ 28936E          ┆ Dupont        ┆ Franck           │
│ 46283B          ┆ Dupont        ┆ Isabelle         │
│ 86719E          ┆ Martin        ┆ Adrien           │
│ 99628C          ┆ Robert        ┆ Adrien           │
│ 99321C          ┆ Denou         ┆ Michelle         │
│ 99322C          ┆ Dupont        ┆ Isabelle         │
└─────────────────┴───────────────┴──────────────────┘

==================================================================================================
select * FROM etudiants JOIN  #notes#  USING (noetu) ;
┌─────────────┬───────────────┬──────────────┬──────────────┐
│ notes.noetu ┆ notes.codemat ┆ notes.noteex ┆ notes.notecc │
╞═════════════╪═══════════════╪══════════════╪══════════════╡
│ 99628C      ┆ MIAS2I5       ┆ 12.0         ┆ 15.5         │
│ 46283B      ┆ MIAS2I5       ┆ 9.5          ┆ 2.0          │
│ 86719E      ┆ IUP2MA        ┆ 12.0         ┆ 5.5          │
│ 99321C      ┆ LIL6          ┆ 18.0         ┆ 16.5         │
│ 28936E      ┆ MIAS2I5       ┆ 13.5         ┆ 13.5         │
│ 86719E      ┆ IUP2IS        ┆ 8.5          ┆ 10.0         │
│ 99321C      ┆ LIL5          ┆ 15.0         ┆ 14.5         │
│ 99322C      ┆ MIAS2I5       ┆ 12.0         ┆ 15.5         │
│ 46283B      ┆ MIAS2I6       ┆ 8.0          ┆ 12.0         │
│ 99628C      ┆ MIAS2I6       ┆ 3.0          ┆ 7.0          │
│ 28936E      ┆ MIAS2I6       ┆ 12.0         ┆ null         │
└─────────────┴───────────────┴──────────────┴──────────────┘

==================================================================================================
select * FROM  #etudiants JOIN notes USING (noetu)#  ;
┌─────────────────┬───────────────┬──────────────────┬───────────────┬──────────────┬──────────────┐
│ etudiants.noetu ┆ etudiants.nom ┆ etudiants.prenom ┆ notes.codemat ┆ notes.noteex ┆ notes.notecc │
╞═════════════════╪═══════════════╪══════════════════╪═══════════════╪══════════════╪══════════════╡
│ 99628C          ┆ Robert        ┆ Adrien           ┆ MIAS2I5       ┆ 12.0         ┆ 15.5         │
│ 46283B          ┆ Dupont        ┆ Isabelle         ┆ MIAS2I5       ┆ 9.5          ┆ 2.0          │
│ 86719E          ┆ Martin        ┆ Adrien           ┆ IUP2MA        ┆ 12.0         ┆ 5.5          │
│ 99321C          ┆ Denou         ┆ Michelle         ┆ LIL6          ┆ 18.0         ┆ 16.5         │
│ 28936E          ┆ Dupont        ┆ Franck           ┆ MIAS2I5       ┆ 13.5         ┆ 13.5         │
│ 86719E          ┆ Martin        ┆ Adrien           ┆ IUP2IS        ┆ 8.5          ┆ 10.0         │
│ 99321C          ┆ Denou         ┆ Michelle         ┆ LIL5          ┆ 15.0         ┆ 14.5         │
│ 99322C          ┆ Dupont        ┆ Isabelle         ┆ MIAS2I5       ┆ 12.0         ┆ 15.5         │
│ 46283B          ┆ Dupont        ┆ Isabelle         ┆ MIAS2I6       ┆ 8.0          ┆ 12.0         │
│ 99628C          ┆ Robert        ┆ Adrien           ┆ MIAS2I6       ┆ 3.0          ┆ 7.0          │
│ 28936E          ┆ Dupont        ┆ Franck           ┆ MIAS2I6       ┆ 12.0         ┆ null         │
└─────────────────┴───────────────┴──────────────────┴───────────────┴──────────────┴──────────────┘

==================================================================================================
select  #* FROM etudiants JOIN notes USING (noetu)#  ;
┌─────────────────┬───────────────┬──────────────────┬───────────────┬──────────────┬──────────────┐
│ etudiants.noetu ┆ etudiants.nom ┆ etudiants.prenom ┆ notes.codemat ┆ notes.noteex ┆ notes.notecc │
╞═════════════════╪═══════════════╪══════════════════╪═══════════════╪══════════════╪══════════════╡
│ 99628C          ┆ Robert        ┆ Adrien           ┆ MIAS2I5       ┆ 12.0         ┆ 15.5         │
│ 46283B          ┆ Dupont        ┆ Isabelle         ┆ MIAS2I5       ┆ 9.5          ┆ 2.0          │
│ 86719E          ┆ Martin        ┆ Adrien           ┆ IUP2MA        ┆ 12.0         ┆ 5.5          │
│ 99321C          ┆ Denou         ┆ Michelle         ┆ LIL6          ┆ 18.0         ┆ 16.5         │
│ 28936E          ┆ Dupont        ┆ Franck           ┆ MIAS2I5       ┆ 13.5         ┆ 13.5         │
│ 86719E          ┆ Martin        ┆ Adrien           ┆ IUP2IS        ┆ 8.5          ┆ 10.0         │
│ 99321C          ┆ Denou         ┆ Michelle         ┆ LIL5          ┆ 15.0         ┆ 14.5         │
│ 99322C          ┆ Dupont        ┆ Isabelle         ┆ MIAS2I5       ┆ 12.0         ┆ 15.5         │
│ 46283B          ┆ Dupont        ┆ Isabelle         ┆ MIAS2I6       ┆ 8.0          ┆ 12.0         │
│ 99628C          ┆ Robert        ┆ Adrien           ┆ MIAS2I6       ┆ 3.0          ┆ 7.0          │
│ 28936E          ┆ Dupont        ┆ Franck           ┆ MIAS2I6       ┆ 12.0         ┆ null         │
└─────────────────┴───────────────┴──────────────────┴───────────────┴──────────────┴──────────────┘
```

Il est aussi possible d'utiliser MySQL :

```
usage: mysql-sbs [-h] [-d DB] [-u USER] [-p PASSWORD] [--host HOST] [--port PORT] [--debug] [-v] [-f FILE | -s SQL]

options:
  -h, --help            show this help message and exit
  -d DB, --db DB        database name
  -u USER, --user USER  database user
  -p PASSWORD, --password PASSWORD
                        database password
  --host HOST           database host
  --port PORT           database port
  --debug               debug mode
  -v, --verbose         verbose mode
  -f FILE, --file FILE  sql file
  -s SQL, --sql SQL     sql string
```

ou SQLite :

```
usage: sqlite-sbs [-h] [-d DB] [--debug] [-v] [-f FILE | -s SQL]

options:
  -h, --help            show this help message and exit
  -d DB, --db DB        database name
  --debug               debug mode
  -v, --verbose         verbose mode
  -f FILE, --file FILE  sql file
  -s SQL, --sql SQL     sql string
```

## LRS

L'outil peut être interfacé avec un LRS compatible XAPI (testé avec Veracity  ; https://lrs.io/home ; https://lrs.io/home/download).  Il suffit de spécifier les paramètres de connection à travers les paramètres "--lrs-*". L'activation elle-même est donnée par le paramètre "--lrs".

## Article de recherche

- Emmanuel Desmontils, Laura Monceaux. **Enseigner SQL en NSI**. Atelier « Apprendre la Pensée Informatique de la Maternelle à l'Université », dans le cadre de la conférence Environnements Informatiques pour l'Apprentissage Humain (EIAH), Jun 2023, Brest, France. pp.17-24. https://hal.science/hal-04144210 
 https://apimu.gitlabpages.inria.fr/site/ateliers/pdf-apimu23/APIMUEIAH_2023_paper_3.pdf


## Génération de la documentation

```shell
pdoc3 --html --force -o doc querycraft
```

## Remerciements

- Wiktoria SLIWINSKA, étudiante ERASMUS en licence Informatique à l'Université de Nantes en 2023-2024, pour son aide à la conception du POC initial. 

## Licence

(C) E. Desmontils, Nantes Université, 2024

Ce logiciel est distribué sous licence GPLv3.



