nsarchive 2.0.0a1

API-wrapper pour récupérer des données liées à Nation

nsarchive

nsarchive est un module Python pour la gestion des entités (utilisateurs et organisations) à l'aide de la base de données Deta. Ce module permet de créer, récupérer, sauvegarder et gérer des entités et leurs attributs spécifiques.

Pré-requis

Listes des choses à avoir afin de pouvoir utiliser le module correctement:

• Python 3.10 ou supérieur
• Un token Deta, donné par un administrateur ou pour votre collection personnelle
• Un bon capuccino, pour commencer la programmation en bons termes

Note: Il vous faudra un token différent pour accéder aux différentes parties de la base de données. Vos tokens n'expireront pas à moins que l'ordre en aura été donné

Installation

Vous pouvez installer ce module via pip :

pip install nsarchive

Utilisation

Importation et Initialisation

Pour utiliser nsarchive, commencez par importer le module et initialiser une instance d'EntityInstance avec votre token Deta.

from nsarchive import EntityInstance

# Remplacez 'your_deta_token' par votre véritable token Deta
entity_instance = EntityInstance(token = 'your_deta_token')

Récupérer une Entité

Vous pouvez récupérer une entité (Utilisateur ou Organisation) à l'aide de son ID.

entity = entity_instance.get_entity(id = 'entity_id')
print(entity.name)

ATTENTION: Les entités sont identifiées sous une forme hexadécimale. Pour les avoir, vous devez convertir leur ID Discord en hexadécimale puis enlever le préfixe 0x.

Pour les organisations, l'ID Discord correspondra à la formule suivante: ID fondateur // 100000.

N'oubliez pas de toujours utiliser un str dans les ID pour interagir avec la base de données.

Sauvegarder une Entité

Après avoir modifié une entité, vous pouvez la sauvegarder dans la base de données.

entity.rename("Nouveau Nom")
entity_instance.save_entity(entity)

Rechercher des Entités

Vous pouvez rechercher des entités avec des critères spécifiques.

entities = entity_instance.fetch_entity(query = {'name': 'Alice'})
for entity in entities:
    print(entity['name'])

Gérer les Organisations

Les organisations peuvent avoir des membres et des certifications. Voici comment ajouter un membre ou une certification.

organization = entity_instance.get_entity(id = 'org_id')
user = entity_instance.get_entity(id = 'user_id')

# Ajouter un membre
organization.add_member(user)
entity_instance.save_entity(organization)

# Ajouter une certification
organization.add_certification('Certification Example')
entity_instance.save_entity(organization)

Les certifications pourront être utilisées pour vérifier l'officialité d'une organisation, mais également pour déterminer si l'on peut accorder (ou non) des permissions à ses membres.

Exemples de Classes

Entity

Classe parente des classes User et Organization, elle est utilisée lorsque le module ne peut pas déterminer l'appartenance d'une identité à l'une de ces deux classes ou à l'autre.

from nsarchive.cls.entities import Entity

entity = Entity(id='entity_id')
entity.rename('New Name')
entity.add_xp(100)
print(entity.get_level())

User

from nsarchive.cls.entities import User

user = User(id = 'user_id')
user.edit_boost(name = 'admin', multiplier = 5) # Négliger le paramètre <multiplier> ou le fixer à un nombre négatif reviendrait à supprimer le boost.
print(user.boosts)

Note: Lorsqu'on ajoute de l'expérience à un utilisateur via la méthode add_xp, le nombre de points ajoutés est automatiquement multiplié par le bonus le plus important dont l'utilisateur bénéficie.

Organization

from nsarchive.cls.entities import Organization

organization = Organization(id = 'org_id')
organization.set_owner(user)
organization.add_member(user)
print(organization.members)

Note: Les attributs owner et members sont indépendants. L'owner peut être n'importe quelle personne faisant ou non partie des members.

Gestion des Exceptions

nsarchive fournit des exceptions spécifiques pour gérer les erreurs courantes.

NameTooLongError

Lancé lorsque le nom d'une entité dépasse la longueur maximale autorisée (32 caractères).

from nsarchive.cls.exceptions import NameTooLongError

try:
    entity.rename('Ce nom est long, voire même très long, je dirais même extrêmement long')
except NameTooLongError as e:
    print(e)

EntityTypeError

Lancé lorsque le type d'entité est incorrect. Vous ne devriez normalement pas la rencontrer en utilisant le module, mais elle pourrait vous être utile.

from nsarchive.cls.exceptions import EntityTypeError

try:
    # Code qui peut lancer une EntityTypeError
except EntityTypeError as e:
    print(e)

License

Ce projet est sous licence GNU GPL-3.0 - Voir le fichier LICENSE pour plus de détails.