Add collections endpoint (#57)

Closes #43

Signed-off-by: sami-m-g <sami.mg@outlook.com>
Reviewed-by: João Gonçalves <jsvgoncalves@gmail.com>

Author: sami-m-g

dds_glossary/database.py

@@ -92,7 +92,7 @@ def get_concept_schemes(engine: Engine) -> list[ConceptScheme]:
         return session.query(ConceptScheme).all()
 
 
-def get_concept_scheme(engine: Engine, concept_scheme_iri: str) -> ConceptScheme | None:
+def get_concept_scheme(engine: Engine, concept_scheme_iri: str) -> ConceptScheme:
     """
     Get the concept scheme from the database.
 
@@ -101,7 +101,10 @@ def get_concept_scheme(engine: Engine, concept_scheme_iri: str) -> ConceptScheme
         concept_scheme_iri (str): The concept scheme IRI.
 
     Returns:
-        ConceptScheme | None: The concept scheme or None if not found.
+        ConceptScheme: The concept scheme.
+
+    Raises:
+        NoResultFound: If the concept scheme is not found.
     """
     with Session(engine) as session:
         member_polymorphic = with_polymorphic(
@@ -113,11 +116,11 @@ def get_concept_scheme(engine: Engine, concept_scheme_iri: str) -> ConceptScheme
             session.query(ConceptScheme)
             .where(ConceptScheme.iri == concept_scheme_iri)
             .options(joinedload(ConceptScheme.members.of_type(member_polymorphic)))
-            .one_or_none()
+            .one()
         )
 
 
-def get_collection(engine: Engine, collection_iri: str) -> Collection | None:
+def get_collection(engine: Engine, collection_iri: str) -> Collection:
     """
     Get the collection from the database.
 
@@ -126,7 +129,10 @@ def get_collection(engine: Engine, collection_iri: str) -> Collection | None:
         collection_iri (str): The collection IRI.
 
     Returns:
-        Collection | None: The collection or None if not found.
+        Collection: The collection.
+
+    Raises:
+        NoResultFound: If the collection is not found.
     """
     with Session(engine) as session:
         member_polymorphic = with_polymorphic(
@@ -138,27 +144,30 @@ def get_collection(engine: Engine, collection_iri: str) -> Collection | None:
             session.query(Collection)
             .where(Collection.iri == collection_iri)
             .options(joinedload(Collection.members.of_type(member_polymorphic)))
-            .one_or_none()
+            .one()
         )
 
 
-def get_concept(engine: Engine, concept_iri: str) -> Concept | None:
+def get_concept(engine: Engine, concept_iri: str) -> Concept:
     """
-    Get the concept from the database, if found.
+    Get the concept from the database.
 
     Args:
         engine (Engine): The database engine.
         concept_iri (str): The concept IRI.
 
     Return:
-        Concept | None: The concept or None if not found.
+        Concept: The concept or None if not found.
+
+    Raises:
+        NoResultFound: If the concept is not found.
     """
     with Session(engine) as session:
         return (
             session.query(Concept)
             .where(Concept.iri == concept_iri)
             .options(joinedload(Concept.concept_schemes))
-            .one_or_none()
+            .one()
         )
 
 

dds_glossary/exceptions.py

@@ -0,0 +1,37 @@
+"""Exception classes for the dds_glossary package."""
+
+from http import HTTPStatus
+
+from fastapi import HTTPException
+
+
+class DDSGlossaryException(HTTPException):
+    """Base class for exceptions in the dds_glossary package."""
+
+
+class EntityNotFound(DDSGlossaryException):
+    """Exception raised when an entity is not found."""
+
+    def __init__(self, entity_name: str, entity_iri: str) -> None:
+        super().__init__(HTTPStatus.NOT_FOUND, f"{entity_name} {entity_iri} not found.")
+
+
+class ConceptSchemeNotFoundException(EntityNotFound):
+    """Exception raised when a concept scheme is not found."""
+
+    def __init__(self, concept_scheme_iri: str) -> None:
+        super().__init__("Concept scheme", concept_scheme_iri)
+
+
+class ConceptNotFoundException(EntityNotFound):
+    """Exception raised when a concept is not found."""
+
+    def __init__(self, concept_iri: str) -> None:
+        super().__init__("Concept", concept_iri)
+
+
+class CollectionNotFoundException(EntityNotFound):
+    """Exception raised when a collection is not found."""
+
+    def __init__(self, collection_iri: str) -> None:
+        super().__init__("Collection", collection_iri)

dds_glossary/routes.py

@@ -1,9 +1,7 @@
 """Routes for the dds_glossary server."""
 
-from http import HTTPStatus
-
 from fastapi import APIRouter, Depends, Request
-from fastapi.responses import JSONResponse, RedirectResponse
+from fastapi.responses import RedirectResponse
 from fastapi_versioning import version
 from starlette.templating import Jinja2Templates, _TemplateResponse
 
@@ -12,7 +10,9 @@
     CollectionResponse,
     ConceptResponse,
     ConceptSchemeResponse,
-    FullConeptResponse,
+    EntityResponse,
+    FullConceptResponse,
+    FullConceptSchemeResponse,
     InitDatasetsResponse,
     VersionResponse,
 )
@@ -141,29 +141,47 @@ def get_concept_schemes(
     return controller.get_concept_schemes(lang=lang)
 
 
-@router_versioned.get("/concepts")
+@router_versioned.get("/scheme")
 @version(0, 1)
-def get_concepts(
+def get_concept_scheme(
     concept_scheme_iri: str,
     controller: GlossaryController = Depends(get_controller),
     lang: str = "en",
-) -> JSONResponse:
+) -> FullConceptSchemeResponse:
     """
-    Returns all the saved concepts for a concept scheme.
+    Returns a concept scheme.
 
     Args:
         concept_scheme_iri (str): The concept scheme IRI.
         controller (GlossaryController): The glossary controller.
         lang (str): The language. Defaults to "en".
 
     Returns:
-        JSONResponse: The concepts.
+        FullConceptSchemeResponse: The concept scheme with member
+            concepts and collections.
     """
-    return JSONResponse(
-        content={"concepts": controller.get_concepts(concept_scheme_iri, lang=lang)},
-        media_type="application/json",
-        status_code=HTTPStatus.OK,
-    )
+    return controller.get_concept_scheme(concept_scheme_iri, lang=lang)
+
+
+@router_versioned.get("/collections")
+@version(0, 1)
+def get_collections(
+    concept_scheme_iri: str,
+    controller: GlossaryController = Depends(get_controller),
+    lang: str = "en",
+) -> list[EntityResponse]:
+    """
+    Returns all the collections.
+
+    Args:
+        concept_scheme_iri (str): The concept scheme IRI.
+        controller (GlossaryController): The glossary controller.
+        lang (str): The language. Defaults to "en".
+
+    Returns:
+        list[CollectionResponse]: The collections.
+    """
+    return controller.get_collections(concept_scheme_iri, lang=lang)
 
 
 @router_versioned.get("/collection")
@@ -175,23 +193,47 @@ def get_collection(
 ) -> CollectionResponse:
     """
     Returns a collection.
+
     Args:
         collection_iri (str): The collection IRI.
         controller (GlossaryController): The glossary controller.
         lang (str): The language. Defaults to "en".
+
     Returns:
-        JSONResponse: The collection.
+        CollectionResponse: The collection with member collections
+            and concepts.
     """
     return controller.get_collection(collection_iri, lang=lang)
 
 
+@router_versioned.get("/concepts")
+@version(0, 1)
+def get_concepts(
+    concept_scheme_iri: str,
+    controller: GlossaryController = Depends(get_controller),
+    lang: str = "en",
+) -> list[ConceptResponse]:
+    """
+    Returns all the concepts in a concept scheme.
+
+    Args:
+        concept_scheme_iri (str): The concept scheme IRI.
+        controller (GlossaryController): The glossary controller.
+        lang (str): The language. Defaults to "en".
+
+    Returns:
+        list[ConceptResponse]: The concepts.
+    """
+    return controller.get_concepts(concept_scheme_iri, lang=lang)
+
+
 @router_versioned.get("/concept")
 @version(0, 1)
 def get_concept(
     concept_iri: str,
     controller: GlossaryController = Depends(get_controller),
     lang: str = "en",
-) -> FullConeptResponse:
+) -> FullConceptResponse:
     """
     Returns a concept.
 
@@ -200,6 +242,6 @@ def get_concept(
         lang (str): The language. Defaults to "en".
 
     Returns:
-        FullConeptResponse: The concept with concept scheme and relations.
+        FullConceptResponse: The concept with concept scheme and relations.
     """
     return controller.get_concept(concept_iri, lang=lang)

dds_glossary/schema.py

@@ -57,17 +57,6 @@ class ConceptSchemeResponse(EntityResponse):
     scopeNote: str
 
 
-class CollectionResponse(EntityResponse):
-    """
-    Response model for the Collection model with members.
-
-    Attributes:
-        members (list[EntityResponse]): The members of the collection.
-    """
-
-    members: list[EntityResponse]
-
-
 class RelationResponse(BaseModel):
     """
     Response model for the SemanticRelation model.
@@ -98,7 +87,33 @@ class ConceptResponse(EntityResponse):
     altLabels: list[str]
 
 
-class FullConeptResponse(ConceptResponse):
+class FullConceptSchemeResponse(ConceptSchemeResponse):
+    """
+    Response model for the ConceptScheme model with collections and concepts.
+
+    Attributes:
+        collections (list[EntityResponse]): The collections.
+        concepts (list[ConceptResponse]): The concepts.
+    """
+
+    collections: list[EntityResponse]
+    concepts: list[ConceptResponse]
+
+
+class CollectionResponse(EntityResponse):
+    """
+    Response model for the Collection model with members.
+
+    Attributes:
+        collections (list[EntityResponse]): The collections.
+        concepts (list[ConceptResponse]): The concepts.
+    """
+
+    collections: list[EntityResponse]
+    concepts: list[ConceptResponse]
+
+
+class FullConceptResponse(ConceptResponse):
     """
     Response model for the Concept model with concept schemes and relations.