Sickle 0.7.0
A lightweight OAI client library for Python
License: BSD
Keywords: oai oai-pmh

Sickle: OAI-PMH for Humans
==========================

.. image:: https://travis-ci.org/mloesch/sickle.svg?branch=master
    :target: https://travis-ci.org/mloesch/sickle
.. image:: https://img.shields.io/pypi/v/Sickle.svg
    :target: https://pypi.python.org/pypi/Sickle
.. image:: https://img.shields.io/pypi/dm/sickle.svg
        :target: https://pypi.python.org/pypi/Sickle

Sickle is a lightweight `OAI-PMH <http://www.openarchives.org/OAI/openarchivesprotocol.html>`_
client library written in Python.  It has been designed for conveniently retrieving data from
OAI interfaces the Pythonic way::

    >>> from sickle import Sickle
    >>> sickle = Sickle('http://elis.da.ulcc.ac.uk/cgi/oai2')
    >>> records = sickle.ListRecords(metadataPrefix='oai_dc')
    >>> records.next()
    <Record oai:eprints.rclis.org:4088>

Features
--------

- Easy harvesting of OAI-compliant interfaces
- Support for all six OAI verbs
- Convenient object representations of OAI items (records, headers, sets, ...)
- Automatic de-serialization of Dublin Core-encoded metadata payloads to Python
  dictionaries
- Option for ignoring deleted items

Installation
------------

::

    pip install sickle

Dependencies:

* `requests <http://docs.python-requests.org/en/latest/>`_
* `lxml <http://lxml.de/>`_


Documentation
-------------

Documentation is available at `Read the Docs <https://sickle.readthedocs.org/en/latest/>`_

Development
-----------

* `Sickle @ GitHub <https://github.com/mloesch/sickle>`_


Changelog
=========

Version 0.7.0
-------------

May 17, 2020

- method for record metadata extraction has been extracted (``Record.get_metadata()``) to make subclassing easier
  (https://github.com/mloesch/sickle/pull/38)
- retryable HTTP status codes and default wait time between retries can be customized (https://github.com/mloesch/sickle/issues/21 https://github.com/mloesch/sickle/pull/41)
- retry logic has been fixed: ``max_retries`` parameter now refers to no. of retries, not counting the initial request anymore
- the default number of HTTP retries has been set to 0 (= no retries)
- fix for https://github.com/mloesch/sickle/pull/39

Version 0.6.5
-------------

January 12, 2020

- fix: repr methods where causing an exception on Python 3 (https://github.com/mloesch/sickle/issues/30)


Version 0.6.4
-------------

October 2, 2018

- fix: resumption token with empty body indicates last response (https://github.com/mloesch/sickle/issues/25)


Version 0.6.3
-------------

April 8, 2018

- fix unicode problems (issues 20 & 22)


Version 0.6.2
-------------

August 11, 2017

- missing datestamp and identifier elements in record header don't break harvesting
- lxml resolve_entities disabled (http://lxml.de/FAQ.html#how-do-i-use-lxml-safely-as-a-web-service-endpoint)


Version 0.6.1
-------------

November 13, 2016

- it is now possible to pass any keyword arguments to requests
- the encoding used to decode the server response can be overridden


Version 0.5
-----------

November 12, 2015

- support for Python 3
- consider resumption tokens with empty tag bodies


Version 0.4
-----------

May 31, 2015

- bug fix: resumptionToken parameter is exclusive
- added support for harvesting complete OAI-XML responses


Version 0.3
-----------

April 17, 2013

- added support for protected OAI interfaces (basic authentication)
- made class mapping for OAI elements configurable
- added options for HTTP timeout and max retries
- added handling of HTTP 503 responses


Version 0.2
-----------

February 26, 2013

- OAI items are now represented as their own classes instead of XML elements
- library raises OAI-specific exceptions
- made lxml a required dependency


Version 0.1
-----------

February 20, 2013

First public release.