ads 0.12.6__py3-none-any.whl

ads/__init__.py

@@ -0,0 +1,12 @@
+
+# coding: utf-8
+
+""" A Python tool for interacting with NASA's ADS """
+
+__version__ = "0.12.6"
+
+from .metrics import MetricsQuery
+from .export import ExportQuery
+from .search import SearchQuery, query
+from .base import RateLimits
+#from .libraries import LibraryQuery, Library #soon

ads/base.py

@@ -0,0 +1,165 @@
+"""
+Base classes for the ads client
+"""
+
+import requests
+import warnings
+import json
+import os
+
+from .exceptions import APIResponseError
+from .config import TOKEN_FILES, TOKEN_ENVIRON_VARS
+from . import __version__
+import ads.config  # For manually setting the token
+
+
+class _Singleton(type):
+    _instances = {}
+
+    def __call__(cls, name, *args, **kwargs):
+        if name not in cls._instances:
+            cls._instances[name] = super(_Singleton, cls).__call__(name, *args, **kwargs)
+        return cls._instances[name]
+
+    @classmethod
+    def get_info(cls):
+        """
+        Print all of the instantiated Singletons
+        """
+        return '\n'.join(
+            [str(cls._instances[key]) for key in cls._instances]
+        )
+
+
+class Singleton(_Singleton('SingletonMeta', (object,), {})):
+    """
+    Wrapper class so that the Singleton metaclass works for both Python 2&3
+    """
+    pass
+
+
+class RateLimits(Singleton):
+    response_to_query = {
+            'SolrResponse': 'SearchQuery',
+            'MetricsResponse': 'MetricsQuery',
+            'ExportResponse': 'ExportQuery'
+        }
+
+    def __init__(self, name):
+        self.limits = {}
+        self.name = self.response_to_query.get(name, name)
+
+    @classmethod
+    def getRateLimits(cls, name):
+        return cls(cls.response_to_query.get(name, name))
+
+    def set(self, headers):
+        self.limits = {
+            'limit': headers.get('x-ratelimit-limit', ''),
+            'remaining': headers.get('x-ratelimit-remaining', ''),
+            'reset': headers.get('x-ratelimit-reset', '')
+        }
+
+    def to_dict(self):
+        return self.limits
+
+    def __str__(self):
+        return '{}: {}'.format(
+            self.name,
+            json.dumps(self.limits)
+        )
+
+
+class APIResponse(object):
+    """
+    Represents an adsws-api http response
+    """
+    response = None
+
+    @classmethod
+    def get_ratelimits(cls):
+        """
+        Return the current, maximum, and reset rate limits from the response
+        header as a dictionary. The values will be strings.
+        """
+        return RateLimits.getRateLimits(cls.__name__).to_dict()
+
+    @classmethod
+    def load_http_response(cls, http_response):
+        """
+        This method should return an instantiated class and set its response
+        to the requests.Response object.
+        """
+        if not http_response.ok:
+            raise APIResponseError(http_response.text)
+        c = cls(http_response)
+        c.response = http_response
+
+        RateLimits.getRateLimits(cls.__name__).set(c.response.headers)
+
+        return c
+
+
+class BaseQuery(object):
+    """
+    Represents an arbitrary query to the adsws-api
+    """
+    _session = None
+    _token = ads.config.token
+
+    @property
+    def token(self):
+        """
+        set the instance attribute `token` following the following logic,
+        stopping whenever a token is found. Raises NoTokenFound is no token
+        is found
+        - environment variables TOKEN_ENVIRON_VARS
+        - file containing plaintext as the contents in TOKEN_FILES
+        - ads.config.token
+        """
+        if self._token is None:
+            for v in map(os.environ.get, TOKEN_ENVIRON_VARS):
+                if v is not None:
+                    self._token = v
+                    return self._token
+            for f in TOKEN_FILES:
+                try:
+                    with open(f) as fp:
+                        self._token = fp.read().strip()
+                        return self._token
+                except IOError:
+                    pass
+            if ads.config.token is not None:
+                self._token = ads.config.token
+                return self._token
+            warnings.warn("No token found", RuntimeWarning)
+        return self._token
+
+    @token.setter
+    def token(self, value):
+        self._token = value
+
+    @property
+    def session(self):
+        """
+        http session interface, transparent proxy to requests.session
+        """
+        if self._session is None:
+            self._session = requests.session()
+            self._session.headers.update(
+                {
+                    "Authorization": "Bearer {}".format(self.token),
+                    "User-Agent": "ads-api-client/{}".format(__version__),
+                    "Content-Type": "application/json",
+                }
+            )
+        return self._session
+
+    def __call__(self):
+        return self.execute()
+
+    def execute(self):
+        """
+        Each subclass should define their own execute method
+        """
+        raise NotImplementedError

ads/config.py

@@ -0,0 +1,21 @@
+"""
+configuration
+"""
+import os
+
+# API urls
+ADSWS_API_URL = 'https://api.adsabs.harvard.edu/v1'
+SEARCH_URL = '{}/search/query/'.format(ADSWS_API_URL)
+BIGQUERY_URL = '{}/search/bigquery/'.format(ADSWS_API_URL)
+METRICS_URL = '{}/metrics/'.format(ADSWS_API_URL)
+EXPORT_URL = '{}/export/'.format(ADSWS_API_URL)
+
+# Token discovery variables
+TOKEN_FILES = list(map(os.path.expanduser,
+    [
+        "~/.ads/token",
+        "~/.ads/dev_key",
+    ]
+))
+TOKEN_ENVIRON_VARS = ["ADS_API_TOKEN", "ADS_DEV_KEY"]
+token = None  # for setting in-situ

ads/exceptions.py

@@ -0,0 +1,25 @@
+"""
+Custom exceptions
+"""
+
+
+class APIResponseError(Exception):
+    """
+    Raised on a HTTP error from the API
+    """
+    def __init__(self, value=None):
+        self.value = value
+
+    def __str__(self):
+        return repr(self.value)
+
+
+class SolrResponseParseError(Exception):
+    """
+    Raised when solr returns an error
+    """
+    def __init__(self, value=None):
+        self.value = value
+
+    def __str__(self):
+        return repr(self.value)

ads/export.py

@@ -0,0 +1,65 @@
+"""
+interfaces to the adsws export service
+"""
+
+import json
+import six
+import os
+
+from .base import APIResponse, BaseQuery
+from .config import EXPORT_URL
+
+
+class ExportResponse(APIResponse):
+    """
+    Data structure that represents a response from the ads export service
+    """
+    def __init__(self, http_response):
+        self._raw = http_response.text
+        self.result = http_response.json()['export']
+
+    def __str__(self):
+        if six.PY3:
+            return self.__unicode__()
+        return self.__unicode__().encode("utf-8")
+
+    def __unicode__(self):
+        return self.result
+
+
+class ExportQuery(BaseQuery):
+    """
+    Represents a query to the adsws export service
+    """
+
+    HTTP_ENDPOINT = EXPORT_URL
+    FORMATS = ['bibtex', 'bibtexabs', 'ads','endnote', 'aastex',
+               'ris', 'icarus', 'mnras', 'soph', 'votable']
+
+    def __init__(self, bibcodes, format="bibtex"):
+        """
+        :param bibcodes: Bibcodes to send to in the export query
+        :type bibcodes: list or string
+        :param format: format to export to
+        """
+        assert format in self.FORMATS, "Format must be one of {}".format(
+            self.FORMATS)
+
+        self.format = format
+
+        self.response = None  # current ExportResponse object
+        if isinstance(bibcodes, six.string_types):
+            bibcodes = [bibcodes]
+        self.bibcodes = bibcodes
+        self.json_payload = json.dumps({"bibcode": bibcodes})
+
+    def execute(self):
+        """
+        Execute the http request to the export service
+        :return ads-classic formatted export string
+        """
+        url = os.path.join(self.HTTP_ENDPOINT, self.format)
+        self.response = ExportResponse.load_http_response(
+            self.session.post(url, data=self.json_payload)
+        )
+        return self.response.result

ads/libraries.py

@@ -0,0 +1,263 @@
+"""Functions to interact with ADS libraries."""
+from .base import BaseQuery
+from .config import ADSWS_API_URL
+from .search import SearchQuery, Article
+import json
+import six
+
+def delete_library(id: str):
+    q = BaseQuery()
+    lib = Library(id)
+    q.session.delete(lib._docs_url)
+    
+def get_user_libraries():
+    q = BaseQuery()
+    out = q.session.get(Library._libraries_url).json()
+    return [Library(id=o.pop('id'), **o) for o in out]
+    
+class Library(BaseQuery):
+    """An object representing an ADS library."""
+    _biblib_url = f"{ADSWS_API_URL}/biblib"
+    _libraries_url = f"{_biblib_url}/libraries"
+    
+    def __init__(self, id: str, **meta):
+        
+        self.id = id
+        self._library_url = f"{self._libraries_url}/{id}"
+        self._docs_url = f"{self._biblib_url}/documents/{id}"
+        self._permissions_url = f"{self._biblib_url}/permissions/{id}"
+        self._ops_url = f"{self._libraries_url}/operations/{id}"
+
+        if not meta:
+            self._refresh_metadata()
+        else:
+            for key, val in meta.items():
+                setattr(self, key, val)
+        
+    def __eq__(self, other):
+        if not isinstance(other, self.__class__):
+            return False
+        
+        return self.id == other.id
+    
+    def _refresh_metadata(self):
+        meta = self.session.get(self._library_url).json()
+        for key, val in meta.items():
+            setattr(self, key, val)
+                
+    def set(self, **items):
+        assert all(name in ['name', 'description', 'public'] for name in items)
+        self.session.put(self._docs_url, payload=json.dumps(items))
+        self._refresh_metadata()
+
+    def get_documents(self, **kwargs):
+        """Return a :class:`~search.SearchQuery` representing all documents in this library."""
+        return SearchQuery(q=f'docs(library/{self.id})', **kwargs)
+
+    @staticmethod
+    def _to_bibcodes(docs):
+        if isinstance(docs, six.string_types):
+            return [docs]
+        
+        if not hasattr(docs, '__iter__'):
+            raise TypeError("docs must be a str or iterable of strings or Articles")
+
+        out = []
+        for d in docs:
+            if isinstance(d, six.string_types):
+                out.append(d)
+            elif isinstance(d, Article):
+                out.append(d.bibcode)
+
+        return out        
+        
+    def add_documents(self, docs) -> int:
+        """Add a list of documents to the library.
+        
+        :param docs: documents to add to the library.
+        :type docs: string bibcode, or sequence of string bibcodes, or sequence of 
+            :class:`search.Article`
+        """
+        docs = self._to_bibcodes(docs)
+        payload = {
+            'bibcode': docs,
+            'action': 'add'
+        }
+        
+        result = self.session.post(self._docs_url, data=json.dumps(payload))
+        
+        self._refresh_metadata()
+        return result.json().get('number_added', -1)
+    
+    
+    def remove_documents(self, docs) -> int:
+        """Remove a list of documents from the library.
+        
+        :param docs: documents to remove from the library.
+        :type docs: string bibcode, or sequence of string bibcodes, or sequence of 
+            :class:`search.Article`
+        """
+        docs = self._to_bibcodes(docs)
+                    
+        payload = {
+            'bibcode': docs,
+            'action': 'remove'
+        }
+
+        self._refresh_metadata()  
+        result = self.session.post(self._docs_url, data=json.dumps(payload))
+        return result.json()['number_removed']
+        
+    @classmethod
+    def new(cls, name=None, description='My ADS Library', public=False, docs=None):
+        """Create a new library and return it.
+        
+        :param name: Name of the library, default "Untitled Library" with incremented
+            integer appended.
+        :type name: string
+        :param description: description of the library.
+        :type description: str
+        :param public: whether the library should be public
+        :type public: bool
+        :param docs: documents to add to the library 
+        :type docs: string bibcode, or sequence of string bibcodes, or sequence of 
+            :class:`search.Article`
+        """
+        docs = cls._to_bibcodes(docs)
+        
+        payload = {'description': description, 'public': bool(public)}
+        if name:
+            payload['name'] = name
+            
+        if docs:
+            payload['docs'] = docs
+        
+        q = BaseQuery()
+        result = q.session.post(cls._libraries_url, data=json.dumps(payload))
+        
+        return cls(result.json()['id'])
+    
+    def get_user_permissions(self):
+        """Get persmissions of different users."""
+        return self.session.get(self._permissions_url).json()
+    
+    def edit_user_persmissions(self, email, permission):
+        """Edit permissions of a user (or add new user).
+        
+        :param email: email of the (new) user
+        :type email: str
+        :param permission: the associated permissions to set, should be a string
+            containing any combination of 'rwa' (read, write, admin).
+        """
+
+        assert [p in 'rwa' for p in permission]
+
+        permission = {
+            'read': 'r' in permission,
+            'write': 'w' in permission,
+            'admin': 'a' in permission            
+        }
+        
+        payload = {'permission': permission, 'email': email}
+        res = self.session.post(self._permissions_url, payload=json.dumps(payload))
+        
+        self._refresh_metadata()
+        
+        return res.json()['message']
+    
+    def _set_operations(self, action, libraries, **kwargs):
+        kw = {k: v for k, v in kwargs.items() if v is not None}
+        payload = {
+            'action': action,
+            'libraries': [l.id if isinstance(l, Library) else l for l in libraries],
+            **kw
+        }
+        res = self.session.post(self._ops_url, payload = json.dumps(payload))
+        return res.json()
+        
+    def union(self, libraries, name=None, description=None, public=False):
+        """Form a new library from the union of this library and other libraries.
+        
+        Returns the new :class:`Library` object.
+        
+        :param libraries: libraries to take the union of.
+        :type libraries: str identifier, :class:`Library` or sequence of such.
+        :param name: Name of the library, default "Untitled Library" with incremented
+            integer appended.
+        :type name: string
+        :param description: description of the library.
+        :type description: str
+        :param public: whether the library should be public
+        :type public: bool
+        """    
+        if isinstance(libraries, (str, Library)):
+            libraries = [libraries]
+        
+        res = self._set_operations('union', libraries, name=name, description=description, public=public)
+        return self.__class__(res['id'])
+    
+    def difference(self, libraries, name=None, description=None, public=False):
+        """Form a new library from the difference of this library and other libraries.
+        
+        Returns the new :class:`Library` object.
+        
+        :param libraries: libraries to difference with this one.
+        :type libraries: str identifier, :class:`Library` or sequence of such.
+        :param name: Name of the library, default "Untitled Library" with incremented
+            integer appended.
+        :type name: string
+        :param description: description of the library.
+        :type description: str
+        :param public: whether the library should be public
+        :type public: bool
+        """
+        if isinstance(libraries, (Library, str)):
+            libraries = [libraries]
+        
+        res = self._set_operations('difference', libraries, name=name, description=description, public=public)
+        return self.__class__(res['id'])
+    
+    def intersection(self, libraries, name=None, description=None, public=False):
+        """Form a new library from the intersection of this library and other libraries.
+        
+        Returns the new :class:`Library` object.
+        
+        :param libraries: libraries to take the intersect.
+        :type libraries: str identifier, :class:`Library` or sequence of such.
+        :param name: Name of the library, default "Untitled Library" with incremented
+            integer appended.
+        :type name: string
+        :param description: description of the library.
+        :type description: str
+        :param public: whether the library should be public
+        :type public: bool
+        """
+        if isinstance(libraries, (Library, str)):
+            libraries = [libraries]
+        
+        res = self._set_operations('intersection', libraries, name=name, description=description, public=public)
+        return self.__class__(res['id'])
+    
+    def empty(self):
+        """Empty this library of all documents."""
+        self._set_operations('empty', libraries=[])
+        self._refresh_metadata()
+
+    def copy_to(self, library):
+        """Copy documents in this library to another library.
+        
+        :param library: the library to copy to
+        :type library: str id or :class:`Library`.
+        """
+        library = [library]            
+        res = self._set_operations('copy', library)
+        return self.__class__(res['id'])
+    
+    def transfer_to(self, email):
+        """Transfer the library ownership to another user.
+        
+        :param email: the email to transfer ownership to.
+        """
+        self.session.post(f"{self._biblib_url}/transfer/{self.id}", payload=json.dumps({'email': email}))
+        self._refresh_metadata()
+    

ads/metrics.py

@@ -0,0 +1,54 @@
+"""
+interfaces to the adsws metrics service
+"""
+
+import json
+import six
+
+from .base import APIResponse, BaseQuery
+from .config import METRICS_URL
+
+
+class MetricsResponse(APIResponse):
+    """
+    Data structure that represents a response from the ads metrics service
+    """
+    def __init__(self, http_response):
+        self._raw = http_response.text
+        self.metrics = http_response.json()
+
+    def __str__(self):
+        if six.PY3:
+            return self.__unicode__()
+        return self.__unicode__().encode("utf-8")
+
+    def __unicode__(self):
+        return self.metrics
+
+
+class MetricsQuery(BaseQuery):
+    """
+    Represents a query to the adsws metrics service
+    """
+
+    HTTP_ENDPOINT = METRICS_URL
+
+    def __init__(self, bibcodes):
+        """
+        :param bibcodes: Bibcodes to send to in the metrics query
+        :type bibcodes: list or string
+        """
+        self.response = None  # current MetricsResponse object
+        if isinstance(bibcodes, six.string_types):
+            bibcodes = [bibcodes]
+        self.bibcodes = bibcodes
+        self.json_payload = json.dumps({"bibcodes": bibcodes})
+
+    def execute(self):
+        """
+        Execute the http request to the metrics service
+        """
+        self.response = MetricsResponse.load_http_response(
+            self.session.post(self.HTTP_ENDPOINT, data=self.json_payload)
+        )
+        return self.response.metrics

ads/sandbox.py

@@ -0,0 +1,58 @@
+"""
+Sandbox environment that wraps relevant classes so that they receive mock
+responses rather than contact the live API
+"""
+
+import re
+
+from ads import search
+from .search import SearchQuery as _SearchQuery, Article as _Article
+from .metrics import MetricsQuery as _MetricsQuery
+from .export import ExportQuery as _ExportQuery
+
+from .tests.mocks import MockSolrResponse, MockMetricsResponse, \
+    MockExportResponse
+
+
+class Article(_Article):
+    """
+    Wrapper for ads.search.Article
+    """
+    def _get_field(self, field):
+        with MockSolrResponse(_SearchQuery.HTTP_ENDPOINT):
+            return super(Article, self)._get_field(field)
+
+
+class SearchQuery(_SearchQuery):
+    """
+    Wrapper for ads.SearchQuery
+    """
+    def execute(self):
+        with MockSolrResponse(SearchQuery.HTTP_ENDPOINT):
+            super(SearchQuery, self).execute()
+
+
+class MetricsQuery(_MetricsQuery):
+    """
+    Wrapper for ads.SearchQuery
+    """
+
+    def execute(self):
+        with MockMetricsResponse(MetricsQuery.HTTP_ENDPOINT):
+            return super(MetricsQuery, self).execute()
+
+
+class ExportQuery(_ExportQuery):
+    """
+    Wrapper for ads.SearchQuery
+    """
+
+    def execute(self):
+        with MockExportResponse(re.compile(ExportQuery.HTTP_ENDPOINT)):
+            return super(ExportQuery, self).execute()
+
+
+# Monkey patch relevant classes that are called in ads.search
+search.Article = Article
+search.MetricsQuery = MetricsQuery
+search.ExportQuery = ExportQuery