Metadata-Version: 1.1
Name: python-epo-ops-client
Version: 2.2.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: Copyright 2015 Monozuku Inc.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

Download-URL: https://github.com/55minutes/python-epo-ops-client/archive/v2.2.0.tar.gz
Description: python-epo-ops-client
        =====================
        
        |PyPI version| |Build Status| |Coverage Status|
        
        python-epo-ops-client is an `Apache2 Licensed`_ client library for
        accessing the `European Patent Office`_'s ("EPO") `Open Patent
        Services`_ ("OPS") v.3.2 (based on `v 1.3.1 of the reference guide`_).
        
        .. code:: 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`_ 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,    | family                | inpadoc   |
        | constituents=None)``                              |                       |           |
        +---------------------------------------------------+-----------------------+-----------+
        | ``number(reference_type, input, output_format)``  | number-service        | other     |
        +---------------------------------------------------+-----------------------+-----------+
        | ``published_data(reference_type, input,           | published-data        | retrieval |
        | endpoint='biblio', constituents=None)``           |                       |           |
        +---------------------------------------------------+-----------------------+-----------+
        | ``published_data_search(cql, range_begin=1,       | published-data/search | search    |
        | range_end=25, constituents=None)``                |                       |           |
        +---------------------------------------------------+-----------------------+-----------+
        | ``register(reference_type, input,                 | register              | other     |
        | constituents=['biblio'])``                        |                       |           |
        +---------------------------------------------------+-----------------------+-----------+
        | ``register_search(cql, range_begin=1,             | register/search       | other     |
        | range_end=25)``                                   |                       |           |
        +---------------------------------------------------+-----------------------+-----------+
        | ``register_search(cql, range_begin=1,             | register/search       | other     |
        | range_end=25)``                                   |                       |           |
        +---------------------------------------------------+-----------------------+-----------+
        
        See the `OPS guide`_ 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
        -  Images retrieval
        -  Bulk operations
        
        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:
        
        .. code:: 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`_
        2. Create an app
        3. Look up the Mock Server URL at `Apiary`_
        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`_ are online.
        
        .. _Apache2 Licensed: http://www.apache.org/licenses/LICENSE-2.0
        .. _European Patent Office: http://epo.org
        .. _Open Patent Services: http://www.epo.org/searching/free/ops.html
        .. _v 1.3.1 of the reference guide: http://documents.epo.org/projects/babylon/eponet.nsf/0/F3ECDCC915C9BCD8C1258060003AA712/$File/ops_v3_2_documentation_version_1_3_1_en.pdf
        .. _requests.Response: http://requests.readthedocs.org/en/latest/user/advanced/#request-and-response-objects
        .. _OPS guide: http://documents.epo.org/projects/babylon/eponet.nsf/0/F3ECDCC915C9BCD8C1258060003AA712/$File/ops_v3_2_documentation_version_1_3_1_en.pdf
        .. _dogpile.cache: https://bitbucket.org/zzzeek/dogpile.cache
        .. _dogpile.cache Region: http://dogpilecache.readthedocs.org/en/latest/api.html#module-dogpile.cache.region
        .. _pytest: http://pytest.org/latest/
        .. _Register a OPS user login with EPO: https://developers.epo.org/user/register
        .. _Apiary: http://docs.opsv31.apiary.io
        .. _mock Apiary services: http://docs.opsv31.apiary.io
        
        .. |PyPI version| image:: http://img.shields.io/pypi/v/python-epo-ops-client.svg
           :target: https://pypi.python.org/pypi/python-epo-ops-client
        .. |Build Status| image:: http://img.shields.io/travis/55minutes/python-epo-ops-client.svg
           :target: https://travis-ci.org/55minutes/python-epo-ops-client
        .. |Coverage Status| image:: http://img.shields.io/coveralls/55minutes/python-epo-ops-client.svg
           :target: https://coveralls.io/r/55minutes/python-epo-ops-client
        
        
        Release History
        ===============
        
        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
        
        .. _eltermann: https://github.com/eltermann
        
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.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
