ajout documentation

app/entreprises/forms.py

@@ -1,4 +1,3 @@
-from flask import flash
 from flask_wtf import FlaskForm
 from markupsafe import Markup
 import requests, re

app/entreprises/models.py

@@ -57,6 +57,23 @@ class EntrepriseContact(db.Model):
             "service": self.service,
         }
 
+    def to_dict_export(self):
+        entreprise = Entreprise.query.get(self.entreprise_id)
+        return {
+            "nom": self.nom,
+            "prenom": self.prenom,
+            "telephone": self.telephone,
+            "mail": self.mail,
+            "poste": self.poste,
+            "service": self.service,
+            "siret": entreprise.siret,
+            "nom_entreprise": entreprise.nom,
+            "adresse_entreprise": entreprise.adresse,
+            "codepostal": entreprise.codepostal,
+            "ville": entreprise.ville,
+            "pays": entreprise.pays,
+        }
+
 
 class EntrepriseOffre(db.Model):
     __tablename__ = "entreprise_offre"

app/entreprises/routes.py

@@ -45,6 +45,18 @@ from werkzeug.utils import secure_filename
 
 @bp.route("/", methods=["GET"])
 def index():
+    """
+    Permet d'afficher une page avec la liste des entreprises et une liste des dernières opérations
+
+    Retourne: template de la page (entreprises.html)
+        Arguments du template:
+            title:
+                titre de la page
+            entreprises:
+                liste des entreprises
+            logs:
+                liste des logs
+    """
     entreprises = Entreprise.query.all()
     logs = EntrepriseLog.query.order_by(EntrepriseLog.date.desc()).limit(LOGS_LEN).all()
     return render_template(
@@ -57,6 +69,18 @@ def index():
 
 @bp.route("/contacts", methods=["GET"])
 def contacts():
+    """
+    Permet d'afficher une page la liste des contacts et une liste des dernières opérations
+
+    Retourne: template de la page (contacts.html)
+        Arguments du template:
+            title:
+                titre de la page
+            contacts:
+                liste des contacts
+            logs:
+                liste des logs
+    """
     contacts = (
         db.session.query(EntrepriseContact, Entreprise)
         .join(Entreprise, EntrepriseContact.entreprise_id == Entreprise.id)
@@ -70,6 +94,31 @@ def contacts():
 
 @bp.route("/fiche_entreprise/<int:id>", methods=["GET"])
 def fiche_entreprise(id):
+    """
+    Permet d'afficher la fiche entreprise d'une entreprise avec une liste des dernières opérations et
+    l'historique des étudiants ayant réaliser un stage ou une alternance dans cette entreprise.
+    La fiche entreprise comporte les informations de l'entreprise, les contacts de l'entreprise et
+    les offres de l'entreprise.
+
+    Arguments:
+        id:
+            l'id de l'entreprise
+
+    Retourne: template de la page (fiche_entreprise.html)
+        Arguments du template:
+            title:
+                titre de la page
+            entreprise:
+                un objet entreprise
+            contacts:
+                liste des contacts de l'entreprise
+            offres:
+                liste des offres de l'entreprise avec leurs fichiers
+            logs:
+                liste des logs
+            historique:
+                liste des étudiants ayant réaliser un stage ou une alternance dans l'entreprise
+    """
     entreprise = Entreprise.query.filter_by(id=id).first_or_404()
     offres = entreprise.offres
     offres_with_files = []
@@ -116,19 +165,32 @@ def fiche_entreprise(id):
 
 @bp.route("/offres", methods=["GET"])
 def offres():
-    offres_recus = (
+    """
+    Permet d'afficher la page où l'on recoit les offres
+
+    Retourne: template de la page (offres.html)
+        Arguments du template:
+            title:
+                titre de la page
+            offres_recus:
+                liste des offres reçues
+    """
+    offres_recues = (
         db.session.query(EntrepriseEnvoiOffre, EntrepriseOffre)
         .filter(EntrepriseEnvoiOffre.receiver_id == current_user.id)
         .join(EntrepriseOffre, EntrepriseOffre.id == EntrepriseEnvoiOffre.offre_id)
         .all()
     )
     return render_template(
-        "entreprises/offres.html", title=("Offres"), offres_recus=offres_recus
+        "entreprises/offres.html", title=("Offres"), offres_recues=offres_recues
     )
 
 
 @bp.route("/add_entreprise", methods=["GET", "POST"])
 def add_entreprise():
+    """
+    Permet d'ajouter une entreprise dans la base avec un formulaire
+    """
     form = EntrepriseCreationForm()
     if form.validate_on_submit():
         entreprise = Entreprise(
@@ -170,6 +232,13 @@ def add_entreprise():
 
 @bp.route("/edit_entreprise/<int:id>", methods=["GET", "POST"])
 def edit_entreprise(id):
+    """
+    Permet de modifier une entreprise de la base avec un formulaire
+
+    Arguments:
+        id:
+            l'id de l'entreprise
+    """
     entreprise = Entreprise.query.filter_by(id=id).first_or_404()
     form = EntrepriseModificationForm()
     if form.validate_on_submit():
@@ -231,6 +300,13 @@ def edit_entreprise(id):
 
 @bp.route("/delete_entreprise/<int:id>", methods=["GET", "POST"])
 def delete_entreprise(id):
+    """
+    Permet de supprimer une entreprise de la base avec un formulaire de confirmation
+
+    Arguments:
+        id:
+            l'id de l'entreprise
+    """
     entreprise = Entreprise.query.filter_by(id=id).first_or_404()
     form = SuppressionConfirmationForm()
     if form.validate_on_submit():
@@ -253,6 +329,13 @@ def delete_entreprise(id):
 
 @bp.route("/add_offre/<int:id>", methods=["GET", "POST"])
 def add_offre(id):
+    """
+    Permet d'ajouter une offre a une entreprise
+
+    Arguments:
+        id:
+            l'id de l'entreprise
+    """
     entreprise = Entreprise.query.filter_by(id=id).first_or_404()
     form = OffreCreationForm()
     if form.validate_on_submit():
@@ -279,6 +362,13 @@ def add_offre(id):
 
 @bp.route("/edit_offre/<int:id>", methods=["GET", "POST"])
 def edit_offre(id):
+    """
+    Permet de modifier une offre
+
+    Arguments:
+        id:
+            l'id de l'offre
+    """
     offre = EntrepriseOffre.query.filter_by(id=id).first_or_404()
     form = OffreModificationForm()
     if form.validate_on_submit():
@@ -309,6 +399,13 @@ def edit_offre(id):
 
 @bp.route("/delete_offre/<int:id>", methods=["GET", "POST"])
 def delete_offre(id):
+    """
+    Permet de supprimer une offre
+
+    Arguments:
+        id:
+            l'id de l'offre
+    """
     offre = EntrepriseOffre.query.filter_by(id=id).first_or_404()
     entreprise_id = offre.entreprise.id
     form = SuppressionConfirmationForm()
@@ -330,6 +427,13 @@ def delete_offre(id):
 
 @bp.route("/add_contact/<int:id>", methods=["GET", "POST"])
 def add_contact(id):
+    """
+    Permet d'ajouter un contact a une entreprise
+
+    Arguments:
+        id:
+            l'id de l'entreprise
+    """
     entreprise = Entreprise.query.filter_by(id=id).first_or_404()
     form = ContactCreationForm(hidden_entreprise_id=entreprise.id)
     if form.validate_on_submit():
@@ -357,6 +461,13 @@ def add_contact(id):
 
 @bp.route("/edit_contact/<int:id>", methods=["GET", "POST"])
 def edit_contact(id):
+    """
+    Permet de modifier un contact
+
+    Arguments:
+        id:
+            l'id du contact
+    """
     contact = EntrepriseContact.query.filter_by(id=id).first_or_404()
     form = ContactModificationForm()
     if form.validate_on_submit():
@@ -391,6 +502,13 @@ def edit_contact(id):
 
 @bp.route("/delete_contact/<int:id>", methods=["GET", "POST"])
 def delete_contact(id):
+    """
+    Permet de supprimer un contact
+
+    Arguments:
+        id:
+            l'id du contact
+    """
     contact = EntrepriseContact.query.filter_by(id=id).first_or_404()
     entreprise_id = contact.entreprise.id
     form = SuppressionConfirmationForm()
@@ -421,6 +539,13 @@ def delete_contact(id):
 
 @bp.route("/add_historique/<int:id>", methods=["GET", "POST"])
 def add_historique(id):
+    """
+    Permet d'ajouter un étudiant ayant réalisé un stage ou une alternance sur la fiche entreprise de l'entreprise
+
+    Arguments:
+        id:
+            l'id de l'entreprise
+    """
     entreprise = Entreprise.query.filter_by(id=id).first_or_404()
     form = HistoriqueCreationForm()
     if form.validate_on_submit():
@@ -458,6 +583,13 @@ def add_historique(id):
 
 @bp.route("/envoyer_offre/<int:id>", methods=["GET", "POST"])
 def envoyer_offre(id):
+    """
+    Permet d'envoyer une offre à un utilisateur
+
+    Arguments:
+        id:
+            l'id de l'offre
+    """
     offre = EntrepriseOffre.query.filter_by(id=id).first_or_404()
     form = EnvoiOffreForm()
     if form.validate_on_submit():
@@ -484,6 +616,16 @@ def envoyer_offre(id):
 
 @bp.route("/etudiants")
 def json_etudiants():
+    """
+    Permet de récuperer un JSON avec tous les étudiants
+
+    Arguments:
+        term:
+            le terme utilisé pour le filtre de l'autosuggest
+
+    Retourne:
+        le JSON de tous les étudiants (nom, prenom, formation actuelle?) correspondant au terme
+    """
     term = request.args.get("term").strip()
     etudiants = Identite.query.filter(Identite.nom.ilike(f"%{term}%")).all()
     list = []
@@ -505,6 +647,16 @@ def json_etudiants():
 
 @bp.route("/responsables")
 def json_responsables():
+    """
+    Permet de récuperer un JSON avec tous les étudiants
+
+    Arguments:
+        term:
+            le terme utilisé pour le filtre de l'autosuggest
+
+    Retourne:
+        le JSON de tous les utilisateurs (nom, prenom, login) correspondant au terme
+    """
     term = request.args.get("term").strip()
     responsables = User.query.filter(
         User.nom.ilike(f"%{term}%"), User.nom.is_not(None), User.prenom.is_not(None)
@@ -521,6 +673,9 @@ def json_responsables():
 
 @bp.route("/export_entreprises")
 def export_entreprises():
+    """
+    Permet d'exporter la liste des entreprises sous format excel (.xlsx)
+    """
     entreprises = Entreprise.query.all()
     if entreprises:
         keys = ["siret", "nom", "adresse", "ville", "codepostal", "pays"]
@@ -539,6 +694,9 @@ def export_entreprises():
 
 @bp.route("/export_contacts")
 def export_contacts():
+    """
+    Permet d'exporter la liste des contacts sous format excel (.xlsx)
+    """
     contacts = EntrepriseContact.query.all()
     if contacts:
         keys = ["nom", "prenom", "telephone", "mail", "poste", "service"]
@@ -552,10 +710,56 @@ def export_contacts():
         abort(404)
 
 
+@bp.route("/export_contacts_bis")
+def export_contacts_bis():
+    """
+    Permet d'exporter la liste des contacts avec leur entreprise sous format excel (.xlsx)
+    """
+    contacts = EntrepriseContact.query.all()
+    if contacts:
+        keys = [
+            "nom",
+            "prenom",
+            "telephone",
+            "mail",
+            "poste",
+            "service",
+            "nom_entreprise",
+            "siret",
+            "adresse_entreprise",
+            "ville",
+            "codepostal",
+            "pays",
+        ]
+        titles = keys[:]
+        L = [
+            [contact.to_dict_export().get(k, "") for k in keys] for contact in contacts
+        ]
+        title = "contacts"
+        xlsx = sco_excel.excel_simple_table(titles=titles, lines=L, sheet_name=title)
+        filename = title
+        return scu.send_file(xlsx, filename, scu.XLSX_SUFFIX, scu.XLSX_MIMETYPE)
+    else:
+        abort(404)
+
+
 @bp.route(
     "/get_offre_file/<int:entreprise_id>/<int:offre_id>/<string:filedir>/<string:filename>"
 )
 def get_offre_file(entreprise_id, offre_id, filedir, filename):
+    """
+    Permet de télécharger un fichier d'une offre
+
+    Arguments:
+        entreprise_id:
+            l'id de l'entreprise
+        offre_id:
+            l'id de l'offre
+        filedir:
+            le répertoire du fichier
+        filename:
+            le nom du fichier
+    """
     if os.path.isfile(
         os.path.join(
             Config.SCODOC_VAR_DIR,
@@ -583,6 +787,13 @@ def get_offre_file(entreprise_id, offre_id, filedir, filename):
 
 @bp.route("/add_offre_file/<int:offre_id>", methods=["GET", "POST"])
 def add_offre_file(offre_id):
+    """
+    Permet d'ajouter un fichier à une offre
+
+    Arguments:
+        offre_id:
+            l'id de l'offre
+    """
     offre = EntrepriseOffre.query.filter_by(id=offre_id).first_or_404()
     form = AjoutFichierForm()
     if form.validate_on_submit():
@@ -607,6 +818,15 @@ def add_offre_file(offre_id):
 
 @bp.route("/delete_offre_file/<int:offre_id>/<string:filedir>", methods=["GET", "POST"])
 def delete_offre_file(offre_id, filedir):
+    """
+    Permet de supprimer un fichier d'une offre
+
+    Arguments:
+        offre_id:
+            l'id de l'offre
+        filedir:
+            le répertoire du fichier
+    """
     offre = EntrepriseOffre.query.filter_by(id=offre_id).first_or_404()
     form = SuppressionConfirmationForm()
     if form.validate_on_submit():

app/models/etudiants.py

@@ -108,6 +108,9 @@ class Identite(db.Model):
         return r[0] if r else None
 
     def inscription_courante_date(self, date_debut, date_fin):
+        """La première inscription à un formsemestre entre date_debut et date_fin.
+        None s'il n'y en a pas (ou plus, ou pas encore).
+        """
         r = [
             ins
             for ins in self.formsemestre_inscriptions

app/models/formsemestre.py

@@ -147,7 +147,7 @@ class FormSemestre(db.Model):
         return (self.date_debut <= today) and (today <= self.date_fin)
 
     def est_courant_date(self, date_debut, date_fin) -> bool:
-        """Vrai si la date actuelle (now) est dans le semestre
+        """Vrai si date_debut et date_fin est dans le semestre
         (les dates de début et fin sont incluses)
         """
         return (self.date_debut <= date_debut) and (date_fin <= self.date_fin)

app/templates/entreprises/_contact.html

@@ -4,6 +4,12 @@
         Prénom : {{ contact.prenom }}<br>
         Téléphone : {{ contact.telephone }}<br>
         Mail : {{ contact.mail }}<br>
+        {% if contact.poste %}
+        Poste : {{ contact.poste }}<br>
+        {% endif %}
+        {% if contact.service %}
+        Service : {{ contact.service }}<br>
+        {% endif %}
     </p>
 
     <div style="margin-bottom: 10px;">

app/templates/entreprises/contacts.html

@@ -21,6 +21,8 @@
                     <th>Prenom</th>
                     <th>Telephone</th>
                     <th>Mail</th>
+                    <th>Poste</th>
+                    <th>Service</th>
                     <th>Entreprise</th>
                 </tr>
                 {% for contact in contacts %}
@@ -29,6 +31,8 @@
                     <th>{{ contact[0].prenom }}</th>
                     <th>{{ contact[0].telephone }}</th>
                     <th>{{ contact[0].mail }}</th>
+                    <th>{{ contact[0].poste}}</th>
+                    <th>{{ contact[0].service}}</th>
                     <th><a href="{{ url_for('entreprises.fiche_entreprise', id=contact[1].id) }}">{{ contact[1].nom }}</a></th>
                 </tr>
                 {% endfor %}
@@ -40,6 +44,7 @@
         <div>
             {% if contacts %}
                 <a class="btn btn-default" href="{{ url_for('entreprises.export_contacts') }}">Exporter la liste des contacts</a>
+                <a class="btn btn-default" href="{{ url_for('entreprises.export_contacts_bis') }}">Exporter la liste des contacts avec leur entreprise</a>
             {% endif %}
         </div>
     </div>

scodoc.py

@@ -248,6 +248,7 @@ def edit_role(rolename, addpermissionname=None, removepermissionname=None):  # e
         db.session.add(role)
         db.session.commit()
 
+
 @app.cli.command()
 @click.argument("rolename")
 def delete_role(rolename):
@@ -259,6 +260,7 @@ def delete_role(rolename):
     db.session.delete(role)
     db.session.commit()
 
+
 @app.cli.command()
 @click.argument("username")
 @click.option("-d", "--dept", "dept_acronym")