publish structure (#33)

* Don't query more than the limit articles

* Let users know about the structure as a whole

* Update version

Author: odarbelaeze

src/bibx/__init__.py

@@ -3,20 +3,21 @@
 import logging
 from typing import TextIO
 
-from bibx._entities.article import Article
-from bibx._entities.collection import Collection
-from bibx._entities.collection_builders.openalex import OpenAlexCollectionBuilder
-from bibx._entities.collection_builders.scopus_bib import ScopusBibCollectionBuilder
-from bibx._entities.collection_builders.scopus_ris import ScopusRisCollectionBuilder
-from bibx._entities.collection_builders.wos import WosCollectionBuilder
 from bibx.algorithms.sap import Sap
+from bibx.article import Article
+from bibx.builders.openalex import HandleReferences, OpenAlexCollectionBuilder
+from bibx.builders.scopus_bib import ScopusBibCollectionBuilder
+from bibx.builders.scopus_ris import ScopusRisCollectionBuilder
+from bibx.builders.wos import WosCollectionBuilder
+from bibx.collection import Collection
 from bibx.exceptions import BibXError
 
 logger = logging.getLogger(__name__)
 
 __all__ = [
     "Article",
     "Collection",
+    "HandleReferences",
     "Sap",
     "query_openalex",
     "read_any",
@@ -25,12 +26,16 @@
     "read_wos",
 ]
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"
 
 
-def query_openalex(query: str, limit: int = 600) -> Collection:
+def query_openalex(
+    query: str,
+    limit: int = 600,
+    references: HandleReferences = HandleReferences.BASIC,
+) -> Collection:
     """Query OpenAlex and return a collection."""
-    return OpenAlexCollectionBuilder(query, limit).build()
+    return OpenAlexCollectionBuilder(query, limit, references=references).build()
 
 
 def read_scopus_bib(*files: TextIO) -> Collection:

src/bibx/_entities/__init__.py

@@ -5,7 +5,7 @@
 from xlsxwriter import Workbook
 from xlsxwriter.worksheet import Worksheet
 
-from bibx import Collection
+from bibx.collection import Collection
 
 from .sap import BRANCH, LEAF, ROOT, TRUNK, Sap
 

src/bibx/_entities/collection_builders/__init__.py

@@ -4,7 +4,8 @@
 import networkx as nx
 from networkx.algorithms.community.louvain import louvain_communities
 
-from bibx import Article, Collection
+from bibx.article import Article
+from bibx.collection import Collection
 
 YEAR = "year"
 LEAF = "leaf"

src/bibx/_entities/collection_builders/base.py

@@ -15,6 +15,8 @@ def _keep_longest(a: str, b: str) -> str:
 
 @dataclass
 class Article:
+    """A scientific article."""
+
     label: str
     ids: set[str]
     authors: list[str] = field(default_factory=list)
@@ -55,10 +57,12 @@ def merge(self, other: "Article") -> "Article":
 
     @property
     def key(self) -> str:
+        """Return the first ID of the article."""
         return next(iter(sorted(self.ids)))
 
     @property
     def simple_label(self) -> Optional[str]:
+        """Return a simple label for the article."""
         pieces = {
             "AU": self.authors[0].replace(",", "") if self.authors else None,
             "PY": str(self.year) if self.year else None,
@@ -73,6 +77,7 @@ def simple_label(self) -> Optional[str]:
 
     @property
     def permalink(self) -> Optional[str]:
+        """Return the permalink of the article."""
         if self._permalink is not None:
             return self._permalink
         if self.doi is not None:
@@ -81,21 +86,25 @@ def permalink(self) -> Optional[str]:
 
     @property
     def simple_id(self) -> Optional[str]:
+        """Return a simple ID for the article."""
         if self.authors and self.year is not None:
             author = self.authors[0].split(" ")[0].replace(",", "")
             return f"{author}{self.year}".lower()
         return None
 
     def __repr__(self) -> str:
+        """Return a string representation of the article."""
         return f"Article(ids={self.ids!r}, authors={self.authors!r})"
 
     def add_simple_id(self) -> "Article":
+        """Add a simple ID to the article."""
         if self.simple_id is None:
             return self
         self.ids.add(f"simple:{self.simple_id}")
         return self
 
     def set_simple_label(self) -> "Article":
+        """Set the simple label as the label of the article."""
         if self.simple_label is None:
             return self
         self.label = self.simple_label
@@ -104,6 +113,7 @@ def set_simple_label(self) -> "Article":
     def info(
         self,
     ) -> dict[str, Union[str, int, list[str], None]]:
+        """Return a dictionary with the information of the article."""
         return {
             "permalink": self.permalink,
             "label": self.label,

src/bibx/_entities/collection_builders/cross_ref.py

@@ -0,0 +1 @@
+"""Builders for diverse Collection types."""