cacholong-cloud-cli 0.3.0__py3-none-any.whl

jsonapi_client/document.py

@@ -0,0 +1,161 @@
+"""
+JSON API Python client 
+https://github.com/qvantel/jsonapi-client
+
+(see JSON API specification in http://jsonapi.org/)
+
+Copyright (c) 2017, Qvantel
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the Qvantel nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL QVANTEL BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+
+import logging
+from typing import TYPE_CHECKING, Iterator, AsyncIterator, List
+
+from .common import AbstractJsonObject
+from .exceptions import ValidationError, DocumentError
+from .objects import Meta, Links
+from .resourceobject import ResourceObject
+
+if TYPE_CHECKING:
+    from .session import Session
+
+
+logger = logging.getLogger(__name__)
+
+
+class Document(AbstractJsonObject):
+    """
+    Top level of JSON API document.
+    Contains one or more ResourceObjects.
+
+    http://jsonapi.org/format/#document-top-level
+    """
+
+    #: List of ResourceObjects contained in this Document
+    resources: List['ResourceObject']
+
+    def __init__(self, session: 'Session',
+                 json_data: dict,
+                 url: str,
+                 no_cache: bool=False) -> None:
+        self._no_cache = no_cache  # if true, do not store resources to session cache
+        self._url = url
+        super().__init__(session, json_data)
+
+    @property
+    def url(self) -> str:
+        return self._url
+
+    @property
+    def resource(self) -> 'ResourceObject':
+        """
+        If there is only 1 ResourceObject contained in this Document, return it.
+        """
+        if len(self.resources) > 1:
+            logger.warning('There are more than 1 item in document %s, please use '
+                           '.resources!', self)
+        return self.resources[0]
+
+    def _handle_data(self, json_data):
+        data = json_data.get('data')
+
+        self.resources = []
+
+        if data:
+            if isinstance(data, list):
+                self.resources.extend([ResourceObject(self.session, i) for i in data])
+            elif isinstance(data, dict):
+                self.resources.append(ResourceObject(self.session, data))
+
+        self.errors = json_data.get('errors')
+        if [data, self.errors] == [None]*2:
+            raise ValidationError('Data or errors is needed')
+        if data and self.errors:
+            logger.error('Data and errors can not both exist in the same document')
+
+        self.meta = Meta(self.session, json_data.get('meta', {}))
+
+        self.jsonapi = json_data.get('jsonapi', {})
+        self.links = Links(self.session, json_data.get('links', {}))
+        if self.errors:
+            raise DocumentError(f'Error document was fetched. Details: {self.errors}',
+                                errors=self.errors)
+        self.included = [ResourceObject(self.session, i)
+                         for i in json_data.get('included', [])]
+        if not self._no_cache:
+            self.session.add_resources(*self.resources, *self.included)
+
+    def __str__(self):
+        return f'{self.resources}' if self.resources else f'{self.errors}'
+
+    def _iterator_sync(self) -> 'Iterator[ResourceObject]':
+        # if we currently have no items on the page, then there's no need to yield items
+        # and check the next page
+        # we do this because there are APIs that always have a 'next' link, even when 
+        # there are no items on the page
+        if len(self.resources) == 0:
+            return
+        
+        yield from self.resources
+
+        if self.links.next:
+            next_doc = self.links.next.fetch()
+            yield from next_doc.iterator()
+
+    async def _iterator_async(self) -> 'AsyncIterator[ResourceObject]':
+        # if we currently have no items on the page, then there's no need to yield items
+        # and check the next page
+        # we do this because there are APIs that always have a 'next' link, even when 
+        # there are no items on the page
+        if len(self.resources) == 0:
+            return
+        
+        for res in self.resources:
+            yield res
+
+        if self.links.next:
+            next_doc = await self.links.next.fetch()
+            async for res in next_doc.iterator():
+                yield res
+
+    def iterator(self):
+        """
+        Iterate through all resources of this Document and follow pagination until
+        there's no more resources.
+
+        If Session is in async mode, this needs to be used with async for.
+        """
+        if self.session.enable_async:
+            return self._iterator_async()
+        else:
+            return self._iterator_sync()
+
+    def mark_invalid(self):
+        """
+        Mark this Document and it's resources invalid.
+        """
+        super().mark_invalid()
+        for r in self.resources:
+            r.mark_invalid()

jsonapi_client/exceptions.py

@@ -0,0 +1,62 @@
+"""
+JSON API Python client 
+https://github.com/qvantel/jsonapi-client
+
+(see JSON API specification in http://jsonapi.org/)
+
+Copyright (c) 2017, Qvantel
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the Qvantel nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL QVANTEL BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+
+
+class JsonApiClientError(Exception):
+    """
+    Generic exception class for jsonapi-client
+    """
+    pass
+
+
+class ValidationError(JsonApiClientError):
+    pass
+
+
+class DocumentError(JsonApiClientError):
+    """
+    Raised when 404 or other error takes place.
+    Status code is stored in errors['status_code'].
+    """
+    def __init__(self, *args, errors, **kwargs):
+        super().__init__(*args)
+        self.errors = errors
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+
+class DocumentInvalid(JsonApiClientError):
+    pass
+
+
+class AsyncError(JsonApiClientError):
+    pass

jsonapi_client/filter.py

@@ -0,0 +1,155 @@
+"""
+JSON API Python client 
+https://github.com/qvantel/jsonapi-client
+
+(see JSON API specification in http://jsonapi.org/)
+
+Copyright (c) 2017, Qvantel
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the Qvantel nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL QVANTEL BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+
+from typing import TYPE_CHECKING, Union, Dict, Sequence
+
+if TYPE_CHECKING:
+    FilterKeywords = Dict[str, Union[str, Sequence[Union[str, int, float]]]]
+    IncludeKeywords = Sequence[str]
+
+
+class Modifier:
+    """
+    Base class for query modifiers.
+    You can derive your own class and use it if you have custom syntax.
+    """
+    def __init__(self, query_str: str='') -> None:
+        self._query_str = query_str
+
+    def url_with_modifiers(self, base_url: str) -> str:
+        """
+        Returns url with modifiers appended.
+
+        Example:
+            Modifier('filter[attr1]=1,2&filter[attr2]=2').filtered_url('doc')
+              -> 'GET doc?filter[attr1]=1,2&filter[attr2]=2'
+        """
+        filter_query = self.appended_query()
+        fetch_url = f'{base_url}?{filter_query}'
+        return fetch_url
+
+    def appended_query(self) -> str:
+        return self._query_str
+
+    def __add__(self, other: 'Modifier') -> 'Modifier':
+        mods = []
+        for m in [self, other]:
+            if isinstance(m, ModifierSum):
+                mods += m.modifiers
+            else:
+                mods.append(m)
+        return ModifierSum(mods)
+
+
+class ModifierSum(Modifier):
+    def __init__(self, modifiers):
+        self.modifiers = modifiers
+
+    def appended_query(self) -> str:
+        return '&'.join(m.appended_query() for m in self.modifiers)
+
+
+class Filter(Modifier):
+    """
+    Implements query filtering for Session.get etc.
+    You can derive your own filter class and use it if you have a
+    custom filter query syntax.
+    """
+    def __init__(self, query_str: str='', **filter_kwargs: 'FilterKeywords') -> None:
+        """
+        :param query_str: Specify query string manually.
+        :param filter_kwargs: Specify required conditions on result.
+            Example: Filter(attribute='1', relation__attribute='2')
+        """
+        super().__init__(query_str)
+        self._filter_kwargs = filter_kwargs
+
+    # This and next method prevent any existing subclasses from breaking
+    def url_with_modifiers(self, base_url: str) -> str:
+        return self.filtered_url(base_url)
+
+    def filtered_url(self, base_url: str) -> str:
+        return super().url_with_modifiers(base_url)
+
+    def appended_query(self) -> str:
+        return super().appended_query() or self.format_filter_query(**self._filter_kwargs)
+
+    def format_filter_query(self, **kwargs: 'FilterKeywords') -> str:
+        """
+        Filter class that implements url filtering scheme according to JSONAPI
+        recommendations (http://jsonapi.org/recommendations/)
+        """
+        def jsonify_key(key):
+            return key.replace('__', '.').replace('_', '-')
+        return '&'.join(f'filter[{jsonify_key(key)}]={value}'
+                        for key, value in kwargs.items())
+
+
+class Inclusion(Modifier):
+    """
+    Implements query inclusion for Session.get etc.
+    """
+    def __init__(self, *include_args: 'IncludeKeywords') -> None:
+        super().__init__()
+        self._include_args = include_args
+
+    def appended_query(self) -> str:
+        includes = ','.join(self._include_args)
+        return f'include={includes}'
+
+
+class Sort(Modifier):
+    """
+    Implements query inclusion for Session.get etc.
+    """
+    def __init__(self, *sort_args: 'SortKeywords') -> None:
+        super().__init__()
+        self._sort_args = sort_args
+
+    def appended_query(self) -> str:
+        sort_by = ','.join(self._sort_args)
+        return f'sort={sort_by}'
+
+
+class SparseField(Modifier):
+    """
+    Implement sparse fields
+    """
+    def __init__(self, resource: str, *sparse_field_args: 'SparseFieldKeywords') -> None:
+        super().__init__()
+        self._resource = resource
+        self._sparse_field_args = sparse_field_args
+
+    def appended_query(self) -> str:
+        sparse_fields = ','.join(self._sparse_field_args)
+        resource = self._resource
+        return f'fields[{resource}]={sparse_fields}'

jsonapi_client/objects.py

@@ -0,0 +1,187 @@
+"""
+JSON API Python client
+https://github.com/qvantel/jsonapi-client
+
+(see JSON API specification in http://jsonapi.org/)
+
+Copyright (c) 2017, Qvantel
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the Qvantel nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL QVANTEL BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+
+import logging
+from itertools import chain
+from typing import Optional, Union, Awaitable, TYPE_CHECKING
+from urllib.parse import urlparse
+
+from .common import AbstractJsonObject, jsonify_attribute_name, ResourceTuple
+from .resourceobject import ResourceObject
+
+if TYPE_CHECKING:
+    from .document import Document
+
+logger = logging.getLogger(__name__)
+
+
+class Meta(AbstractJsonObject):
+    """
+    Object type for meta data
+
+    http://jsonapi.org/format/#document-meta
+    """
+    def _handle_data(self, data):
+        self.meta = data
+
+    def __getattr__(self, name):
+        return self.meta.get(jsonify_attribute_name(name))
+
+    def __getitem__(self, name):
+        return self.meta.get(name)
+
+    def __str__(self):
+        return str(self.meta)
+
+
+class Link(AbstractJsonObject):
+    """
+    Object type for a single link
+
+    http://jsonapi.org/format/#document-links
+    """
+    def _handle_data(self, data):
+        if data:
+            if isinstance(data, str):
+                self.href = data
+            else:
+                self.href = data['href']
+                self.meta = Meta(self.session, data.get('meta', {}))
+        else:
+            self.href = ''
+
+    def __eq__(self, other):
+        return self.href == other.href
+
+    def __bool__(self):
+        return bool(self.href)
+
+    @property
+    def url(self) -> str:
+        if urlparse(self.href).scheme:  # if href contains only relative link
+            return self.href
+        else:
+            return f'{self.session.server_url}{self.href}'
+
+    def __str__(self):
+        return self.url if self.href else ''
+
+    def fetch_sync(self) -> 'Optional[Document]':
+        self.session.assert_sync()
+        if self:
+            return self.session.fetch_document_by_url(self.url)
+
+    def fetch(self):
+        if self.session.enable_async:
+            return self.fetch_async()
+        else:
+            return self.fetch_sync()
+
+    async def fetch_async(self) -> 'Optional[Document]':
+        self.session.assert_async()
+        if self:
+            return await self.session.fetch_document_by_url_async(self.url)
+
+
+class Links(AbstractJsonObject):
+    """
+    Object type for container of links
+
+    http://jsonapi.org/format/#document-links
+    """
+    def _handle_data(self, data):
+        self._links = {key: Link(self.session, value) for key, value in data.items()}
+
+    def __getattr__(self, item):
+        attr = self._links.get(item)
+        if not attr:
+            return Link(self.session, '')
+        return attr
+
+    def __bool__(self):
+        return bool(self._links)
+
+    def __dir__(self):
+        return chain(super().__dir__(), self._links.keys())
+
+    def __str__(self):
+        return str(self._links)
+
+
+class ResourceIdentifier(AbstractJsonObject):
+    """
+    Object type for resource identifier
+
+    http://jsonapi.org/format/#document-resource-identifier-objects
+    """
+    def _handle_data(self, data):
+        self.id:str = data.get('id')
+        self.type:str = data.get('type')
+        self.meta = data.get('meta')
+
+    @property
+    def url(self):
+        return f'{self.session.url_prefix}/{self.type}/{self.id}'
+
+    def __str__(self):
+        return f'{self.type}: {self.id} ({self.meta})'
+
+    def fetch_sync(self, cache_only=True) -> 'ResourceObject':
+        return self.session.fetch_resource_by_resource_identifier(self, cache_only)
+
+    async def fetch_async(self, cache_only=True) -> 'ResourceObject':
+        return await self.session.fetch_resource_by_resource_identifier_async(self,
+                                                                              cache_only)
+
+    def fetch(self, cache_only=True) \
+            -> 'Union[Awaitable[ResourceObject], ResourceObject]':
+        if self.session.enable_async:
+            return self.fetch_async(cache_only)
+        else:
+            return self.fetch_sync(cache_only)
+
+    def as_resource_identifier_dict(self) -> dict:
+        if not self.id:
+            return None
+        res = {
+            'id': self.id,
+            'type': self.type,
+        }
+        if self.meta:
+            res['meta'] = self.meta
+        return res
+
+    def __bool__(self):
+        return self.id is not None
+
+RESOURCE_TYPES = (ResourceObject, ResourceIdentifier, ResourceTuple)
+ResourceTypes = Union[ResourceObject, ResourceIdentifier, ResourceTuple]