pub-analyzer 0.1.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

pub_analyzer/internal/report.py

@@ -2,27 +2,72 @@
 
 import datetime
 import math
-from typing import Any
+from typing import Any, NewType
 
 import httpx
 from pydantic import TypeAdapter
 
 from pub_analyzer.internal import identifier
-from pub_analyzer.models.author import Author
-from pub_analyzer.models.institution import Institution
+from pub_analyzer.models.author import Author, AuthorOpenAlexKey, AuthorResult, DehydratedAuthor
+from pub_analyzer.models.institution import DehydratedInstitution, Institution, InstitutionOpenAlexKey, InstitutionResult
 from pub_analyzer.models.report import (
     AuthorReport,
     CitationReport,
-    CitationResume,
+    CitationSummary,
     CitationType,
     InstitutionReport,
-    OpenAccessResume,
-    SourcesResume,
+    OpenAccessSummary,
+    SourcesSummary,
     WorkReport,
     WorkTypeCounter,
 )
+from pub_analyzer.models.source import DehydratedSource, Source
 from pub_analyzer.models.work import Authorship, Work
 
+FromDate = NewType("FromDate", datetime.datetime)
+"""DateTime marker for works published from this date."""
+
+ToDate = NewType("ToDate", datetime.datetime)
+"""DateTime marker for works published up to this date."""
+
+
+def _get_author_profiles_keys(
+    author: Author, extra_profiles: list[Author | AuthorResult | DehydratedAuthor] | None
+) -> list[AuthorOpenAlexKey]:
+    """Create a list of profiles IDs joining main author profile and extra author profiles.
+
+    Args:
+        author: Main OpenAlex author object.
+        extra_profiles: Extra OpenAlex authors objects related with the main author.
+
+    Returns:
+        List of Author OpenAlex Keys.
+    """
+    if extra_profiles:
+        profiles = [author, *extra_profiles]
+        return [identifier.get_author_id(profile) for profile in profiles]
+    else:
+        return [identifier.get_author_id(author)]
+
+
+def _get_institution_keys(
+    institution: Institution, extra_profiles: list[Institution | InstitutionResult | DehydratedInstitution] | None
+) -> list[InstitutionOpenAlexKey]:
+    """Create a list of profiles IDs joining main institution profile and extra institution profiles.
+
+    Args:
+        institution: Main OpenAlex institution object.
+        extra_profiles: Extra OpenAlex institutions objects related with the main institution.
+
+    Returns:
+        List of Institution OpenAlex Keys.
+    """
+    if extra_profiles:
+        profiles = [institution, *extra_profiles]
+        return [identifier.get_institution_id(profile) for profile in profiles]
+    else:
+        return [identifier.get_institution_id(institution)]
+
 
 def _get_authors_list(authorships: list[Authorship]) -> list[str]:
     """Collect OpenAlex IDs from authors in a list of authorships.
@@ -93,7 +138,7 @@ def _get_valid_works(works: list[dict[str, Any]]) -> list[dict[str, Any]]:
         In response, we have chosen to exclude such works at this stage, thus avoiding
         the need to handle exceptions within the Model validators.
     """
-    return [_add_work_abstract(work) for work in works if work['title'] is not None]
+    return [_add_work_abstract(work) for work in works if work["title"] is not None]
 
 
 async def _get_works(client: httpx.AsyncClient, url: str) -> list[Work]:
@@ -118,7 +163,7 @@ async def _get_works(client: httpx.AsyncClient, url: str) -> list[Work]:
     meta_info = json_response["meta"]
     page_count = math.ceil(meta_info["count"] / meta_info["per_page"])
 
-    works_data = list(_get_valid_works(json_response["results"]),)
+    works_data = list(_get_valid_works(json_response["results"]))
 
     for page_number in range(1, page_count):
         page_result = (await client.get(url + f"&page={page_number + 1}")).json()
@@ -127,13 +172,44 @@ async def _get_works(client: httpx.AsyncClient, url: str) -> list[Work]:
     return TypeAdapter(list[Work]).validate_python(works_data)
 
 
-async def make_author_report(author: Author, from_date: datetime.date | None = None, to_date: datetime.date | None = None) -> AuthorReport:
+async def _get_source(client: httpx.AsyncClient, url: str) -> Source:
+    """Get source given a URL.
+
+    Args:
+        client: HTTPX asynchronous client to be used to make the requests.
+        url: URL of works with all filters.
+
+    Returns:
+        Source Model.
+
+    Raises:
+        httpx.HTTPStatusError: One response from OpenAlex API had an error HTTP status of 4xx or 5xx.
+    """
+    response = await client.get(url=url)
+    response.raise_for_status()
+
+    return Source(**response.json())
+
+
+async def make_author_report(
+    author: Author,
+    extra_profiles: list[Author | AuthorResult | DehydratedAuthor] | None = None,
+    pub_from_date: FromDate | None = None,
+    pub_to_date: ToDate | None = None,
+    cited_from_date: FromDate | None = None,
+    cited_to_date: ToDate | None = None,
+) -> AuthorReport:
     """Make a scientific production report by Author.
 
     Args:
         author: Author to whom the report is generated.
-        from_date: Filter works published from this date.
-        to_date: Filter works published up to this date.
+        extra_profiles: List of author profiles whose works will be attached.
+
+        pub_from_date: Filter works published from this date.
+        pub_to_date: Filter works published up to this date.
+
+        cited_from_date: Filter works that cite the author, published after this date.
+        cited_to_date: Filter works that cite the author, published up to this date.
 
     Returns:
         Author's scientific production report Model.
@@ -141,31 +217,40 @@ async def make_author_report(author: Author, from_date: datetime.date | None = N
     Raises:
         httpx.HTTPStatusError: One response from OpenAlex API had an error HTTP status of 4xx or 5xx.
     """
-    author_id = identifier.get_author_id(author)
+    author_profiles_keys = _get_author_profiles_keys(author, extra_profiles)
+    profiles_query_parameter = "|".join(author_profiles_keys)
 
-    from_filter = f",from_publication_date:{from_date:%Y-%m-%d}" if from_date else ""
-    to_filter = f",to_publication_date:{to_date:%Y-%m-%d}" if to_date else ""
-    url = f"https://api.openalex.org/works?filter=author.id:{author_id}{from_filter}{to_filter}&sort=publication_date"
+    pub_from_filter = f",from_publication_date:{pub_from_date:%Y-%m-%d}" if pub_from_date else ""
+    pub_to_filter = f",to_publication_date:{pub_to_date:%Y-%m-%d}" if pub_to_date else ""
+    url = (
+        f"https://api.openalex.org/works?filter=author.id:{profiles_query_parameter}{pub_from_filter}{pub_to_filter}&sort=publication_date"
+    )
 
     async with httpx.AsyncClient() as client:
         # Getting all the author works.
         author_works = await _get_works(client, url)
 
+        # Extra filters
+        cited_from_filter = f",from_publication_date:{cited_from_date:%Y-%m-%d}" if cited_from_date else ""
+        cited_to_filter = f",to_publication_date:{cited_to_date:%Y-%m-%d}" if cited_to_date else ""
+
         # Report fields.
         works: list[WorkReport] = []
-        report_citation_resume = CitationResume()
-        open_access_resume = OpenAccessResume()
+        report_citation_summary = CitationSummary()
+        open_access_summary = OpenAccessSummary()
         works_type_counter: list[WorkTypeCounter] = []
-        sources_resume = SourcesResume(sources=[])
+        dehydrated_sources: list[DehydratedSource] = []
 
         # Getting all works that have cited the author.
         for author_work in author_works:
             work_id = identifier.get_work_id(author_work)
             work_authors = _get_authors_list(authorships=author_work.authorships)
-            cited_by_api_url = f"https://api.openalex.org/works?filter=cites:{work_id}&sort=publication_date"
+            cited_by_api_url = (
+                f"https://api.openalex.org/works?filter=cites:{work_id}{cited_from_filter}{cited_to_filter}&sort=publication_date"
+            )
 
             # Adding the type of OpenAccess in the counter.
-            open_access_resume.add_oa_type(author_work.open_access.oa_status)
+            open_access_summary.add_oa_type(author_work.open_access.oa_status)
 
             # Adding the work type to works type counter.
             work_type = next((work_type for work_type in works_type_counter if work_type.type_name == author_work.type), None)
@@ -176,43 +261,64 @@ async def make_author_report(author: Author, from_date: datetime.date | None = N
 
             # Add Sources to global list.
             for location in author_work.locations:
-                if location.source and not any(source.display_name == location.source.display_name for source in sources_resume.sources):
-                    sources_resume.sources.append(location.source)
+                if location.source and not any(source.id == location.source.id for source in dehydrated_sources):
+                    dehydrated_sources.append(location.source)
 
             cited_by_works = await _get_works(client, cited_by_api_url)
             cited_by: list[CitationReport] = []
-            work_citation_resume = CitationResume()
+            work_citation_summary = CitationSummary()
             for cited_by_work in cited_by_works:
                 cited_authors = _get_authors_list(authorships=cited_by_work.authorships)
                 citation_type = _get_citation_type(work_authors, cited_authors)
 
                 # Adding the type of cites in the counters.
-                report_citation_resume.add_cite_type(citation_type)
-                work_citation_resume.add_cite_type(citation_type)
+                report_citation_summary.add_cite_type(citation_type)
+                work_citation_summary.add_cite_type(citation_type)
 
                 cited_by.append(CitationReport(work=cited_by_work, citation_type=citation_type))
 
-            works.append(WorkReport(work=author_work, cited_by=cited_by, citation_resume=work_citation_resume))
+            works.append(WorkReport(work=author_work, cited_by=cited_by, citation_summary=work_citation_summary))
+
+        # Get sources full info.
+        sources: list[Source] = []
+        for dehydrated_source in dehydrated_sources:
+            source_id = identifier.get_source_id(dehydrated_source)
+            source_url = f"https://api.openalex.org/sources/{source_id}"
+            sources.append(await _get_source(client, source_url))
+
+        # Sort sources by h_index
+        sources_sorted = sorted(sources, key=lambda source: source.summary_stats.two_yr_mean_citedness, reverse=True)
+        sources_summary = SourcesSummary(sources=sources_sorted)
 
     return AuthorReport(
         author=author,
         works=works,
-        citation_resume=report_citation_resume,
-        open_access_resume=open_access_resume,
-        works_type_resume=works_type_counter,
-        sources_resume=sources_resume
+        citation_summary=report_citation_summary,
+        open_access_summary=open_access_summary,
+        works_type_summary=works_type_counter,
+        sources_summary=sources_summary,
     )
 
 
 async def make_institution_report(
-        institution: Institution, from_date: datetime.date | None = None, to_date: datetime.date | None = None
-    ) -> InstitutionReport:
+    institution: Institution,
+    extra_profiles: list[Institution | InstitutionResult | DehydratedInstitution] | None = None,
+    pub_from_date: FromDate | None = None,
+    pub_to_date: ToDate | None = None,
+    cited_from_date: FromDate | None = None,
+    cited_to_date: ToDate | None = None,
+) -> InstitutionReport:
     """Make a scientific production report by Institution.
 
     Args:
         institution: Institution to which the report is generated.
-        from_date: Filter works published from this date.
-        to_date: Filter works published up to this date.
+        extra_profiles: List of institutions profiles whose works will be attached.
+
+        pub_from_date: Filter works published from this date.
+        pub_to_date: Filter works published up to this date.
+
+        cited_from_date: Filter works that cite the institution, published after this date.
+        cited_to_date: Filter works that cite the institution, published up to this date.
 
     Returns:
         Institution's scientific production report Model.
@@ -220,31 +326,38 @@ async def make_institution_report(
     Raises:
         httpx.HTTPStatusError: One response from OpenAlex API had an error HTTP status of 4xx or 5xx.
     """
-    institution_id = identifier.get_institution_id(institution)
+    institution_keys = _get_institution_keys(institution, extra_profiles)
+    institution_query_parameter = "|".join(institution_keys)
 
-    from_filter = f",from_publication_date:{from_date:%Y-%m-%d}" if from_date else ""
-    to_filter = f",to_publication_date:{to_date:%Y-%m-%d}" if to_date else ""
-    url = f"https://api.openalex.org/works?filter=institutions.id:{institution_id}{from_filter}{to_filter}&sort=publication_date"
+    pub_from_filter = f",from_publication_date:{pub_from_date:%Y-%m-%d}" if pub_from_date else ""
+    pub_to_filter = f",to_publication_date:{pub_to_date:%Y-%m-%d}" if pub_to_date else ""
+    url = f"https://api.openalex.org/works?filter=institutions.id:{institution_query_parameter}{pub_from_filter}{pub_to_filter}&sort=publication_date"
 
     async with httpx.AsyncClient() as client:
         # Getting all the institution works.
         institution_works = await _get_works(client=client, url=url)
 
+        # Extra filters
+        cited_from_filter = f",from_publication_date:{cited_from_date:%Y-%m-%d}" if cited_from_date else ""
+        cited_to_filter = f",to_publication_date:{cited_to_date:%Y-%m-%d}" if cited_to_date else ""
+
         # Report fields.
         works: list[WorkReport] = []
-        report_citation_resume = CitationResume()
-        open_access_resume = OpenAccessResume()
+        report_citation_summary = CitationSummary()
+        open_access_summary = OpenAccessSummary()
         works_type_counter: list[WorkTypeCounter] = []
-        sources_resume = SourcesResume(sources=[])
+        dehydrated_sources: list[DehydratedSource] = []
 
         # Getting all works that have cited a work.
         for institution_work in institution_works:
             work_id = identifier.get_work_id(institution_work)
             work_authors = _get_authors_list(authorships=institution_work.authorships)
-            cited_by_api_url = f"https://api.openalex.org/works?filter=cites:{work_id}&sort=publication_date"
+            cited_by_api_url = (
+                f"https://api.openalex.org/works?filter=cites:{work_id}{cited_from_filter}{cited_to_filter}&sort=publication_date"
+            )
 
             # Adding the type of OpenAccess in the counter.
-            open_access_resume.add_oa_type(institution_work.open_access.oa_status)
+            open_access_summary.add_oa_type(institution_work.open_access.oa_status)
 
             # Adding the work type to works type counter.
             work_type = next((work_type for work_type in works_type_counter if work_type.type_name == institution_work.type), None)
@@ -255,29 +368,40 @@ async def make_institution_report(
 
             # Add Sources to global list.
             for location in institution_work.locations:
-                if location.source and not any(source.display_name == location.source.display_name for source in sources_resume.sources):
-                    sources_resume.sources.append(location.source)
+                if location.source and not any(source.id == location.source.id for source in dehydrated_sources):
+                    dehydrated_sources.append(location.source)
 
             cited_by_works = await _get_works(client, cited_by_api_url)
             cited_by: list[CitationReport] = []
-            work_citation_resume = CitationResume()
+            work_citation_summary = CitationSummary()
             for cited_by_work in cited_by_works:
                 cited_authors = _get_authors_list(authorships=cited_by_work.authorships)
                 citation_type = _get_citation_type(work_authors, cited_authors)
 
                 # Adding the type of cites in the counters.
-                report_citation_resume.add_cite_type(citation_type)
-                work_citation_resume.add_cite_type(citation_type)
+                report_citation_summary.add_cite_type(citation_type)
+                work_citation_summary.add_cite_type(citation_type)
 
                 cited_by.append(CitationReport(work=cited_by_work, citation_type=citation_type))
 
-            works.append(WorkReport(work=institution_work, cited_by=cited_by, citation_resume=work_citation_resume))
+            works.append(WorkReport(work=institution_work, cited_by=cited_by, citation_summary=work_citation_summary))
+
+        # Get sources full info.
+        sources: list[Source] = []
+        for dehydrated_source in dehydrated_sources:
+            source_id = identifier.get_source_id(dehydrated_source)
+            source_url = f"https://api.openalex.org/sources/{source_id}"
+            sources.append(await _get_source(client, source_url))
+
+        # Sort sources by h_index
+        sources_sorted = sorted(sources, key=lambda source: source.summary_stats.two_yr_mean_citedness, reverse=True)
+        sources_summary = SourcesSummary(sources=sources_sorted)
 
     return InstitutionReport(
         institution=institution,
         works=works,
-        citation_resume=report_citation_resume,
-        open_access_resume=open_access_resume,
-        works_type_resume=works_type_counter,
-        sources_resume=sources_resume
+        citation_summary=report_citation_summary,
+        open_access_summary=open_access_summary,
+        works_type_summary=works_type_counter,
+        sources_summary=sources_summary,
     )

pub_analyzer/internal/templates/author/{author_resume.typ → author_summary.typ}

@@ -1,4 +1,4 @@
-// Author Resume
+// Author Summary
 = Author.
 
 // Cards
@@ -22,8 +22,9 @@
         [#align(center)[#text(size: 12pt)[Last institution:]]],
 
         // Card content
-        {% if report.author.last_known_institution %}
-        [#align(left)[#text(size: 10pt)[- *Name:* {{ report.author.last_known_institution.display_name }}]]],
+        {% if report.author.last_known_institutions%}
+        {% set last_known_institution = report.author.last_known_institutions[0] %}
+        [#align(left)[#text(size: 10pt)[- *Name:* {{ last_known_institution.display_name }}]]],
         [#align(left)[#text(size: 10pt)[- *Country:* MX]]],
         [#align(left)[#text(size: 10pt)[- *Type:* education]]],
         {% endif %}

pub_analyzer/internal/templates/author/report.typ

@@ -39,12 +39,13 @@
   columns: (1fr),
   row-gutter: 11pt,
   [#align(center, text(size: 17pt, weight: "bold")[{{ report.author.display_name }}])],
-  {% if report.author.last_known_institution %}
-  [#align(center, text(size: 15pt, weight: "thin")[{{ report.author.last_known_institution.display_name }}])],
+  {% if report.author.last_known_institutions %}
+  {% set last_known_institution = report.author.last_known_institutions[0] %}
+  [#align(center, text(size: 15pt, weight: "thin")[{{ last_known_institution.display_name }}])],
   {% endif %}
 )
 
-{% include 'author_resume.typ' %}
+{% include 'author_summary.typ' %}
 
 {% include 'works.typ' %}
 

pub_analyzer/internal/templates/author/sources.typ

@@ -2,19 +2,21 @@
 = Sources.
 
 #table(
-  columns: (auto, 3fr, 2fr, auto, auto, auto),
+  columns: (auto, 3fr, 2fr, auto, auto, auto, auto, auto),
   inset: 8pt,
   align: horizon,
   // Headers
-  [], [*Name*], [*Publisher or institution*], [*Type*], [*ISSN-L*], [*Is Open Access*],
+  [], [*Name*], [*Publisher or institution*], [*Type*], [*ISSN-L*], [*Impact factor*], [*h-index*], [*Is OA*],
 
   // Content
-  {% for source in report.sources_resume.sources %}
-  [{{ loop.index }}],
-  [#underline([#link("{{ source.id }}")[#"{{ source.display_name }}"]])],
+  {% for source in report.sources_summary.sources %}
+  [#underline[3.{{ loop.index }}. #label("source_{{ source.id.path.rpartition("/")[2] }}")]],
+  [#underline([#link("{{ source.homepage_url }}")[#"{{ source.display_name }}"]])],
   [{{ source.host_organization_name or "-" }}],
   [{{source.type }}],
   [{{ source.issn_l or "-" }}],
+  [{{ source.summary_stats.two_yr_mean_citedness|round(3) }}],
+  [{{ source.summary_stats.h_index }}],
   [{% if source.is_oa %}#text(rgb("909d63"))[True]{% else %}#text(rgb("bc5653"))[False]{% endif %}],
   {% endfor %}
 )

pub_analyzer/internal/templates/author/works.typ

@@ -9,14 +9,14 @@
   [
     #align(center)[_Citation metrics_]
     #parbreak()
-    - *Count:* {{ report.citation_resume.type_a_count + report.citation_resume.type_b_count }}
-    - *Type A:* {{ report.citation_resume.type_a_count }}
-    - *Type B:* {{ report.citation_resume.type_b_count }}
+    - *Count:* {{ report.citation_summary.type_a_count + report.citation_summary.type_b_count }}
+    - *Type A:* {{ report.citation_summary.type_a_count }}
+    - *Type B:* {{ report.citation_summary.type_b_count }}
   ],
   [
     #align(center)[_Work Type_]
     #parbreak()
-    {% for work_type in report.works_type_resume %}
+    {% for work_type in report.works_type_summary %}
     - *{{ work_type.type_name }}:* {{ work_type.count }}
     {% endfor %}
   ],
@@ -27,13 +27,13 @@
       columns: (1fr, 1fr),
       column-gutter: 15pt,
       [
-        - *gold:* {{report.open_access_resume.gold}}
-        - *green:* {{report.open_access_resume.green}}
-        - *hybrid:* {{report.open_access_resume.hybrid}}
+        - *gold:* {{report.open_access_summary.gold}}
+        - *green:* {{report.open_access_summary.green}}
+        - *hybrid:* {{report.open_access_summary.hybrid}}
       ],
       [
-        - *bronze:* {{report.open_access_resume.bronze}}
-        - *closed:* {{report.open_access_resume.closed}}
+        - *bronze:* {{report.open_access_summary.bronze}}
+        - *closed:* {{report.open_access_summary.closed}}
       ],
     )
   ],
@@ -56,9 +56,9 @@
   [{{ work.work.type }}],
   [{% if work.work.ids.doi %}#underline([#link("{{ work.work.ids.doi }}")[DOI]]){% else %}-{% endif %}],
   [{{ work.work.publication_date }}],
-  [{{ work.citation_resume.type_a_count + work.citation_resume.type_b_count }}],
-  [{{ work.citation_resume.type_a_count }}],
-  [{{ work.citation_resume.type_b_count }}],
+  [{{ work.citation_summary.type_a_count + work.citation_summary.type_b_count }}],
+  [{{ work.citation_summary.type_a_count }}],
+  [{{ work.citation_summary.type_b_count }}],
   [{{ work.work.open_access.oa_status.value }}],
   {% endfor %}
 )

pub_analyzer/internal/templates/author/works_extended.typ

@@ -39,9 +39,9 @@
   [
     #align(center)[_Citation_]
     #parbreak()
-    - *Count:* {{ work.citation_resume.type_a_count + work.citation_resume.type_b_count }}
-    - *Type A:* {{ work.citation_resume.type_a_count }}
-    - *Type B:* {{ work.citation_resume.type_b_count }}
+    - *Count:* {{ work.citation_summary.type_a_count + work.citation_summary.type_b_count }}
+    - *Type A:* {{ work.citation_summary.type_a_count }}
+    - *Type B:* {{ work.citation_summary.type_b_count }}
   ],
 )
 
@@ -83,7 +83,7 @@
   // Content
   {% for location in work.work.locations %}
   {% if location.source %}
-  [{{ loop.index }}],
+  [#underline([#link(label("source_{{ location.source.id.path.rpartition("/")[2] }}"))[{{ loop.index }}]])],
   [#underline([#link("{{ location.landing_page_url }}")[#"{{ location.source.display_name }}"]])],
   [{{ location.source.host_organization_name or "-" }}],
   [{{ location.source.type }}],

pub_analyzer/main.py

@@ -18,15 +18,17 @@ from pub_analyzer.widgets.sidebar import SideBar
 class PubAnalyzerApp(App[DOMNode]):
     """Pub Analyzer App entrypoint."""
 
-    CSS_PATH: ClassVar[CSSPathType] = [
-        "css/author.tcss",
+    TITLE = "Pub Analyzer"
+
+    CSS_PATH: ClassVar[CSSPathType | None] = [
         "css/body.tcss",
         "css/buttons.tcss",
         "css/checkbox.tcss",
+        "css/collapsible.tcss",
         "css/datatable.tcss",
-        "css/institution.tcss",
         "css/main.tcss",
         "css/report.tcss",
+        "css/summary.tcss",
         "css/search.tcss",
         "css/tabs.tcss",
         "css/tree.tcss",
@@ -59,10 +61,7 @@ class PubAnalyzerApp(App[DOMNode]):
         """Take Screenshot."""
         file_path = self.app.save_screenshot()
         self.app.notify(
-            title="Screenshot saved!",
-            message=f"You can see the screenshot at {file_path}",
-            severity="information",
-            timeout=10.0
+            title="Screenshot saved!", message=f"You can see the screenshot at {file_path}", severity="information", timeout=10.0
         )
 
     def action_open_link(self, link: str) -> None:

pub_analyzer/models/author.py

@@ -1,26 +1,26 @@
 """Authors models from OpenAlex API Schema definition."""
 
-from pydantic import BaseModel, ConfigDict, Field, HttpUrl, field_validator
+from typing import TypeAlias
+
+from pydantic import BaseModel, Field, HttpUrl
 
 from pub_analyzer.models.institution import DehydratedInstitution
 
+AuthorOpenAlexID: TypeAlias = HttpUrl
+"""OpenAlex ID for Author Objects with the format `https://openalex.org/A000000000`"""
 
-class AuthorIDs(BaseModel):
-    """IDs from an Author."""
+AuthorOpenAlexKey: TypeAlias = str
+"""OpenAlex author entity Key with the format `A000000000`"""
 
-    openalex: str
-    orcid: str | None = ""
-    scopus: str | None = ""
-    twitter: str | None = ""
-    wikipedia: str | None = ""
 
-    # Allowing a value to be assigned during validation.
-    model_config = ConfigDict(validate_assignment=True)
+class AuthorIDs(BaseModel):
+    """IDs from an Author."""
 
-    @field_validator("scopus", "twitter", "wikipedia")
-    def set_default(cls, value: str) -> str:
-        """Define a default text."""
-        return value or ""
+    openalex: AuthorOpenAlexID
+    orcid: HttpUrl | None = None
+    scopus: HttpUrl | None = None
+    twitter: HttpUrl | None = None
+    wikipedia: HttpUrl | None = None
 
 
 class AuthorYearCount(BaseModel):
@@ -42,7 +42,7 @@ class AuthorSummaryStats(BaseModel):
 class Author(BaseModel):
     """Author Model Object from OpenAlex API definition."""
 
-    id: HttpUrl
+    id: AuthorOpenAlexID
     ids: AuthorIDs
     orcid: str | None = ""
 
@@ -52,7 +52,7 @@ class Author(BaseModel):
     works_count: int
     cited_by_count: int
 
-    last_known_institution: DehydratedInstitution | None
+    last_known_institutions: list[DehydratedInstitution]
     counts_by_year: list[AuthorYearCount]
 
     summary_stats: AuthorSummaryStats
@@ -63,7 +63,7 @@ class Author(BaseModel):
 class DehydratedAuthor(BaseModel):
     """Stripped-down Author Model."""
 
-    id: HttpUrl
+    id: AuthorOpenAlexID
     display_name: str | None = None
     orcid: HttpUrl | None = None
 
@@ -71,18 +71,10 @@ class DehydratedAuthor(BaseModel):
 class AuthorResult(BaseModel):
     """Author result Model resulting from a search in OpenAlex."""
 
-    id: HttpUrl
+    id: AuthorOpenAlexID
     display_name: str
-    hint: str | None = ""
+    hint: str | None = None
     cited_by_count: int
     works_count: int
     entity_type: str
-    external_id: str | None = ""
-
-    # Allowing a value to be assigned during validation.
-    model_config = ConfigDict(validate_assignment=True)
-
-    @field_validator("hint", "external_id")
-    def set_default(cls, value: str) -> str:
-        """Define a default text."""
-        return value or ""
+    external_id: str | None = None

pub_analyzer/models/concept.py

@@ -0,0 +1,19 @@
+"""Concept model from OpenAlex API Schema definition."""
+
+from pydantic import BaseModel, HttpUrl
+
+
+class DehydratedConcept(BaseModel):
+    """Stripped-down Concept Model."""
+
+    id: HttpUrl
+    """The OpenAlex ID for this concept."""
+    display_name: str
+    """The English-language label of the concept."""
+
+    wikidata: HttpUrl
+    """The Wikidata ID for this concept. All OpenAlex concepts are also Wikidata concepts."""
+    level: int
+    """The level in the concept. Lower-level concepts are more general, and higher-level concepts are more specific."""
+    score: float
+    """The strength of the connection between the work and this concept (higher is stronger)."""