pybliometrics 4.2__py3-none-any.whl

pybliometrics/__init__.py

@@ -0,0 +1,11 @@
+from importlib.metadata import version
+
+__version__ = version("pybliometrics")
+
+__citation__ = 'Rose, Michael E. and John R. Kitchin: "pybliometrics: '\
+    'Scriptable bibliometrics using a Python interface to Scopus", SoftwareX '\
+    '10 (2019) 100263.'
+
+import pybliometrics.scopus
+import pybliometrics.sciencedirect
+from pybliometrics.utils.startup import init

pybliometrics/exception.py

@@ -0,0 +1,88 @@
+"""Base exceptions and classes for pybliometrics.scopus."""
+
+import warnings
+
+warnings.filterwarnings("default", category=DeprecationWarning)
+
+
+def deprecated(cls):
+    original_init = cls.__init__
+    def __init__(self, *args, **kwargs):
+        msg = f"{cls.__name__} is deprecated and will be removed in the next "\
+              "release. Please use ScopusServerError instead"
+        warnings.warn(msg, DeprecationWarning, stacklevel=2)
+        original_init(self, *args, **kwargs)
+    cls.__init__ = __init__
+    return cls
+
+
+# Base classes
+class ScopusException(Exception):
+    """Base class for exceptions in pybliometrics."""
+
+
+class ScopusError(ScopusException):
+    """Exception for a serious error in pybliometrics."""
+
+
+# Query errors
+class ScopusQueryError(ScopusException):
+    """Exception for problems related to Scopus queries."""
+
+
+# HTML errors
+class ScopusHtmlError(ScopusException):
+    """Wrapper for exceptions raised by requests."""
+
+
+class Scopus400Error(ScopusHtmlError):
+    """Raised if a query yields a 400 error (Bad Request for url)."""
+
+
+class Scopus401Error(ScopusHtmlError):
+    """Raised if a query yields a 401 error (Unauthorized for url)."""
+
+
+class Scopus403Error(ScopusHtmlError):
+    """Raised if a query yields a 403 error (Forbidden for url)."""
+
+
+class Scopus404Error(ScopusHtmlError):
+    """Raised if a query yields a 404 error (Not Found for url)."""
+
+
+class Scopus407Error(ScopusHtmlError):
+    """Raised if a query yields a 407 error (Proxy Authentication Required)."""
+
+
+class Scopus413Error(ScopusHtmlError):
+    """Raised if a query yields a 413 error (Request Entity Too
+    Large for url).
+    """
+
+
+class Scopus414Error(ScopusHtmlError):
+    """Raised if a query yields a 414 error (Request-URI Too Large for url)."""
+
+
+class Scopus429Error(ScopusHtmlError):
+    """Raised if a query yields a 429 error (Quota exceeded)."""
+
+
+class ScopusServerError(ScopusHtmlError):
+    """Wrapper for Server related exceptions (code 5xx)."""
+
+
+@deprecated
+class Scopus500Error(ScopusServerError):
+    """Raised if a query yields a 500 error (Internal Server Error
+    for url).
+    """
+
+@deprecated
+class Scopus502Error(ScopusServerError):
+    """Raised if a query yields a 502 error (Bad gateway for url)."""
+
+@deprecated
+class Scopus504Error(ScopusServerError):
+    """Raised if a query yields a 504 error (Gateway Time-out for url)."""

pybliometrics/sciencedirect/__init__.py

@@ -0,0 +1,9 @@
+from pybliometrics.utils import *
+
+from pybliometrics.sciencedirect.article_entitlement import *
+from pybliometrics.sciencedirect.article_metadata import *
+from pybliometrics.sciencedirect.article_retrieval import *
+from pybliometrics.sciencedirect.object_metadata import *
+from pybliometrics.sciencedirect.object_retrieval import *
+from pybliometrics.sciencedirect.sciencedirect_search import *
+from pybliometrics.sciencedirect.subject_classifications import *

pybliometrics/sciencedirect/article_entitlement.py

@@ -0,0 +1,95 @@
+"""Module for retrieving article entitlement information from ScienceDirect."""
+
+from typing import Optional, Union
+
+from pybliometrics.superclasses import Retrieval
+from pybliometrics.utils import chained_get, check_parameter_value, detect_id_type, VIEWS
+
+
+class ArticleEntitlement(Retrieval):
+    """Class to retrieve the entitlement status for a document from ScienceDirect."""
+    @property
+    def status(self) -> Optional[str]:
+        """Status of whether a document has been found"""
+        return self._json.get("@status")
+
+    @property
+    def identifier(self) -> Optional[str]:
+        """Identifier of a document."""
+        return self._json.get("dc:identifier")
+
+    @property
+    def eid(self) -> Optional[str]:
+        "The EID of a document."
+        return self._json.get("eid")
+
+    @property
+    def entitled(self) -> Optional[str]:
+        """Entitlement status of a document."""
+        return self._json.get("entitled")
+
+    @property
+    def link(self) -> Optional[str]:
+        """ScienceDirect canonical URL."""
+        return chained_get(self._json, ['link', '@href'])
+
+    @property
+    def message(self) -> Optional[str]:
+        """Entitlement status message."""
+        return self._json.get("message")
+
+    @property
+    def pii(self) -> Optional[str]:
+        """The PII of a document."""
+        return self._json.get("pii")
+
+    @property
+    def pii_norm(self) -> Optional[str]:
+        """The PII-norm of a document."""
+        return self._json.get("pii-norm")
+
+    @property
+    def doi(self) -> Optional[str]:
+        """The DOI of a document."""
+        return self._json.get("prism:doi")
+
+    @property
+    def pubmed_id(self) -> Optional[str]:
+        """The Pubmed ID of a document (when used in the request)."""
+        return self._json.get("pubmed_id")
+
+    @property
+    def url(self) -> Optional[str]:
+        """API URL used to check entitlement."""
+        return self._json.get("prism:url")
+
+    @property
+    def scopus_id(self) -> Optional[str]:
+        """The Scopus ID of a document (when used in the request)."""
+        return self._json.get("scopus_id")
+
+    def __init__(self,
+                 identifier: Union[int, str],
+                 view: str = "FULL",
+                 id_type: Optional[str] = None,
+                 refresh: Union[bool, int] = False,
+                 **kwds: str) -> None:
+        # Checks
+        identifier = str(identifier)
+        check_parameter_value(view, VIEWS["ArticleEntitlement"], "view")
+        if not id_type:
+            id_type = detect_id_type(identifier)
+        else:
+            allowed_id_types = ("eid", "pii", "scopus_id", "pubmed_id", "doi", "pui")
+            check_parameter_value(id_type, allowed_id_types, "id_type")
+
+        self._view = view
+        self._refresh = refresh
+        # Retrieve and get content
+        Retrieval.__init__(self, identifier=identifier, id_type=id_type, **kwds)
+        self._json = chained_get(self._json, ["entitlement-response", "document-entitlement"])
+
+    def __str__(self) -> str:
+        s = self.message
+        s += f' with doi: {self.doi}'
+        return s

pybliometrics/sciencedirect/article_metadata.py

@@ -0,0 +1,171 @@
+from collections import namedtuple
+from typing import Optional, Union
+
+from pybliometrics.superclasses import Search
+from pybliometrics.utils import check_field_consistency, chained_get, \
+    check_integrity, check_parameter_value, deduplicate, \
+    make_search_summary, VIEWS
+
+
+class ArticleMetadata(Search):
+    @property
+    def results(self) -> Optional[list[namedtuple]]:
+        """A list of namedtuples in the form `(authorKeywords authors available_online_date
+        first_author abstract_text doi title eid link openArchiveArticle openaccess_status
+        openaccessArticle openaccessUserLicense pii aggregationType copyright coverDate
+        coverDisplayDate edition endingPage isbn publicationName startingPage teaser
+        api_link publicationType vor_available_online_date)`.
+
+        Field definitions correspond to the `Article Metadata Views
+        <https://dev.elsevier.com/sd_article_meta_views.html>`__ and return the
+        values as-is, except for `authors` which are joined on `";"`.
+
+        Raises
+        ------
+        ValueError
+            If the elements provided in `integrity_fields` do not match the
+            actual field names (listed above).
+
+        Notes
+        -----
+        The list of authors and the list of affiliations per author are
+        deduplicated.
+        """
+        fields = 'authorKeywords authors available_online_date first_author abstract_text ' \
+            'doi title eid link openArchiveArticle openaccess_status openaccessArticle '\
+            'openaccessUserLicense pii aggregationType copyright coverDate coverDisplayDate '\
+            'edition endingPage isbn publicationName startingPage teaser api_link publicationType '\
+            'vor_available_online_date'
+        doc = namedtuple('Document', fields)
+        check_field_consistency(self._integrity, fields)
+        # Parse elements one-by-one
+        out = []
+        for item in self._json:
+            # Get authors and create ";" separated string
+            authors_list = [author.get('$') for author in chained_get(item, ['authors', 'author'], [])]
+            authors_list = deduplicate(authors_list)
+            authors = ';'.join(authors_list)
+            first_author = item.get('dc:creator')[0].get('$')
+            link = item.get('link')[0].get('@href')
+            doi = item.get("prism:doi") or item.get("dc:identifier")[4:] if item.get("dc:identifier") else None
+            new = doc(
+                authorKeywords=item.get('authkeywords'),
+                authors=authors,
+                available_online_date=item.get('available-online-date'),
+                first_author=first_author,
+                abstract_text=item.get('dc:description'),
+                doi=doi,
+                title=item.get('dc:title'),
+                eid=item.get('eid'),
+                link=link,
+                openArchiveArticle=item.get('openArchiveArticle'),
+                openaccess_status=item.get('openaccess'),
+                openaccessArticle=item.get('openaccessArticle'),
+                openaccessUserLicense=item.get('openaccessUserLicense'),
+                pii=item.get('pii'),
+                aggregationType=item.get('prism:aggregationType'),
+                copyright=item.get('prism:copyright'),
+                coverDate=item.get('prism:coverDate'),
+                coverDisplayDate=item.get('prism:coverDisplayDate'),
+                edition=item.get('prism:edition'),
+                endingPage=item.get('prism:endingPage'),
+                isbn=item.get('prism:isbn'),
+                publicationName=item.get('prism:publicationName'),
+                startingPage=item.get('prism:startingPage'),
+                teaser=item.get('prism:teaser'),
+                api_link=item.get('prism:url'),
+                publicationType=item.get('pubType'),
+                vor_available_online_date=item.get('vor-available-online-date'),
+            )
+            out.append(new)
+        check_integrity(out, self._integrity, self._action)
+        return out or None
+
+    def __init__(self,
+                 query: str,
+                 refresh: Union[bool, int] = False,
+                 view: str = None,
+                 verbose: bool = False,
+                 download: bool = True,
+                 integrity_fields: Union[list[str], tuple[str, ...]] = None,
+                 integrity_action: str = "raise",
+                 subscriber: bool = True,
+                 **kwds: str
+                 ) -> None:
+        """Interaction with the ScienceDirect Article Metadata API.
+
+        :param query: A string of the query as used in the `Advanced Search <https://dev.elsevier.com/tecdoc_sdsearch_migration.html>`__.
+        :param refresh: Whether to refresh the cached file if it exists or not.
+                        If int is passed, cached file will be refreshed if the
+                        number of days since last modification exceeds that value.
+        :param view: Which view to use for the query, see `the documentation <https://dev.elsevier.com/sd_article_meta_views.html>`__.
+                     Allowed values: `STANDARD`, `COMPLETE`.  If `None`, defaults to
+                     `COMPLETE` if `subscriber=True` and to `STANDARD` if
+                     `subscriber=False`.
+        :param verbose: Whether to print a download progress bar.
+        :param download: Whether to download results (if they have not been
+                         cached).
+        :param integrity_fields: A list or tuple with the names of fields whose completeness should
+                                 be checked.  `ArticleMetadata` will perform the
+                                 action specified in `integrity_action` if
+                                 elements in these fields are missing.  This
+                                 helps to avoid idiosynchratically missing
+                                 elements that should always be present
+                                 (e.g., EID or source ID).
+        :param integrity_action: What to do in case integrity of provided fields
+                                 cannot be verified.  Possible actions:
+                                 - `"raise"`: Raise an `AttributeError`
+                                 - `"warn"`: Raise a `UserWarning`
+        :param subscriber: Whether you access ScienceDirect with a subscription or not.
+                           For subscribers, ScienceDirect's cursor navigation will be
+                           used.  Sets the number of entries in each query
+                           iteration to the maximum number allowed by the
+                           corresponding view.
+        :param unescape: Convert named and numeric characters in the `results` to
+                        their corresponding Unicode characters.
+        :param kwds: Keywords passed on as query parameters.  Must contain
+                     fields and values mentioned in the `API specification <https://dev.elsevier.com/documentation/ArticleMetadataAPI.wadl>`__.
+
+        Raises
+        ------
+        ScopusQueryError
+            For non-subscribers, if the number of search results exceeds 5000.
+
+        ValueError
+            If any of the parameters `integrity_action`, `refresh` or `view`
+            is not one of the allowed values.
+
+        Notes
+        -----
+        The directory for cached results is `{path}/{view}/{fname}`,
+        where `path` is specified in your configuration file and `fname` is
+        the md5-hashed version of `query`.
+        """
+        # Check view or set to default
+        if view:
+            check_parameter_value(view, VIEWS['ArticleMetadata'], "view")
+        else:
+            view = "COMPLETE" if subscriber else "STANDARD"
+
+        allowed = ("warn", "raise")
+        check_parameter_value(integrity_action, allowed, "integrity_action")
+
+        size = 25  # for pagination
+        if view == "STANDARD" and subscriber:
+            size = 200
+
+        # Query
+        self._action = integrity_action
+        self._integrity = integrity_fields or []
+        self._refresh = refresh
+        self._query = query
+        self._view = view
+        Search.__init__(self, query=query, size=size, download=download, verbose=verbose, **kwds)
+
+    def __str__(self):
+        """Print a summary string."""
+        return make_search_summary(self, "document", self.get_eids())
+
+    def get_eids(self):
+        """EIDs of retrieved documents."""
+        return [d['eid'] for d in self._json]

pybliometrics/sciencedirect/article_retrieval.py

@@ -0,0 +1,244 @@
+from collections import namedtuple
+from typing import Optional, Union
+
+from pybliometrics.superclasses import Retrieval
+from pybliometrics.utils import (
+    chained_get,
+    check_parameter_value,
+    detect_id_type,
+    list_authors,
+    make_bool_if_possible,
+    make_int_if_possible,
+    parse_pages,
+    VIEWS,
+)
+
+
+class ArticleRetrieval(Retrieval):
+    @property
+    def abstract(self) -> Optional[str]:
+        """The abstract of a document."""
+        abstract = chained_get(self._json, ['coredata', 'dc:description'])
+        if abstract:
+            abstract = abstract.strip()
+        return abstract
+
+    @property
+    def aggregationType(self) -> Optional[str]:
+        """The aggregation type of a document."""
+        return chained_get(self._json, ['coredata', 'prism:aggregationType'])
+
+    @property
+    def authors(self) -> Optional[list]:
+        """The authors of a document."""
+        out = []
+        auth = namedtuple('Author', 'surname given_name')
+        for author in chained_get(self._json, ['coredata', 'dc:creator']):
+            surname, given_name = author['$'].split(', ')
+            new = auth(surname=surname, given_name=given_name)
+            out.append(new)
+        return out or None
+
+    @property
+    def copyright(self) -> Optional[str]:
+        """The copyright of a document."""
+        return chained_get(self._json, ['coredata', 'prism:copyright'])
+
+    @property
+    def coverDate(self) -> Optional[str]:
+        """The date of the cover the document is in."""
+        return chained_get(self._json, ['coredata', 'prism:coverDate'])
+
+    @property
+    def coverDisplayDate(self) -> Optional[str]:
+        """The cover display date of a document."""
+        return chained_get(self._json, ['coredata', 'prism:coverDisplayDate'])
+
+    @property
+    def document_entitlement_status(self) -> Optional[str]:
+        """Returns the document entitlement status, i.e. tells if the requestor 
+        is entitled to the requested resource.
+        Note: Only works with `ENTITLED` view.
+        """
+        return chained_get(self._json, ['document-entitlement', 'status'])
+
+    @property
+    def doi(self) -> str:
+        """The doi of a document."""
+        return chained_get(self._json, ['coredata', 'prism:doi'])
+
+    @property
+    def eid(self) -> Optional[str]:
+        """The eid of a document."""
+        return chained_get(self._json, ['coredata', 'eid'])
+
+    @property
+    def endingPage(self) -> Optional[str]:
+        """The ending page of a document."""
+        page = chained_get(self._json, ['coredata', 'prism:endingPage'])
+        return page
+
+    @property
+    def issn(self) -> int:
+        """The issn of a document."""
+        return make_int_if_possible(chained_get(self._json, ['coredata', 'prism:issn']))
+
+    @property
+    def openaccess(self) -> bool:
+        """The document is open access."""
+        open_access = chained_get(self._json, ['coredata', 'openaccessArticle'])
+        return make_bool_if_possible(open_access)
+
+    @property
+    def openaccessSponsorName(self) -> Optional[str]:
+        """The open access sponsor name of a document."""
+        return chained_get(self._json, ['coredata', 'openaccessSponsorName'])
+
+    @property
+    def openaccessSponsorType(self) -> Optional[str]:
+        """The open access sponsor type of a document."""
+        return chained_get(self._json, ['coredata', 'openaccessSponsorType'])
+
+    @property
+    def openaccessType(self) -> Optional[str]:
+        """The open access type of a document."""
+        return chained_get(self._json, ['coredata', 'openaccessType'])
+
+    @property
+    def openaccessUserLicense(self) -> Optional[str]:
+        """The open access user license of a document."""
+        return chained_get(self._json, ['coredata', 'openaccessUserLicense'])
+
+    @property
+    def openArchiveArticle(self) -> bool:
+        """The document is an open archive article."""
+        open_archive = chained_get(self._json, ['coredata', 'openArchiveArticle'])
+        return make_bool_if_possible(open_archive)
+
+    @property
+    def originalText(self) -> Optional[str]:
+        """Complete document text."""
+        return self._json.get('originalText')
+
+    @property
+    def pageRange(self) -> Optional[str]:
+        """The prism:pageRange of a document."""
+        return chained_get(self._json, ['coredata', 'prism:pageRange'])
+
+    @property
+    def publicationName(self) -> str:
+        """The publication name of a document (e.g. Journal of Economy and Technology)."""
+        return chained_get(self._json, ['coredata', 'prism:publicationName'])
+
+    @property
+    def publisher(self) -> Optional[str]:
+        """The publisher of a document."""
+        return chained_get(self._json, ['coredata', 'prism:publisher'])
+
+    @property
+    def pubType(self) -> Optional[str]:
+        """The publication type of a document."""
+        return chained_get(self._json, ['coredata', 'pubType'])
+
+    @property
+    def pii(self) -> str:
+        """The pii of a document."""
+        return chained_get(self._json, ['coredata', 'pii'])
+
+    @property
+    def sciencedirect_link(self) -> str:
+        """The ScienceDirect link of a document."""
+        links = chained_get(self._json, ['coredata', 'link'])
+        for link in links:
+            if link['@rel'] == 'scidir':
+                return link['@href']
+
+    @property
+    def self_link(self) -> str:
+        """The API link of a document."""
+        links = chained_get(self._json, ['coredata', 'link'])
+        for link in links:
+            if link['@rel'] == 'self':
+                return link['@href']
+
+    @property
+    def startingPage(self) -> Optional[str]:
+        """The starting page of a document."""
+        return chained_get(self._json, ['coredata', 'prism:startingPage'])
+
+    @property
+    def subjects(self) -> Optional[str]:
+        """The subjects of a document."""
+        subjects = chained_get(self._json, ['coredata', 'dcterms:subject'])
+        return [subject['$'] for subject in subjects]
+
+    @property
+    def title(self) -> str:
+        """The title of a document."""
+        return chained_get(self._json, ['coredata', 'dc:title'])
+
+    @property
+    def url(self) -> str:
+        """The url of a document."""
+        return chained_get(self._json, ['coredata', 'prism:url'])
+
+    @property
+    def volume(self) -> Optional[str]:
+        """The prism:volume of a document."""
+        vol = chained_get(self._json, ['coredata', 'prism:volume'])
+        return make_int_if_possible(vol)
+
+    def __init__(self,
+                 identifier: Union[int, str],
+                 refresh: Union[bool, int] = False,
+                 view: str = 'META',
+                 id_type: Optional[str] = None,
+                 **kwds: str
+                 ):
+        """Interaction with the Article Retrieval API.
+        
+        :param identifier: The indentifier of an article.
+        :param refresh: Whether to refresh the cached file if it exists or not.
+                        If int is passed, cached file will be refreshed if the
+                        number of days since last modification exceeds that value.
+        :param view: The view of the file that should be downloaded. Allowed values:
+                     'META', 'META_ABS', 'META_ABS_REF', 'FULL', 'ENTITLED'. Default: 'META'.
+        :param id_type: The type of used ID. Allowed values: `None`, 'eid', 'pii',
+                        'scopus_id', 'pubmed_id' and 'doi'.  If the value is `None`,
+                        pybliometrics tries to infer the ID type itself.
+        """
+        identifier = str(identifier)
+        check_parameter_value(view, VIEWS['ArticleRetrieval'], "view")
+        if id_type is None:
+            id_type = detect_id_type(identifier)
+        else:
+            allowed_id_types = ('eid', 'pii', 'scopus_id', 'pubmed_id', 'doi')
+            check_parameter_value(id_type, allowed_id_types, "id_type")
+
+        self._view = view
+        self._refresh = refresh
+
+        Retrieval.__init__(self, identifier=identifier, id_type=id_type, **kwds)
+        if self._view != "ENTITLED":
+            self._json = self._json['full-text-retrieval-response']
+
+    def __str__(self):
+        s = ''
+        if self._view in ('FULL', 'META_ABS', 'META'):
+            if self.authors:
+                if len(self.authors) > 1:
+                    authors = list_authors(self.authors)
+                else:
+                    a = self.authors[0]
+                    authors = str(a.given_name) + ' ' + str(a.surname)
+            else:
+                authors = "(No author found)"
+            # All other information
+            s += f'{authors}: "{self.title}", {self.publicationName}'
+            s += f', {self.volume}' if self.volume else ''
+            s += ', '
+            s += parse_pages(self)
+            s += f'({self.coverDate[:4]}).'
+            if self.doi:
+                s += f' https://doi.org/{self.doi}.'
+        return s