Metadata-Version: 2.1
Name: python-epo-ops-client
Version: 3.1.0
Summary: Python Client for the European Patent Office's Open Patent Services API
Home-page: https://github.com/55minutes/python-epo-ops-client
Author: George Song
Author-email: george@monozuku.com
License: UNKNOWN
Download-URL: https://github.com/55minutes/python-epo-ops-client/archive/v3.1.0.tar.gz
Description: # python-epo-ops-client
        
        [![PyPI](https://img.shields.io/pypi/v/python-epo-ops-client)](https://pypi.org/project/python-epo-ops-client/)
        [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/python-epo-ops-client)](https://pypi.org/project/python-epo-ops-client/)
        [![Travis (.org)](https://img.shields.io/travis/55minutes/python-epo-ops-client)](https://travis-ci.org/55minutes/python-epo-ops-client)
        [![Coveralls github](https://img.shields.io/coveralls/github/55minutes/python-epo-ops-client)](https://coveralls.io/github/55minutes/python-epo-ops-client)
        
        python-epo-ops-client is an [Apache2 licensed][apache license] client library
        for accessing the [European Patent Office][epo]'s ("EPO") [Open Patent
        Services][ops] ("OPS") v.3.2 (based on [v 1.3.15 of the reference guide][ops guide]).
        
        ```python
        import epo_ops
        
        client = epo_ops.Client(key='abc', secret='xyz')  # Instantiate client
        response = client.published_data(  # Retrieve bibliography data
          reference_type = 'publication',  # publication, application, priority
          input = epo_ops.models.Docdb('1000000', 'EP', 'A1'),  # original, docdb, epodoc
          endpoint = 'biblio',  # optional, defaults to biblio in case of published_data
          constituents = []  # optional, list of constituents
        )
        ```
        
        ---
        
        ## Features
        
        `python-epo-ops-client` abstracts away the complexities of accessing EPO OPS:
        
        - Format the requests properly
        - Bubble up quota problems as proper HTTP errors
        - Handle token authentication and renewals automatically
        - Handle throttling properly
        - Add optional caching to minimize impact on the OPS servers
        
        There are two main layers to `python-epo-ops-client`: Client and Middleware.
        
        ### Client
        
        The Client contains all the formatting and token handling logic and is what
        you'll interact with mostly.
        
        When you issue a request, the response is a
        [requests.Response][requests.response] object. If `response.status_code != 200`
        then a `requests.HTTPError` exception will be raised — it's your responsibility
        to handle those exceptions if you want to. The one case that's handled is when
        the access token has expired: in this case, the client will automatically handle
        the HTTP 400 status and renew the token.
        
        Note that the Client does not attempt to interpret the data supplied by OPS, so
        it's your responsibility to parse the XML or JSON payload for your own purpose.
        
        The following custom exceptions are raised for cases when OPS quotas are
        exceeded, they are all in the `epo_ops.exceptions` module and are subclasses of
        `requests.HTTPError`, and therefore offer the same behaviors:
        
        - IndividualQuotaPerHourExceeded
        - RegisteredQuotaPerWeekExceeded
        
        Again, it's up to you to parse the response and decide what to do.
        
        Currently the Client knows how to issue request for the following services:
        
        | Client method                                                                 | API end point         | throttle  |
        | ----------------------------------------------------------------------------- | --------------------- | --------- |
        | `family(reference_type, input, endpoint=None, constituents=None)`             | family                | inpadoc   |
        | `image(path, range=1, extension='tiff')`                                      | published-data/images | images    |
        | `number(reference_type, input, output_format)`                                | number-service        | other     |
        | `published_data(reference_type, input, endpoint='biblio', constituents=None)` | published-data        | retrieval |
        | `published_data_search(cql, range_begin=1, range_end=25, constituents=None)`  | published-data/search | search    |
        | `register(reference_type, input, constituents=['biblio'])`                    | register              | other     |
        | `register_search(cql, range_begin=1, range_end=25)`                           | register/search       | other     |
        | `register_search(cql, range_begin=1, range_end=25)`                           | register/search       | other     |
        
        Bulk operations can be achieved by passing a list of valid models to the
        published_data input field.
        
        See the [OPS guide][] or use the [Developer's Area][] for more information on
        how to use each service.
        
        Please submit pull requests for the following services by enhancing the
        `epo_ops.api.Client` class:
        
        - Legal service
        
        ### Middleware
        
        All requests and responses are passed through each middleware object listed in
        `client.middlewares`. Requests are processed in the order listed, and responses
        are processed in the _reverse_ order.
        
        Each middleware should subclass `middlewares.Middleware` and implement the
        `process_request` and `process_response` methods.
        
        There are two middleware classes out of the box: Throttler and Dogpile.
        Throttler is in charge of the OPS throttling rules and will delay requests
        accordingly. Dogpile is an optional cache which will cache all HTTP status 200,
        404, 405, and 413 responses.
        
        By default, only the Throttler middleware is enabled, if you want to enable
        caching:
        
        ```python
        import epo_ops
        
        middlewares = [
            epo_ops.middlewares.Dogpile(),
            epo_ops.middlewares.Throttler(),
        ]
        client = epo_ops.Client(
            key='key',
            secret='secret',
            middlewares=middlewares,
        )
        ```
        
        _Note that caching middleware should be first in most cases._
        
        #### Dogpile
        
        Dogpile is based on (surprise) [dogpile.cache][]. By default it is instantiated
        with a DBMBackend region with timeout of 2 weeks.
        
        Dogpile takes three optional instantiation parameters:
        
        - `region`: You can pass whatever valid [dogpile.cache Region][] you want to
          backend the cache
        - `kwargs_handlers`: A list of keyword argument handlers, which it will use to
          process the kwargs passed to the request object in order to extract elements
          for generating the cache key. Currently one handler is implemented (and
          instantiated by default) to make sure that the range request header is part of
          the cache key.
        - `http_status_codes`: A list of HTTP status codes that you would like to have
          cached. By default 200, 404, 405, and 413 responses are cached.
        
        **Note**: dogpile.cache is not installed by default, if you want to use it, `pip install dogpile.cache` in your project.
        
        #### Throttler
        
        Throttler contains all the logic for handling different throttling scenarios.
        Since OPS throttling is based on a one minute rolling window, we must persist
        historical (at least for the past minute) throtting data in order to know what
        the proper request frequency is. Each Throttler must be instantiated with a
        Storage object.
        
        ##### Storage
        
        The Storage object is responsible for:
        
        1.  Knowing how to update the historical record with each request
            (`Storage.update()`), making sure to observe the one minute rolling window
            rule.
        2.  Calculating how long to wait before issuing the next request
            (`Storage.delay_for()`).
        
        Currently the only Storage backend provided is SQLite, but you can easily write
        your own Storage backend (such as file, Redis, etc.). To use a custom Storage
        type, just pass the Storage object when you're instantiating a Throttler object.
        See `epo_ops.middlewares.throttle.storages.Storage` for more implementation
        details.
        
        ---
        
        ## Tests
        
        Tests are written using [pytest][]. To run the tests:
        
        1.  [Register a OPS user login with EPO][ops registration]
        2.  Create an app
        3.  Look up the Mock Server URL at [Apiary][apiary ops]
        4.  Set the `APIARY_URL`, `OPS_KEY`, and `OPS_SECRET` environment variables
            accordingly
        5.  `make test`
        
        The tests must be run with a working internet connection, since both OPS and the
        [mock Apiary services][apiary ops] are online.
        
        [apache license]: http://www.apache.org/licenses/LICENSE-2.0
        [apiary ops]: http://docs.opsv31.apiary.io
        [developer's area]: https://developers.epo.org/ops-v3-2/apis
        [epo]: http://epo.org
        [ops guide]: http://documents.epo.org/projects/babylon/eponet.nsf/0/F3ECDCC915C9BCD8C1258060003AA712/$FILE/ops_v3.2_documentation%20_version_1.3.4_en.pdf
        [ops registration]: https://developers.epo.org/user/register
        [ops]: http://www.epo.org/searching/free/ops.html
        [requests]: http://requests.readthedocs.org/en/latest/
        [dogpile.cache region]: http://dogpilecache.readthedocs.org/en/latest/api.html#module-dogpile.cache.region
        [dogpile.cache]: https://bitbucket.org/zzzeek/dogpile.cache
        [pytest]: http://pytest.org/latest/
        [requests.response]: http://requests.readthedocs.org/en/latest/user/advanced/#request-and-response-objects
        
        # Release History
        
        ## 3.1.0 (2019-10-27)
        
        - Add support for bulk retrieval, thanks to [mmath][]
        
        ## 3.0.0 (2019-10-27)
        
        - Drop support for PyPy, Python 3.4 (probably still works)
        - Add support for Python 3.7, 3.8
        - Invalid and expired tokens are now treated the same, since OPS doesn't
          distinguish between the two use cases.
        
        ## 2.3.2 (2018-01-15)
        
        - Bug fix: Cache 4xx results as well, thanks to [amotl][]
        
        ## 2.3.1 (2017-11-10)
        
        - Bug fix: explicitly declare content-type during request
        
        ## 2.3.0 (2017-10-22)
        
        - Drop support for Python 2.6
        - Officially support Python 3.6
        - Update to latest dependencies
        - Add image retrieval service, thanks to [rfaga][]
        
        ## 2.2.0 (2017-03-30)
        
        - EPO OPS v3.2 compatibility, thanks to [eltermann][]
        
        ## 2.1.0 (2016-02-21)
        
        - Add number service, thanks to [eltermann][]
        
        ## 2.0.0 (2015-12-11)
        
        - Dropping support for Python 3.3 (although it probably still works).
        - Update to latest dependencies, no new features.
        
        ## 1.0.0 (2015-09-20)
        
        - Allow no middleware to be specified
        - Minor tweaks to development infrastructure, no new features.
        - This has been working for a while now, let's call it 1.0!
        
        ## 0.1.9 (2015-07-21)
        
        - No new features, just updating third party dependencies
        
        ## 0.1.8 (2015-01-24)
        
        - No new features, just updating third party dependencies
        
        ## 0.1.7 (2015-01-24)
        
        - Created default Dogpile DBM path if it doesn't exist
        
        ## 0.1.6 (2014-12-12)
        
        - Fixed bug with how service URL is constructed
        
        ## 0.1.5 (2014-10-17)
        
        - Added support for register retrieval and search
        
        ## 0.1.4 (2014-10-10)
        
        - Verified PyPy3 support
        - Updated various dependency pacakges
        
        ## 0.1.3 (2014-05-21)
        
        - Python 3.4 compatibility
        - Updated `requests` dependency to 2.3.0
        
        ## 0.1.2 (2014-03-04)
        
        - Python 2.6 and 3.3 compatibility
        
        ## 0.1.1 (2014-03-01)
        
        - Allow configuration of which HTTP responses (based on status code) to cache
        
        ## 0.1.0 (2014-02-20)
        
        - Introduced dogpile.cache for caching http200 resopnses
        - Introduced the concept of middleware
        
        ## 0.0.1 (2014-01-21)
        
        - Initial release
        
        [amotl]: https://github.com/amotl
        [eltermann]: https://github.com/eltermann
        [mmath]: https://github.com/mmath
        [rfaga]: https://github.com/rfaga
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
