pyjstage2 0.1.2__tar.gz

pyjstage2-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 matsurih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyjstage2-0.1.2/MANIFEST.in

@@ -0,0 +1,3 @@
+include requirements.txt
+include README.md
+include LICENSE

pyjstage2-0.1.2/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: pyjstage2
+Version: 0.1.2
+Summary: J-STAGE API wrapper for Python - Python 3.12 Compatible
+Home-page: https://github.com/lanshi17/pyjstage
+Author: lanshi17
+Author-email: lanshi17@users.noreply.github.com
+License: MIT
+Project-URL: Source, https://github.com/lanshi17/pyjstage
+Project-URL: Original, https://github.com/matsurih/pyjstage
+Keywords: jstage api wrapper japan science technology academic papers
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: certifi>=2023.0.0
+Requires-Dist: chardet>=5.0.0
+Requires-Dist: idna>=3.0
+Requires-Dist: lxml>=5.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: urllib3>=2.0.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# pyjstage2
+
+![Python 3.12](https://img.shields.io/badge/python-3.12-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+![PyPI version](https://img.shields.io/pypi/v/pyjstage2)
+
+## Overview
+
+[J-STAGE WebAPI](https://www.jstage.jst.go.jp/static/pages/OtherJstageServices/TAB2/-char/ja) Wrapper for Python 3.
+
+- J-STAGE is an electronic journal platform for science and technology information in Japan, developed and managed by the Japan Science and Technology Agency (JST).
+- This package is a **Python 3.12 compatible fork** of [pyjstage](https://pypi.org/project/pyjstage/).
+
+## Acknowledgments
+
+This project is modified based on [matsurih/pyjstage](https://github.com/matsurih/pyjstage) (v0.0.2).
+
+Special thanks to the original author [@matsurih](https://github.com/matsurih) for creating this useful J-STAGE API wrapper.
+
+## What's Changed
+
+| Package | Original | Forked |
+|---------|----------|--------|
+| lxml | 4.4.2 | >=5.0.0 |
+| requests | 2.22.0 | >=2.31.0 |
+| urllib3 | 1.25.7 | >=2.0.0 |
+| certifi | 2019.11.28 | >=2023.0.0 |
+
+- Fixed absolute imports to relative imports
+- Fixed private method name mangling (`__finish_setup` → `_finish_setup`)
+- Added `__init__.py` export for cleaner imports
+
+## Prerequisites
+
+- Python >= 3.12
+
+## Installation
+
+```shell
+$ pip install pyjstage2
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+from pyjstage.pyjstage import Pyjstage
+
+jstage = Pyjstage()
+
+# Search by ISSN
+ret_search = jstage.search(issn='2186-6619', count=3)
+
+# List articles in a journal
+ret_list = jstage.list(issn='2186-6619')
+```
+
+### Accessing Results
+
+```python
+for entry in ret_search.entries:
+    print(f"Title: {entry.title}")
+    print(f"Author: {entry.author.get('ja', '')}")
+    print(f"Journal: {entry.material_title.get('ja', '')}")
+    print(f"Year: {entry.pubyear}")
+    print(f"DOI: {entry.doi}")
+    print(f"Link: {entry.link}")
+```
+
+### Search Parameters
+
+```python
+jstage.search(
+    pubyearfrom=2020,      # Search from year
+    pubyearto=2024,        # Search to year
+    material='journal',    # Journal name contains
+    article='title',       # Article title contains
+    author='name',         # Author name contains
+    keyword='AI',          # Keyword contains
+    issn='2186-6619',      # ISSN
+    count=10               # Number of results (max 1000)
+)
+```
+
+## Important Notes
+
+### What J-STAGE API Provides
+
+- ✅ **Literature search** - Search by ISSN, keyword, author, year, etc.
+- ✅ **Metadata** - Title, author, journal, year, DOI, page numbers
+- ✅ **Article links** - Links to J-STAGE article pages
+
+### What J-STAGE API Does NOT Provide
+
+- ❌ **Full-text PDF download** - The API does not provide direct PDF downloads
+- ❌ **Full-text content** - The API returns metadata, not full article text
+
+To access full-text content, use the `link` or `doi` fields to visit the publisher's website.
+
+## Changelog
+
+### v0.1.2 (2025-06-16)
+
+- **Fix**: Null-safe XML parsing in `SearchResult` and `ListResult` — handles missing/empty XML elements without raising `AttributeError`
+- **Fix**: `WARN_002` (too many results) is now treated as a warning instead of raising an error, since the API still returns valid data
+
+### v0.1.1 (2025-05-18)
+
+- First PyPI release as `pyjstage2`
+- Python 3.12 compatibility
+- Updated dependencies (lxml >=5.0, requests >=2.31, urllib3 >=2.0)
+
+## Source Code
+
+https://github.com/lanshi17/pyjstage
+
+## License
+
+MIT License - see [LICENSE](https://github.com/lanshi17/pyjstage/blob/master/LICENSE) file.

pyjstage2-0.1.2/README.md

@@ -0,0 +1,120 @@
+# pyjstage2
+
+![Python 3.12](https://img.shields.io/badge/python-3.12-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+![PyPI version](https://img.shields.io/pypi/v/pyjstage2)
+
+## Overview
+
+[J-STAGE WebAPI](https://www.jstage.jst.go.jp/static/pages/OtherJstageServices/TAB2/-char/ja) Wrapper for Python 3.
+
+- J-STAGE is an electronic journal platform for science and technology information in Japan, developed and managed by the Japan Science and Technology Agency (JST).
+- This package is a **Python 3.12 compatible fork** of [pyjstage](https://pypi.org/project/pyjstage/).
+
+## Acknowledgments
+
+This project is modified based on [matsurih/pyjstage](https://github.com/matsurih/pyjstage) (v0.0.2).
+
+Special thanks to the original author [@matsurih](https://github.com/matsurih) for creating this useful J-STAGE API wrapper.
+
+## What's Changed
+
+| Package | Original | Forked |
+|---------|----------|--------|
+| lxml | 4.4.2 | >=5.0.0 |
+| requests | 2.22.0 | >=2.31.0 |
+| urllib3 | 1.25.7 | >=2.0.0 |
+| certifi | 2019.11.28 | >=2023.0.0 |
+
+- Fixed absolute imports to relative imports
+- Fixed private method name mangling (`__finish_setup` → `_finish_setup`)
+- Added `__init__.py` export for cleaner imports
+
+## Prerequisites
+
+- Python >= 3.12
+
+## Installation
+
+```shell
+$ pip install pyjstage2
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+from pyjstage.pyjstage import Pyjstage
+
+jstage = Pyjstage()
+
+# Search by ISSN
+ret_search = jstage.search(issn='2186-6619', count=3)
+
+# List articles in a journal
+ret_list = jstage.list(issn='2186-6619')
+```
+
+### Accessing Results
+
+```python
+for entry in ret_search.entries:
+    print(f"Title: {entry.title}")
+    print(f"Author: {entry.author.get('ja', '')}")
+    print(f"Journal: {entry.material_title.get('ja', '')}")
+    print(f"Year: {entry.pubyear}")
+    print(f"DOI: {entry.doi}")
+    print(f"Link: {entry.link}")
+```
+
+### Search Parameters
+
+```python
+jstage.search(
+    pubyearfrom=2020,      # Search from year
+    pubyearto=2024,        # Search to year
+    material='journal',    # Journal name contains
+    article='title',       # Article title contains
+    author='name',         # Author name contains
+    keyword='AI',          # Keyword contains
+    issn='2186-6619',      # ISSN
+    count=10               # Number of results (max 1000)
+)
+```
+
+## Important Notes
+
+### What J-STAGE API Provides
+
+- ✅ **Literature search** - Search by ISSN, keyword, author, year, etc.
+- ✅ **Metadata** - Title, author, journal, year, DOI, page numbers
+- ✅ **Article links** - Links to J-STAGE article pages
+
+### What J-STAGE API Does NOT Provide
+
+- ❌ **Full-text PDF download** - The API does not provide direct PDF downloads
+- ❌ **Full-text content** - The API returns metadata, not full article text
+
+To access full-text content, use the `link` or `doi` fields to visit the publisher's website.
+
+## Changelog
+
+### v0.1.2 (2025-06-16)
+
+- **Fix**: Null-safe XML parsing in `SearchResult` and `ListResult` — handles missing/empty XML elements without raising `AttributeError`
+- **Fix**: `WARN_002` (too many results) is now treated as a warning instead of raising an error, since the API still returns valid data
+
+### v0.1.1 (2025-05-18)
+
+- First PyPI release as `pyjstage2`
+- Python 3.12 compatibility
+- Updated dependencies (lxml >=5.0, requests >=2.31, urllib3 >=2.0)
+
+## Source Code
+
+https://github.com/lanshi17/pyjstage
+
+## License
+
+MIT License - see [LICENSE](https://github.com/lanshi17/pyjstage/blob/master/LICENSE) file.

pyjstage2-0.1.2/pyjstage/__init__.py

@@ -0,0 +1 @@
+from .pyjstage import Pyjstage

pyjstage2-0.1.2/pyjstage/entry.py

@@ -0,0 +1,76 @@
+class Entry:
+    """Base class for Entry
+
+    Attributes:
+        issn: ISSN
+        eissn: eISSN
+        cdjournal: journal name
+        material_title: journal title
+        volume: journal volume
+        number: journal number
+        starting_page: starting page this document is.
+        pubyear: Published year.
+        systemcode: System code
+        systemname: System name
+        title: Title
+        link: Link
+        id: ID, it is always the same as link parameter.
+        updated: updated date
+    """
+    def __init__(self):
+        """Initialize Entry class"""
+        self.issn = None
+        self.eissn = None
+        self.cdjournal = None
+        self.material_title = None
+        self.volume = None
+        self.number = None
+        self.starting_page = None
+        self.pubyear = None
+        self.systemcode = None
+        self.systemname = None
+        self.title = None
+        self.link = None
+        self.id = None
+        self.updated = None
+
+    def __str__(self):
+        return str(self.__dict__.items())
+
+
+class ListEntry(Entry):
+    """Entry class for List API
+
+    Attributes:
+        vols_title: volumes title
+        vols_link: volumes link
+        publisher_name: publisher name
+        publisher_url: publisher url
+    """
+    def __init__(self):
+        """Initialize ListEntry class"""
+        super().__init__()
+        self.vols_title = {}
+        self.vols_link = {}
+        self.publisher_name = None
+        self.publisher_url = {}
+
+
+class SearchEntry(Entry):
+    """Entry class for Search API
+
+    Attributes:
+        article_title: article title
+        article_link: article link
+        author: article author
+        ending_page: ending page
+        doi: DOI
+    """
+    def __init__(self):
+        """Initialize SearchEntry class"""
+        super().__init__()
+        self.article_title = {}
+        self.article_link = None
+        self.author = None
+        self.ending_page = None
+        self.doi = None

pyjstage2-0.1.2/pyjstage/errors.py

@@ -0,0 +1,78 @@
+class JstageError(Exception):
+    """Abstract class for errors caused by J-STAGE API"""
+    pass
+
+
+class JstageWarning(Warning):
+    """Abstract class for warnings caused by J-STAGE API"""
+    pass
+
+
+class NoResultsError(JstageError):
+    """ERR_001"""
+    pass
+
+
+class TooManyResultsError(JstageWarning):
+    """WARN_001"""
+    pass
+
+
+class TooManyRequestsError(JstageError):
+    """ERR_003"""
+    pass
+
+
+class InvalidQueryError(JstageError):
+    """ERR_004"""
+    pass
+
+
+class EmptyRequiredFieldError(JstageError):
+    """ERR_005"""
+    pass
+
+
+class InvalidYearValueError(JstageError):
+    """ERR_006"""
+    pass
+
+
+class InvalidCountsError(JstageError):
+    """ERR_007"""
+    pass
+
+
+class InvalidIssnError(JstageError):
+    """ERR_008"""
+    pass
+
+
+class SystemFatalError(JstageError):
+    """SYS_ERR_009"""
+    pass
+
+
+class InvalidUrlError(JstageError):
+    """ERR_010"""
+    pass
+
+
+class ListNoQueryError(JstageError):
+    """ERR_011"""
+    pass
+
+
+class SearchNoQueryError(JstageError):
+    """ERR_012"""
+    pass
+
+
+class ListUnspecifiedError(JstageError):
+    """ERR_013"""
+    pass
+
+
+class SearchUnsortableError(JstageError):
+    """ERR_014"""
+    pass

pyjstage2-0.1.2/pyjstage/order.py

@@ -0,0 +1,21 @@
+from enum import Enum
+
+
+class ListOrder(Enum):
+    """Enum for list's order
+
+    ListOrder.ASCENDING: sort by ascending
+    ListOrder.DESCENDING: sort by descending
+    """
+    ASCENDING = 1
+    DESCENDING = 2
+
+
+class SearchOrder(Enum):
+    """Enum for search's order
+
+    SearchOrder.SCORE: sort by score
+    SearchOrder.NUMBER: sort by number ascending
+    """
+    SCORE = 1
+    NUMBER = 2

pyjstage2-0.1.2/pyjstage/parser.py

@@ -0,0 +1,56 @@
+from lxml import etree
+from .result import Result, ListResult, SearchResult
+from .status import Status
+from datetime import datetime
+import re
+
+
+class Parser:
+    """Parser Class"""
+    def __init__(self):
+        """Initialize Parser class"""
+        self.regex = re.compile(r'\n* +')
+
+    def parse(self, xml_text: bytes) -> Result:
+        """Parse XML returned from J-STAGE API
+
+        Parse XML document (as bytes object) into Result object.
+        This function may raise Error or Warning.
+        If that error starts with Jstage, that error was occurred by J-STAGE.
+
+        Args:
+            xml_text: raw xml text's bytes encoded by UTF-8
+        Returns:
+            Result object which contains meta data and contents.
+        Raises:
+            JstageError: error depending on j-stage api
+            JstageWarning: warning depending on j-stage api
+        """
+        result = Result()
+
+        root = etree.fromstring(xml_text)
+        result.xmlns = root.nsmap
+        result.xmlns['xml'] = 'http://www.w3.org/XML/1998/namespace'
+        result.xml_lang = root.find('[@xml:lang]', result.xmlns).attrib.values()[0]
+        result.xml_version = etree.ElementTree(root).docinfo.xml_version
+        result.encoding = etree.ElementTree(root).docinfo.encoding
+        result.servicecd = int(root.find('./servicecd', result.xmlns).text)
+        result.title = root.find('./title', result.xmlns).text
+        result.link = self.regex.sub('', root.find('./link', result.xmlns).attrib['href'])
+        result.id = self.regex.sub('', root.find('./id', result.xmlns).text)
+        result.updated = datetime.fromisoformat(root.find('./updated', result.xmlns).text)
+        result.total_results = int(root.find('./opensearch:totalResults', result.xmlns).text)
+        result.start_index = int(root.find('./opensearch:startIndex', result.xmlns).text)
+        result.items_per_page = int(root.find('./opensearch:itemsPerPage', result.xmlns).text)
+        result.entries = list(root.findall('./entry', result.xmlns))
+        result.status = root.find('./result/status', result.xmlns).text
+        result.message = root.find('./result/message', result.xmlns).text
+        Status.divide(result.status, result.message)
+        if result.servicecd == 2:
+            rresult = ListResult(result)
+        elif result.servicecd == 3:
+            rresult = SearchResult(result)
+        else:
+            raise Exception('Undefined service code')
+
+        return rresult

pyjstage2-0.1.2/pyjstage/pyjstage.py

@@ -0,0 +1,153 @@
+from .result import Result
+from .parser import Parser
+from .service import Service
+from .order import ListOrder, SearchOrder
+from urllib.parse import quote
+from typing import List, Union
+import requests
+
+
+class Pyjstage:
+    """Pyjstage Class
+
+    Attributes:
+        domain: J-STAGE API domain
+        parser: Parser object
+    """
+    def __init__(self, domain: str = 'http://api.jstage.jst.go.jp/searchapi/do?'):
+        """Initialize Pyjstage class
+
+        Args:
+            domain: (Optional) J-STAGE API domain
+        """
+        self.domain: str = domain
+        self.parser: Parser = Parser()
+
+    def list(
+            self,
+            pubyearfrom: int = None,
+            pubyearto: int = None,
+            material: Union[str, List[str]] = None,
+            issn: str = None,
+            cdjournal: str = None,
+            volorder: ListOrder = None
+    ) -> Result:
+        """Access LIST API
+
+        Access LIST API and parse result as ListResult Object.
+        Union[xxx, List[xxx]] arguments can multiple value as list object.
+        If you set that argument as list, Search as 'AND'
+
+        Args:
+            pubyearfrom: (Optional) Year you want to search when papers were published from.
+            pubyearto: (Optional) Year you want to search when papers were published to.
+            material: (Optional) Keyword journal should contain.
+            issn: (Optional) ISSN you want to search.
+            cdjournal: (Optional) Journal code you want to search.
+            volorder: (Optional) How order are responses sorted.
+        Returns:
+            ListResult object which contains meta data and contents
+        Raises:
+            JstageError: Error caused by J-STAGE API
+            JstageWarning: Warning caused by J-STAGE API
+        """
+        url = self.build_query(
+            service=Service.LIST.value,
+            pubyearfrom=pubyearfrom,
+            pubyearto=pubyearto,
+            material=material,
+            issn=issn,
+            cdjournal=cdjournal,
+            volorder=volorder.value)
+        response = requests.get(url)
+        return self.parser.parse(response.text.encode('utf-8'))
+
+    def search(
+            self,
+            pubyearfrom: int = None,
+            pubyearto: int = None,
+            material: Union[str, List[str]] = None,
+            article: Union[str, List[str]] = None,
+            author: Union[str, List[str]] = None,
+            affile: Union[str, List[str]] = None,
+            keyword: Union[str, List[str]] = None,
+            abst: Union[str, List[str]] = None,
+            text: Union[str, List[str]] = None,
+            issn: str = None,
+            cdjournal: str = None,
+            sortfig: SearchOrder = None,
+            vol: int = None,
+            no: int = None,
+            start: int = None,
+            count: int = None
+    ) -> Result:
+        """Access SEARCH API
+
+        Access SEARCH API and parse result as SearchResult Object.
+        Union[xxx, List[xxx]] arguments can multiple value as list object.
+        If you set that argument as list, Search as 'AND'
+
+        Args:
+            pubyearfrom: (Optional) Year you want to search when papers were published from.
+            pubyearto: (Optional) Year you want to search when papers were published to.
+            material: (Optional) Keyword journal should contain.
+            article: Keyword document's title should contain.
+            author: Keyword document's author name should contain.
+            affile: Keyword document's author's affile name should contain.
+            keyword: Keyword document's keyword should contain.
+            abst: Keyword document's abstract should contain.
+            text: Keyword document's body should contain
+            issn: (Optional) ISSN you want to search.
+            cdjournal: (Optional) Journal code you want to search.
+            sortfig: How order are responses sorted.
+            vol: What volume is document contained in journal
+            no: What number is document contained in journal
+            start: How many offsets you want to set, default 0.
+            count: How many results you want to fetch, max & default is 1000.
+        Returns:
+            SearchResult object which contains meta data and contents
+        Raises:
+            xxxError: xxx
+        """
+        url = self.build_query(
+            service=Service.SEARCH.value,
+            pubyearfrom=pubyearfrom,
+            pubyearto=pubyearto,
+            material=material,
+            article=article,
+            author=author,
+            affile=affile,
+            keyword=keyword,
+            abst=abst,
+            text=text,
+            issn=issn,
+            cdjournal=cdjournal,
+            sortfig=sortfig.value if sortfig else None,
+            vol=vol,
+            no=no,
+            start=start,
+            count=count
+        )
+        response = requests.get(url)
+        result = self.parser.parse(response.text.encode('utf-8'))
+        return result
+
+    def build_query(self, **kwargs):
+        """Build url with queries
+
+        Args:
+            kwargs: key-value pairs for querying. If multiple values, use list.
+        Returns:
+            URL-string which can access J-STAGE API
+        """
+        return self.domain + '&'.join(
+            [
+                f'{quote(k, encoding="utf8")}={quote(str(v) if type(v) is not list else " ".join(v), encoding="utf8")}'
+                for k, v in kwargs.items() if v is not None
+            ]
+        )
+
+if __name__ == '__main__':
+    pj = Pyjstage()
+    ret = pj.search(text=['統合失調症', '精神分裂病'], count=10)
+    print(ret)