Skip to content

Base

papertrail.fetchers.base

Abstract base class for publication fetchers.

BaseFetcher

Bases: ABC

Interface that all data-source fetchers must implement.

Subclass this to add support for additional bibliographic APIs (e.g. Semantic Scholar, Crossref, PubMed).

Source code in src/papertrail/fetchers/base.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
class BaseFetcher(ABC):
    """Interface that all data-source fetchers must implement.

    Subclass this to add support for additional bibliographic APIs
    (e.g. Semantic Scholar, Crossref, PubMed).
    """

    @abstractmethod
    def search_authors(self, name: str) -> list[AuthorInfo]:
        """Search for authors matching the given name.

        Args:
            name: Full or partial author name.

        Returns:
            A list of matching :class:`~papertrail.models.AuthorInfo` objects,
            ordered by relevance (most relevant first).

        Raises:
            FetchError: If the underlying API request fails.
        """

    @abstractmethod
    def fetch_publications(
        self,
        author_id: str,
        *,
        max_results: int | None = None,
    ) -> list[Publication]:
        """Fetch all publications for a specific author.

        Args:
            author_id: The unique author identifier understood by this fetcher.
            max_results: Optional cap on the number of publications returned.
                ``None`` means fetch all available.

        Returns:
            A list of :class:`~papertrail.models.Publication` objects.

        Raises:
            FetchError: If the underlying API request fails.
        """

    def fetch_analyze_metrics(
        self,
        publications: list[Publication],
    ) -> dict[str, Any] | None:
        """Fetch optional source-native analysis metrics for publications.

        Most fetchers will return ``None``. Data sources that provide native
        analysis endpoints (e.g. ADS Metrics API) can override this hook.
        """
        return None

search_authors abstractmethod 

search_authors(name: str) -> list[AuthorInfo]

Search for authors matching the given name.

Parameters:

Name Type Description Default
name str

Full or partial author name.

 required

Returns:

Type Description
list[AuthorInfo]

A list of matching :class:~papertrail.models.AuthorInfo objects,
list[AuthorInfo]

ordered by relevance (most relevant first).

Raises:

Type Description
FetchError

If the underlying API request fails.
Source code in src/papertrail/fetchers/base.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
@abstractmethod
def search_authors(self, name: str) -> list[AuthorInfo]:
    """Search for authors matching the given name.

    Args:
        name: Full or partial author name.

    Returns:
        A list of matching :class:`~papertrail.models.AuthorInfo` objects,
        ordered by relevance (most relevant first).

    Raises:
        FetchError: If the underlying API request fails.
    """

fetch_publications abstractmethod 

fetch_publications(
    author_id: str, *, max_results: int | None = None
) -> list[Publication]

Fetch all publications for a specific author.

Parameters:

Name Type Description Default
author_id str

The unique author identifier understood by this fetcher.

 required
max_results int | None

Optional cap on the number of publications returned. None means fetch all available.

 None

Returns:

Type Description
list[Publication]

A list of :class:~papertrail.models.Publication objects.

Raises:

Type Description
FetchError

If the underlying API request fails.
Source code in src/papertrail/fetchers/base.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
@abstractmethod
def fetch_publications(
    self,
    author_id: str,
    *,
    max_results: int | None = None,
) -> list[Publication]:
    """Fetch all publications for a specific author.

    Args:
        author_id: The unique author identifier understood by this fetcher.
        max_results: Optional cap on the number of publications returned.
            ``None`` means fetch all available.

    Returns:
        A list of :class:`~papertrail.models.Publication` objects.

    Raises:
        FetchError: If the underlying API request fails.
    """

fetch_analyze_metrics 

fetch_analyze_metrics(
    publications: list[Publication],
) -> dict[str, Any] | None

Fetch optional source-native analysis metrics for publications.

Most fetchers will return None. Data sources that provide native analysis endpoints (e.g. ADS Metrics API) can override this hook.

Source code in src/papertrail/fetchers/base.py 
54
55
56
57
58
59
60
61
62
63
def fetch_analyze_metrics(
    self,
    publications: list[Publication],
) -> dict[str, Any] | None:
    """Fetch optional source-native analysis metrics for publications.

    Most fetchers will return ``None``. Data sources that provide native
    analysis endpoints (e.g. ADS Metrics API) can override this hook.
    """
    return None