nsarchive 3.0.0b1__tar.gz → 3.0.0b2__tar.gz

nsarchive-3.0.0b2/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.3
+Name: nsarchive
+Version: 3.0.0b2
+Summary: API-wrapper pour récupérer des données liées à Nation
+License: GPL-3.0
+Author: happex
+Author-email: 110610727+okayhappex@users.noreply.github.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: pillow (>=10.4,<11.0)
+Requires-Dist: requests (>=2.31,<3.0)
+Description-Content-Type: text/markdown
+
+# NSArchive v3
+
+## Pré-requis
+
+- Python 3.10 ou + (Python 3.13 si possible)
+- Un serveur avec [nation.db](https://github.com/1nserv/nation-db)
+- Deux barres de Twix ou une tasse de thé
+
+
+## Avant de démarrer
+
+Dans la documentation, vous croiserez souvent des noms de classes comme `.User` ou autres similaires. Le «.» devant le nom de la classe signfie qu'elle appartient au module NSAv3, et qu'il faut donc les interprêter comme `nsarchive.User`. La seule exception est `NSID` qui ne sera pas précédé d'un point mais devra être interprêté de la même manière.
+
+
+## Installation
+
+L'installation de NSAv3 se fait via pip:
+
+```sh
+pip install nsarchive
+```
+
+La dernière version de nsarchive devrait s'installer. Les dépendances requises pour nsarchive sont `pillow` et `requests` mais celles-ci devraient s'installer en même temps que le module. Vous pourriez également avoir besoin des modules `bcrypt` et `python-dotenv`, ceux-ci devront être installés manuellement.
+
+
+### Bonus: Environnement virtuel
+
+Il est recommandé mais non obligatoire d'avoir un environnement virtuel (venv) pour votre projet. Sa création se fait comme ceci:
+
+```sh
+python -m venv .venv
+```
+
+N'oubliez pas de l'activer via cette commande pour powershell...
+
+```ps1
+.venv\Scripts\Activate
+```
+
+...ou cette commande pour les terminaux type UNIX (Bash par exemple)
+
+```sh
+source .venv/Scripts/Activate
+```
+
+## Prise en main
+
+### Identifier les objets
+
+Les objets sont tous identifiables sur NSAv3. Ils ont un identifiant commun appelé NSID (`from nsarchive import NSID`). Cet identifiant n'est rien de plus qu'un nombre hexadécimal. Il peut être utilisé comme un string, dans un print ou un f-string par exemple. Cet identifiant est communément basé sur plusieurs valeurs fixes ou universelles, dont les deux plus fréquentes sont:
+- L'ID Discord de l'objet concerné, dans le cas d'un utilisateur par exemple
+- Le timestamp (secondes depuis 1970) du moment où il a été créé, dans le cas de la plupart des autres objets
+
+
+### Interfaces
+
+Le module nsarchive est divisé en **4 interfaces**:
+- [Entités](/docs/interfaces/entities.md) (membres, groupes, positions)
+- [Économie](/docs/interfaces/economy.md) (comptes en banque, dettes)
+- [Justice](/docs/interfaces/justice.md) (signalements, procès, sanctions)
+- [État](/docs/interfaces/state.md) (votes, élections)
+
+> Les interfaces État et Justice peuvent être confondues et désignées comme République, comme c'était le cas dans les versions précédentes.
+
+
+Les interfaces ont toutes quatre rôles en commun:
+- Vous authentifier
+- Récupérer des objets
+- Créer des objets
+- Supprimer des objets (Entités uniquement)
+
+Une documentation plus détaillée est disponible [ici](/docs/interfaces/README.md).

nsarchive-3.0.0b2/README.md

@@ -0,0 +1,72 @@
+# NSArchive v3
+
+## Pré-requis
+
+- Python 3.10 ou + (Python 3.13 si possible)
+- Un serveur avec [nation.db](https://github.com/1nserv/nation-db)
+- Deux barres de Twix ou une tasse de thé
+
+
+## Avant de démarrer
+
+Dans la documentation, vous croiserez souvent des noms de classes comme `.User` ou autres similaires. Le «.» devant le nom de la classe signfie qu'elle appartient au module NSAv3, et qu'il faut donc les interprêter comme `nsarchive.User`. La seule exception est `NSID` qui ne sera pas précédé d'un point mais devra être interprêté de la même manière.
+
+
+## Installation
+
+L'installation de NSAv3 se fait via pip:
+
+```sh
+pip install nsarchive
+```
+
+La dernière version de nsarchive devrait s'installer. Les dépendances requises pour nsarchive sont `pillow` et `requests` mais celles-ci devraient s'installer en même temps que le module. Vous pourriez également avoir besoin des modules `bcrypt` et `python-dotenv`, ceux-ci devront être installés manuellement.
+
+
+### Bonus: Environnement virtuel
+
+Il est recommandé mais non obligatoire d'avoir un environnement virtuel (venv) pour votre projet. Sa création se fait comme ceci:
+
+```sh
+python -m venv .venv
+```
+
+N'oubliez pas de l'activer via cette commande pour powershell...
+
+```ps1
+.venv\Scripts\Activate
+```
+
+...ou cette commande pour les terminaux type UNIX (Bash par exemple)
+
+```sh
+source .venv/Scripts/Activate
+```
+
+## Prise en main
+
+### Identifier les objets
+
+Les objets sont tous identifiables sur NSAv3. Ils ont un identifiant commun appelé NSID (`from nsarchive import NSID`). Cet identifiant n'est rien de plus qu'un nombre hexadécimal. Il peut être utilisé comme un string, dans un print ou un f-string par exemple. Cet identifiant est communément basé sur plusieurs valeurs fixes ou universelles, dont les deux plus fréquentes sont:
+- L'ID Discord de l'objet concerné, dans le cas d'un utilisateur par exemple
+- Le timestamp (secondes depuis 1970) du moment où il a été créé, dans le cas de la plupart des autres objets
+
+
+### Interfaces
+
+Le module nsarchive est divisé en **4 interfaces**:
+- [Entités](/docs/interfaces/entities.md) (membres, groupes, positions)
+- [Économie](/docs/interfaces/economy.md) (comptes en banque, dettes)
+- [Justice](/docs/interfaces/justice.md) (signalements, procès, sanctions)
+- [État](/docs/interfaces/state.md) (votes, élections)
+
+> Les interfaces État et Justice peuvent être confondues et désignées comme République, comme c'était le cas dans les versions précédentes.
+
+
+Les interfaces ont toutes quatre rôles en commun:
+- Vous authentifier
+- Récupérer des objets
+- Créer des objets
+- Supprimer des objets (Entités uniquement)
+
+Une documentation plus détaillée est disponible [ici](/docs/interfaces/README.md).

{nsarchive-3.0.0b1 → nsarchive-3.0.0b2}/nsarchive/__init__.py

@@ -1,7 +1,7 @@
 """
 nsarchive - API-wrapper pour récupérer des données liées à Nation.
 
-Version: 3.0.0-beta.1
+Version: 3.0.0-beta.2
 Date de sortie: 2025-08-06
 License: GPL-3.0
 Auteur : happex <110610727+okayhappex@users.noreply.github.com>
@@ -24,6 +24,8 @@ from .models.justice import *
 
 from .models.scale import *
 
+from . import errors
+
 # Import des interfaces
 from .models.base import Interface
 from .interfaces._entities import EntityInterface

nsarchive-3.0.0b2/nsarchive/errors/__init__.py

@@ -0,0 +1 @@
+from . import _globals as globals

nsarchive-3.0.0b2/nsarchive/errors/_globals.py

@@ -0,0 +1,29 @@
+class ServerDownError(Exception):
+    def __init__(self, *args):
+        super().__init__(*args)
+
+# 4XX
+
+class MissingParamError(Exception): # 400
+    def __init__(self, *args):
+        super().__init__(*args)
+
+class InvalidParamError(Exception): # 400
+    def __init__(self, *args):
+        super().__init__(*args)
+
+class AuthError(Exception): # 401
+    def __init__(self, *args):
+        super().__init__(*args)
+
+class PermissionError(Exception): # 403
+    def __init__(self, *args):
+        super().__init__(*args)
+
+class NotFoundError(Exception): # 404
+    def __init__(self, *args):
+        super().__init__(*args)
+
+class ConflictError(Exception): # 409
+    def __init__(self, *args):
+        super().__init__(*args)

nsarchive-3.0.0b2/nsarchive/interfaces/_economy.py

@@ -0,0 +1,111 @@
+import time
+
+from ..models.base import *
+from ..models.economy import *
+
+from ..models import economy # Pour les default_headers
+
+class EconomyInterface(Interface):
+    """Interface qui vous permettra d'interagir avec les comptes en banque et les transactions économiques."""
+
+    def __init__(self, url: str, token: str) -> None:
+        super().__init__(url, token)
+
+        economy.default_headers = self.default_headers
+
+    """
+    ---- COMPTES EN BANQUE ----
+    """
+
+    def get_account(self, id: NSID) -> BankAccount:
+        """
+        Récupère les informations d'un compte bancaire.
+
+        ## Paramètres
+        id: `NSID`\n
+            ID du compte.
+
+        ## Renvoie
+        - `.BankAccount`
+        """
+
+        id = NSID(id)
+        res = requests.get(f"{self.url}/bank/accounts/{id}", headers = self.default_headers)
+
+        if res.status_code == 200:
+            _data = res.json()
+        else:
+            res.raise_for_status()
+            return
+
+        if _data is None:
+            return None
+
+        account = BankAccount(id)
+        account._load(_data, self.url, self.default_headers)
+
+        return account
+
+    def save_account(self, account: BankAccount) -> str:
+        """
+        Sauvegarde un compte bancaire dans la base de données.
+
+        ## Paramètres
+        - account: `.BankAccount`\n
+            Compte à sauvegarder
+        """
+
+        _data = {
+            'id': NSID(account.id),
+            'amount': account.amount,
+            'frozen': account.frozen, 
+            'owner_id': account.owner_id, 
+            'bank': account.bank,
+            'income': account.income
+        }
+
+        res = requests.put(f"{self.url}/bank/register_account?owner={_data['owner_id']}", headers = self.default_headers, json = _data)
+
+        if res.status_code == 200:
+            account._url = f"{self.url}/bank/accounts/{account.id}"
+            account.id = res.json()['id']
+
+            return res.json()['digicode']
+        else:
+            res.raise_for_status()
+
+    def fetch_accounts(self, **query: typing.Any) -> list[BankAccount]:
+        """
+        Récupère une liste de comptes en banque en fonction d'une requête.
+
+        ## Paramètres
+        query: `**dict`\n
+            La requête pour filtrer les comptes.
+
+        ## Renvoie
+        - `list[.BankAccount]`
+        """
+
+        query = "&".join(f"{k}={ urllib.parse.quote(v) }" for k, v in query.items())
+
+        _res = requests.get(f"{self.url}/fetch/accounts?{query}", headers = self.default_headers)
+
+        if _res.status_code == 200:
+            _data = _res.json()
+        else:
+            _res.raise_for_status()
+            return []
+
+        res = []
+
+        for _acc in _data:
+            if not _acc: continue
+
+            account = BankAccount(_acc["owner_id"])
+
+            account.id = NSID(_acc['id'])
+            account._load(_acc, self.url, self.default_headers)
+
+            res.append(account)
+
+        return res

{nsarchive-3.0.0b1 → nsarchive-3.0.0b2}/nsarchive/interfaces/_entities.py

@@ -1,6 +1,8 @@
 from ..models.base import *
 from ..models.entities import *
 
+from .. import errors
+
 from ..models import entities # Pour les default_headers
 
 class EntityInterface(Interface):
@@ -41,20 +43,35 @@ class EntityInterface(Interface):
         id = NSID(id)
 
         if _class == "user":
-            _data = self._get_by_ID('individuals', id)
+            res = requests.get(f"{self.url}/model/individuals/{id}", headers = self.default_headers, json = {})
         elif _class == "group":
-            _data = self._get_by_ID('organizations', id)
+            res = requests.get(f"{self.url}/model/organisations/{id}", headers = self.default_headers, json = {})
         else:
-            _data = self._get_by_ID('entities', id)
+            res = requests.get(f"{self.url}/model/entities/{id}", headers = self.default_headers, json = {})
+
+
+        # ERREURS
+
+        if res.status_code == 404:
+            return
+
+        if 500 <= res.status_code < 600:
+            res.raise_for_status()
+
+        if not 200 <= res.status_code < 300:
+            print(res.json()['message'])
+            return
+
 
-        if _data is None: # ID inexistant chez les entités
-            return None
+        # TRAITEMENT
+
+        _data = res.json()
 
         if _data['_class'] == 'individuals':
             entity = User(id)
         elif _data['_class'] == 'organizations':
             entity = Organization(id)
-        else: 
+        else:
             entity = Entity(id)
 
         entity._load(_data, self.url, self.default_headers)
@@ -82,12 +99,37 @@ class EntityInterface(Interface):
         else:
             return
 
-        self._put_in_db(
-            f"/new_model/{_class}?id={id}&name={name}&position={position}&zone={zone}",
+        res = requests.put(
+            f"{self.url}/new_model/{_class}?id={id}&name={name}&position={position}&zone={zone}",
             headers = self.default_headers,
-            use_PUT = True
+            json = {}
         )
 
+
+        # ERREURS
+
+        if 500 <= res.status_code < 600:
+            raise errors.globals.ServerDownError()
+
+        _data = res.json()
+
+        if res.status_code == 400:
+            if _data['message'] == "MissingParam":
+                raise errors.globals.MissingParamError(f"Missing parameter '{_data['param']}'.")
+            elif _data['message'] == "InvalidParam":
+                raise errors.globals.InvalidParamError(f"Invalid parameter '{_data['param']}'.")
+            elif _data['message'] == "InvalidToken":
+                raise errors.globals.AuthError("Token is not valid.")
+
+        elif res.status_code == 401:
+            raise errors.globals.AuthError(_data['message'])
+
+        elif res.status_code == 403:
+            raise errors.globals.PermissionError(_data['message'])
+
+
+        # TRAITEMENT
+
         entity = self.get_entity(id)
 
         if _class == "individuals":
@@ -112,8 +154,27 @@ class EntityInterface(Interface):
 
         res = requests.post(f"{entity._url}/delete", headers = self.default_headers)
 
-        if res.status_code != 200:
-            res.raise_for_status()
+        if 200 <= res.status_code < 300:
+            return
+
+        if 500 <= res.status_code < 600:
+            raise errors.globals.ServerDownError()
+
+        _data = res.json()
+
+        if res.status_code == 400:
+            if _data['message'] == "MissingParam":
+                raise errors.globals.MissingParamError(f"Missing parameter '{_data['param']}'.")
+            elif _data['message'] == "InvalidParam":
+                raise errors.globals.InvalidParamError(f"Invalid parameter '{_data['param']}'.")
+            elif _data['message'] == "InvalidToken":
+                raise errors.globals.AuthError("Token is not valid.")
+
+        elif res.status_code == 401:
+            raise errors.globals.AuthError(_data['message'])
+
+        elif res.status_code == 403:
+            raise errors.globals.PermissionError(_data['message'])
 
     def fetch_entities(self, **query: typing.Any) -> list[ Entity | User | Organization ]:
         """
@@ -172,10 +233,35 @@ class EntityInterface(Interface):
         - `.Position`
         """
 
-        _data = self._get_by_ID('positions', id)
+        res = requests.get(f"{self.url}/model/positions/{id}", headers = self.default_headers)
+
+
+        # ERREURS
+
+        if 500 <= res.status_code < 600:
+            raise errors.globals.ServerDownError()
+
+        _data = res.json()
+
+        if res.status_code == 400:
+            if _data['message'] == "MissingParam":
+                raise errors.globals.MissingParamError(f"Missing parameter '{_data['param']}'.")
+            elif _data['message'] == "InvalidParam":
+                raise errors.globals.InvalidParamError(f"Invalid parameter '{_data['param']}'.")
+            elif _data['message'] == "InvalidToken":
+                raise errors.globals.AuthError("Token is not valid.")
+
+        elif res.status_code == 401:
+            raise errors.globals.AuthError(_data['message'])
+
+        elif res.status_code == 403:
+            raise errors.globals.PermissionError(_data['message'])
+
+        elif res.status_code == 404:
+            return
+
 
-        if _data is None:
-            return None
+        # TRAITEMENT
 
         position = Position(id)
         position._load(_data, self.url, self.default_headers)