#411 Rename SerialTitle classes

docs/configuration.rst

@@ -18,8 +18,8 @@ The structure of the file is the following:
     AuthorSearch = PPP/.cache/.pybliometrics/Scopus/author_search
     CitationOverview = PPP/.cache/.pybliometrics/Scopus/citation_overview
     ScopusSearch = PPP/.cache/.pybliometrics/Scopus/scopus_search
-    SerialSearch = PPP/.cache/.pybliometrics/Scopus/serial_search
-    SerialTitle = PPP/.cache/.pybliometrics/Scopus/serial_title
+    SerialTitleSearch = PPP/.cache/.pybliometrics/Scopus/serial_search
+    SerialTitleISSN = PPP/.cache/.pybliometrics/Scopus/serial_title
     PlumXMetrics = PPP/.cache/.pybliometrics/Scopus/plumx
     SubjectClassifications = PPP/.cache/.pybliometrics/Scopus/subject_classification
 

docs/index.rst

@@ -26,8 +26,8 @@ Classes for the Scopus API
    CitationOverview
    PlumXMetrics
    ScopusSearch
-   SerialSearch
-   SerialTitle
+   SerialTitleSearch
+   SerialTitleISSN
    SubjectClassifications
 
 =================================
@@ -45,7 +45,7 @@ Classes for the ScienceDirect API
    ObjectMetadata
    ObjectRetrieval
    ScienceDirectSearch
-   SerialTitle
+   SerialTitleISSN
    SubjectClassifications
 
 ==========================

docs/reference.rst

@@ -32,8 +32,8 @@ Scopus
 
     reference/scopus/CitationOverview.rst
     reference/scopus/PlumXMetrics.rst
-    reference/scopus/SerialSearch.rst
-    reference/scopus/SerialTitle.rst
+    reference/scopus/SerialTitleSearch.rst
+    reference/scopus/SerialTitleISSN.rst
     reference/scopus/SubjectClassifications.rst
 
 One other Metadata API, the Citations Count Metadata API, is not implemented yet.
@@ -60,7 +60,7 @@ ScienceDirect
     reference/sciencedirect/NonserialTitle.rst
     reference/sciencedirect/ObjectMetadata.rst
     reference/sciencedirect/ObjectRetrieval.rst
-    reference/sciencedirect/SerialTitle.rst
+    reference/sciencedirect/SerialTitleISSN.rst
 
 One other Retrieval API, the Article Hosting Permission API, is not implemented yet.
 

docs/reference/sciencedirect/SerialTitle.rst → docs/reference/sciencedirect/SerialTitleISSN.rst

@@ -1,8 +1,7 @@
-pybliometrics.sciencedirect.SerialTitle
-=======================================
+pybliometrics.sciencedirect.SerialTitleISSN
+===========================================
 
-`SerialTitle()` implements the `Serial Title API <https://dev.elsevier.com/documentation/SerialTitleAPI.wadl>`_.  It offers basic information on registered serials (also known as sources), including publisher details, identifiers, and various metrics.
-Note that this class accesses the same API endpoint as the :class:`pybliometrics.scopus.SerialTitle` class.
+`SerialTitleISSN()` implements the `issn` endpoint of the `Serial Title API <https://dev.elsevier.com/documentation/SerialTitleAPI.wadl>`_.  It offers basic information on registered serials (also known as sources), including publisher details, identifiers, and various metrics.
 
 .. currentmodule:: pybliometrics.sciencedirect
 .. contents:: Table of Contents
@@ -11,7 +10,7 @@ Note that this class accesses the same API endpoint as the :class:`pybliometrics
 Documentation
 -------------
 
-.. autoclass:: SerialTitle
+.. autoclass:: SerialTitleISSN
     :members:
     :inherited-members:
     :no-index:
@@ -24,9 +23,9 @@ You initialize the class with an ISSN or an E-ISSN (works with and without hyphe
 .. code-block:: python
 
     >>> import pybliometrics
-    >>> from pybliometrics.sciencedirect import SerialTitle, init
+    >>> from pybliometrics.sciencedirect import SerialTitleISSN, init
     >>> init()
-    >>> source = SerialTitle("03781119")
+    >>> source = SerialTitleISSN("03781119")
 
 You can obtain basic information just by printing the object:
 
@@ -74,7 +73,7 @@ The `citescoreyearinfolist` property provides detailed information for all avail
 .. code-block:: python
 
     >>> import pandas as pd
-    >>> source_full = SerialTitle("00368075", view="CITESCORE")
+    >>> source_full = SerialTitleISSN("00368075", view="CITESCORE")
     >>> info = pd.DataFrame(source_full.citescoreyearinfolist)
     >>> print(info)
 
@@ -351,11 +350,11 @@ The `yearly_data` time series includes the number of documents published in a gi
     </div>
 
 
-By default, `SerialTitle()` retrieves only the most recent metrics, although yearly data is available from 1996 onwards.  If you provide a year or a range of years via the optional parameter `years`, `SerialTitle()` will retrieve information for these years (except for the CiteScore):
+By default, `SerialTitleISSN()` retrieves only the most recent metrics, although yearly data is available from 1996 onwards.  If you provide a year or a range of years via the optional parameter `years`, `SerialTitleISSN()` will retrieve information for these years (except for the CiteScore):
 
 .. code-block:: python
 
-    >>> source_y = SerialTitle("2352-7110", years="2017-2019")
+    >>> source_y = SerialTitleISSN("2352-7110", years="2017-2019")
     >>> source_y.citescoreyearinfolist
     [Citescoreinfolist(year=2023, citescore=5.5),
      Citescoreinfolist(year=2024, citescore=4.2)]

docs/reference/scopus/SerialTitle.rst → docs/reference/scopus/SerialTitleISSN.rst

@@ -1,7 +1,7 @@
-pybliometrics.scopus.SerialTitle
-================================
+pybliometrics.scopus.SerialTitleISSN
+====================================
 
-`SerialTitle()` implements the `Serial Title API <https://dev.elsevier.com/documentation/SerialTitleAPI.wadl>`_.  It offers basic information on registered serials (also known as sources), including publisher details, identifiers, and various metrics.
+`SerialTitleISSN()` implements the `issn` endpoint of the `Serial Title API <https://dev.elsevier.com/documentation/SerialTitleAPI.wadl>`_.  It offers basic information on registered serials (also known as sources), including publisher details, identifiers, and various metrics.
 
 .. currentmodule:: pybliometrics.scopus
 .. contents:: Table of Contents
@@ -10,7 +10,7 @@ pybliometrics.scopus.SerialTitle
 Documentation
 -------------
 
-.. autoclass:: SerialTitle
+.. autoclass:: SerialTitleISSN
     :members:
     :inherited-members:
 
@@ -22,9 +22,9 @@ You initialize the class with an ISSN or an E-ISSN (works with and without hyphe
 .. code-block:: python
 
     >>> import pybliometrics
-    >>> from pybliometrics.scopus import SerialTitle
+    >>> from pybliometrics.scopus import SerialTitleISSN
     >>> pybliometrics.scopus.init()
-    >>> source = SerialTitle("00368075")
+    >>> source = SerialTitleISSN("00368075")
 
 You can obtain basic information just by printing the object:
 
@@ -72,7 +72,7 @@ The `citescoreyearinfolist` property provides detailed information for all avail
 
 .. code-block:: python
 
-    >>> source_full = SerialTitle("00368075", view="CITESCORE")
+    >>> source_full = SerialTitleISSN("00368075", view="CITESCORE")
     >>> info = pd.DataFrame(source_full.citescoreyearinfolist)
     >>> print(info)
         year  citescore       status  documentcount  citationcount  percentcited                             rank
@@ -110,11 +110,11 @@ The `yearly_data` time series includes the number of documents published in a gi
 	4  2000              2401        7.00           457            19.033736        294076
 
 
-By default, `SerialTitle()` retrieves only the most recent metrics, although yearly data is availble from 1996 onwards.  If you provide a year or a range of years via the optional parameter `years`, `SerialTitle()` will retrieve information for these years (except for the CiteScore):
+By default, `SerialTitleISSN()` retrieves only the most recent metrics, although yearly data is availble from 1996 onwards.  If you provide a year or a range of years via the optional parameter `years`, `SerialTitleISSN()` will retrieve information for these years (except for the CiteScore):
 
 .. code-block:: python
 
-    >>> source_y = SerialTitle("00368075", years="2017-2019")
+    >>> source_y = SerialTitleISSN("00368075", years="2017-2019")
     >>> source_y.citescoreyearinfolist
     [Citescoreinfolist(year=2022, citescore=59.0),
      Citescoreinfolist(year=2023, citescore=58.8)]

docs/reference/scopus/SerialSearch.rst → docs/reference/scopus/SerialTitleSearch.rst

@@ -1,7 +1,7 @@
-pybliometrics.scopus.SerialSearch
-=================================
+pybliometrics.scopus.SerialTitleSearch
+======================================
 
-`SerialSearch()` implements the search of the `Serial Title API <https://dev.elsevier.com/documentation/SerialTitleAPI.wadl>`_.  This class performs searches for serial sources (journals, trade journals, conference proceedings, book series) based on title, ISSN, publisher, subject, or source type.
+`SerialTitleSearch()` implements the search of the `Serial Title API <https://dev.elsevier.com/documentation/SerialTitleAPI.wadl>`_.  This class performs searches for serial sources (journals, trade journals, conference proceedings, book series) based on title, ISSN, publisher, subject, or source type.
 
 .. currentmodule:: pybliometrics.scopus
 .. contents:: Table of Contents
@@ -10,7 +10,7 @@ pybliometrics.scopus.SerialSearch
 Documentation
 -------------
 
-.. autoclass:: SerialSearch
+.. autoclass:: SerialTitleSearch
     :members:
     :inherited-members:
 
@@ -22,9 +22,9 @@ The class is initialized with a search query dictionary.  Its keys are limited t
 .. code-block:: python
 
     >>> import pybliometrics
-    >>> from pybliometrics.scopus import SerialSearch
+    >>> from pybliometrics.scopus import SerialTitleSearch
     >>> pybliometrics.scopus.init()
-    >>> s = SerialSearch(query={"title": "SoftwareX"})
+    >>> s = SerialTitleSearch(query={"title": "SoftwareX"})
 
 
 You can obtain basic information just by printing the object:

pybliometrics/sciencedirect/__init__.py

@@ -8,4 +8,4 @@
 from pybliometrics.sciencedirect.object_retrieval import *
 from pybliometrics.sciencedirect.sciencedirect_search import *
 from pybliometrics.sciencedirect.subject_classifications import *
-from pybliometrics.scopus.serial_title import *
+from pybliometrics.scopus.serial_title_issn import *

pybliometrics/sciencedirect/tests/test_SerialTitle.py → pybliometrics/sciencedirect/tests/test_SerialTitleISSN.py

@@ -1,15 +1,23 @@
-"""Test pybliometrics.sciencedirect.SerialTitle()"""
+"""Test pybliometrics.sciencedirect.SerialTitleISSN()"""
 
 from collections import namedtuple
 
-from pybliometrics.sciencedirect import SerialTitle, init
+from pybliometrics.sciencedirect import SerialTitleISSN, init
 
 init()
 
-gene = SerialTitle('03781119', view='ENHANCED', refresh=30)
+gene = SerialTitleISSN('03781119', view='ENHANCED', refresh=30)
 
 def test_module():
-    assert gene.__module__  == 'pybliometrics.scopus.serial_title'
+    assert gene.__module__  == 'pybliometrics.scopus.serial_title_issn'
+
+
+def test_deprecated_class():
+    from pytest import deprecated_call
+    from pybliometrics.sciencedirect import SerialTitle
+
+    with deprecated_call():
+        _ = SerialTitle('03781119', refresh=30)
 
 
 def test_aggregation_type():

pybliometrics/scopus/__init__.py

@@ -8,6 +8,6 @@
 from pybliometrics.scopus.author_search import *
 from pybliometrics.scopus.plumx_metrics import *
 from pybliometrics.scopus.scopus_search import *
-from pybliometrics.scopus.serial_search import *
-from pybliometrics.scopus.serial_title import *
+from pybliometrics.scopus.serial_title_search import *
+from pybliometrics.scopus.serial_title_issn import *
 from pybliometrics.scopus.subject_classifications import *

pybliometrics/scopus/serial_title.py → pybliometrics/scopus/serial_title_issn.py

@@ -1,12 +1,13 @@
 from collections import namedtuple
 from typing import Optional, Union
+import warnings
 
 from pybliometrics.superclasses import Retrieval
 from pybliometrics.utils import chained_get, check_parameter_value, \
     get_link, make_float_if_possible, make_int_if_possible, VIEWS
 
 
-class SerialTitle(Retrieval):
+class SerialTitleISSN(Retrieval):
     @property
     def aggregation_type(self) -> str:
         """The type of the source."""
@@ -197,7 +198,7 @@ def __init__(self,
                  years: str = None,
                  **kwds: str
                  ) -> None:
-        """Interaction with the Serial Title API.
+        """Interaction with the `ISSN` endpoint of the `Serial Title API`.
         Class retrieves data from both Scopus and ScienceDirect.
 
         :param issn: The ISSN or the E-ISSN of the source.
@@ -228,7 +229,7 @@ def __init__(self,
         where `path` is specified in your configuration file.
         """
         # Checks
-        check_parameter_value(view, VIEWS['SerialTitle'], "view")
+        check_parameter_value(view, VIEWS['SerialTitleISSN'], "view")
         self._view = view
 
         # Force refresh when years is specified
@@ -312,3 +313,15 @@ def _get_all_cite_score_years(
         new_data.append(Citescoreinfolist_year)
 
     return new_data or None
+
+def SerialTitle(*args, **kwds):
+    """Deprecated: Use SerialTitleISSN instead.
+    This class is deprecated and will be removed.
+    """
+    warnings.warn(
+        "SerialTitle is deprecated and will be removed."
+        "Use SerialTitleISSN instead.",
+        DeprecationWarning,
+        stacklevel=2
+    )
+    return SerialTitleISSN(*args, **kwds)

pybliometrics/scopus/serial_search.py → pybliometrics/scopus/serial_title_search.py

@@ -1,11 +1,12 @@
 from collections import OrderedDict
 from typing import Optional, Union
+import warnings
 
 from pybliometrics.superclasses import Search
 from pybliometrics.utils import check_parameter_value, make_search_summary, VIEWS
 
 
-class SerialSearch(Search):
+class SerialTitleSearch(Search):
     @property
     def results(self) -> Optional[list[OrderedDict[str, str]]]:
         """A list of OrderedDicts representing results of serial search. The
@@ -53,7 +54,7 @@ def __init__(self,
                  view: str = 'ENHANCED',
                  **kwds: str
                  ) -> None:
-        """Interaction with the Serial Title API.
+        """Interaction with the base endpoint of the `Serial Title API`.
 
         :param query:  Query parameters and corresponding fields. Allowed keys
                       'title', 'issn', 'pub', 'subj', 'subjCode', 'content',
@@ -92,7 +93,7 @@ def __init__(self,
         invalid = [k for k in query.keys() if k not in allowed_query_keys]
         if invalid:
             raise ValueError(f'Query key(s) "{", ".join(invalid)}" invalid')
-        check_parameter_value(view, VIEWS['SerialSearch'], "view")
+        check_parameter_value(view, VIEWS['SerialTitleSearch'], "view")
 
         # Query
         self._query = str(query)
@@ -178,3 +179,16 @@ def _retrieve_source_rankings(source_data):
         for t in stats:
             out.append([f"{key}_['@year']", t['$']])
     return out or None
+
+
+def SerialSearch(*args, **kwds):
+    """Deprecated: Use SerialTitleSearch instead.
+    This class is deprecated and will be removed.
+    """
+    warnings.warn(
+        "SerialSearch is deprecated and will be removed."
+        "Use SerialTitleSearch instead.",
+        DeprecationWarning,
+        stacklevel=2
+    )
+    return SerialTitleSearch(*args, **kwds)

pybliometrics/scopus/tests/test_SerialTitle.py → pybliometrics/scopus/tests/test_SerialTitleISSN.py

@@ -1,22 +1,22 @@
-"""Tests for `scopus.SerialTitle` module."""
+"""Tests for `scopus.SerialTitleISSN` module."""
 
 import datetime
 
 from collections import namedtuple
 
-from pybliometrics.scopus import SerialTitle, init
+from pybliometrics.scopus import SerialTitleISSN, init
 
 init()
 
 
 # SoftwareX
-softwarex = SerialTitle("2352-7110", refresh=30)
+softwarex = SerialTitleISSN("2352-7110", refresh=30)
 # OECD Economic Studies
-oecd = SerialTitle("0255-0822", refresh=30)
+oecd = SerialTitleISSN("0255-0822", refresh=30)
 # Neural Networks
-neural_networks = SerialTitle('1879-2782', view='CITESCORE', refresh=30)
+neural_networks = SerialTitleISSN('1879-2782', view='CITESCORE', refresh=30)
 # Empty rank for year 2018 in JCO clinical cancer informatics
-jco_cci = SerialTitle('2473-4276', view='CITESCORE', refresh=30)
+jco_cci = SerialTitleISSN('2473-4276', view='CITESCORE', refresh=30)
 
 
 def test_aggregation_type():
@@ -47,6 +47,14 @@ def test_citescoreyearinfolist():
     assert jco_cci.citescoreyearinfolist[-1].rank == []
 
 
+def test_deprecated_class():
+    from pytest import deprecated_call
+    from pybliometrics.scopus import SerialTitle
+
+    with deprecated_call():
+        _ = SerialTitle("2352-7110", refresh=30)
+
+
 def test_eissn():
     assert softwarex.eissn == "2352-7110"
     assert oecd.eissn == "1609-7491"