Metadata-Version: 2.1
Name: sparql-client
Version: 3.7
Summary: Python API to query a SPARQL endpoint
Home-page: https://github.com/eea/sparql-client
Author: European Environment Agency: IDM2 A-Team
Author-email: eea-edw-a-team-alerts@googlegroups.com
License: MPL
Description: **************************
        SPARQL HTTP client library
        **************************
        .. image:: https://ci.eionet.europa.eu/buildStatus/icon?job=eea/sparql-client/develop
          :target: https://ci.eionet.europa.eu/job/eea/job/sparql-client/job/develop/display/redirect
          :alt: develop
        .. image:: https://ci.eionet.europa.eu/buildStatus/icon?job=eea/sparql-client/master
          :target: https://ci.eionet.europa.eu/job/eea/job/sparql-client/job/master/display/redirect
          :alt: master
        .. image:: https://img.shields.io/github/v/release/eea/sparql-client
          :target: https://eggrepo.eea.europa.eu/d/sparql-client/
          :alt: Release
          
        `sparql-client` is a SPARQL query library that performs SELECT and ASK queries against a SPARQL endpoint via HTTP.
        It will automatically convert literals to the coresponding Python types.
        
        API based on SPARQL_JavaScript_Library_  by Lee Feigenbaum and Elias Torres. Heavy influence from Juan Manuel Caicedo’s SPARQL library.
        
        .. _SPARQL_JavaScript_Library: https://web.archive.org/web/20120518014957/http://www.thefigtrees.net/lee/sw/sparql.js
        
        API
        ---
        
        First you open a connection to the endpoint::
        
            s = sparql.Service(endpoint, "utf-8", "GET")
        
        Then you make the query::
        
            result = s.query(statement)
        
        If you have made a SELECT query, then you can read the result with fetchone() or fetchall()::
        
            for row in result.fetchone():
        
        If you have made an ASK query, then you can read the result (a boolean value) with hasresult():
        
            works = result.hasresult()
        
        
        How it works
        ------------
        
        >>> import sparql
        
        >>> q = ('SELECT DISTINCT ?station, ?orbits WHERE { '
        ...      '?station a <http://dbpedia.org/ontology/SpaceStation> . '
        ...      '?station <http://dbpedia.org/property/orbits> ?orbits . '
        ...      'FILTER(?orbits > 50000) } ORDER BY DESC(?orbits)')
        >>> result = sparql.query('http://dbpedia.org/sparql', q)
        
        >>> result.variables
        [u'station', u'orbits']
        
        >>> for row in result:
        ...     print 'row:', row
        ...     values = sparql.unpack_row(row)
        ...     print values[0], "-", values[1], "orbits"
        row: (<IRI <http://dbpedia.org/resource/Mir>>, <Literal "86331"^^<http://www.w3.org/2001/XMLSchema#int>>)
        http://dbpedia.org/resource/Mir - 86331 orbits
        row: (<IRI <http://dbpedia.org/resource/Salyut_7>>, <Literal "51917"^^<http://www.w3.org/2001/XMLSchema#int>>)
        http://dbpedia.org/resource/Salyut_7 - 51917 orbits
        
        sparql module
        -------------
        
        The ``sparql`` module can be invoked in several different ways. To quickly run a query use ``query()``. Results are encapsulated in a ``_ResultsParser`` instance:
        
        >>> result = sparql.query(endpoint, query)
        >>> for row in result:
        >>>    print row
        
        Command-line use
        ================
        
        >>> sparql.py [-i] endpoint
            -i Interactive mode
        
        If interactive mode is enabled, the program reads queries from the console and then executes them. Use a double line (two ‘enters’) to separate queries.
        Otherwise, the query is read from standard input.
        
        RDF wrapper classes
        ===================
        
        class sparql.RDFTerm
        Super class containing methods to override. ``sparql.IRI``, ``sparql.Literal`` and ``sparql.BlankNode`` all inherit from ``sparql.RDFTerm``.
        
        ``n3()``
        
        Return a Notation3 representation of this term.
        
        ``class sparql.IRI(value)``
        
        An RDF resource.
        
        ``class sparql.Literal(value, datatype=None, lang=None)``
        
        Literals. These can take a data type or a language code.
        
        ``class sparql.BlankNode(value)``
        
        Blank node. Similar to IRI but lacks a stable identifier.
        
        Query utilities
        
        ``class sparql.Service(endpoint, qs_encoding='utf-8')``
        
        This is the main entry to the library. The user creates a Service, then sends a query to it. If we want to have persistent connections, then open them here.
        
        ``class sparql._ResultsParser(fp)``
        
        Parse the XML result.
        
        ``__iter__()``
        
        Synonim for fetchone().
        
        ``fetchall()``
        
        Loop through the result to build up a list of all rows. Patterned after DB-API 2.0.
        
        ``fetchone()``
        
        Fetches the next set of rows of a query result, returning a list. An empty list is returned when no more rows are available. If the query was an ASK request, then an empty list is returned as there are no rows available.
        
        ``hasresult()``
        
        ASK queries are used to test if a query would have a result. If the query is an ASK query there won’t be an actual result, and fetchone() will return nothing. Instead, this method can be called to check the result from the ASK query.
        
        If the query is a SELECT statement, then the return value of hasresult() is None, as the XML result format doesn’t tell you if there are any rows in the result until you have read the first one.
        
        ``sparql.parse_n3_term(src)``
        
        Parse a Notation3 value into a RDFTerm object (IRI or Literal).
        
        This parser understands IRIs and quoted strings; basic non-string types (integers, decimals, booleans, etc) are not supported yet.
        
        ``sparql.unpack_row(row, convert=None, convert_type={})``
        
        Convert values in the given row from RDFTerm objects to plain Python values: IRI is converted to a unicode string containing the IRI value; BlankNode is converted to a unicode string with the BNode’s identifier, and Literal is converted based on its XSD datatype.
        
        The library knows about common XSD types (STRING becomes unicode, INTEGER and LONG become int, DOUBLE and FLOAT become float, DECIMAL becomes Decimal, BOOLEAN becomes bool). If the python-dateutil library is found, then DATE, TIME and DATETIME are converted to date, time and datetime respectively. For other conversions, an extra argument convert may be passed. It should be a callable accepting two arguments: the serialized value as a unicode object, and the XSD datatype.
        
        ``sparql.query(endpoint, query)``
        
        Convenient method to execute a query. Exactly equivalent to:
        
        ``sparql.Service(endpoint).query(query)``
        
        Conversion of data types
        ------------------------
        
        The library will automatically convert typed literals to a coresponding
        simple type in Python. Dates are also converted if the dateutil_ library is
        available.
        
        .. _dateutil: http://labix.org/python-dateutil
        
        
        Running the unit tests
        ----------------------
        
        If you have nose_ installed, just run ``nosetests`` in the top-level directory.
        Some tests require the python-dateutil_ (version 1.5) or mock_ libraries.
        Tested under Python 2.4 through 2.7.
        
        .. _nose: http://somethingaboutorange.com/mrl/projects/nose/
        .. _python-dateutil: http://niemeyer.net/python-dateutil
        .. _mock: http://www.voidspace.org.uk/python/mock/
        
        Installing sparql-client
        ------------------------
        
        The ``sparql-client`` library is available from PyPI and has no dependencies. Installation is as simple as:
        
            pip install sparql-client
        
        We recommend also instlaling ``python-dateutil``, to enable parsing of dates and times from query results
        
        License
        -------
        The contents of this package are subject to the Mozilla Public
        License Version 1.1 (the "License"); you may not use this package
        except in compliance with the License. You may obtain a copy of
        the License at http://www.mozilla.org/MPL/
        
        Software distributed under the License is distributed on an "AS
        IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
        implied. See the License for the specific language governing
        rights and limitations under the License.
        
        The Original Code is SPARQL client version 1.0.
        
        The Initial Owner of the Original Code is European Environment
        Agency (EEA). Portions created by Eau de Web for EEA are
        Copyright (C) European Environment Agency. All Rights Reserved.
        
        
        Authors
        -------
        * Søren Roug, EEA
        * Alex Morega, Eau de Web
        
        
        Changelog
        =========
        
        3.7 - (2020-06-17)
        ---------------------------
        * Feature: added the documentation originally found under eionet.euripa.eu
          [alecghica refs #111217]
        
        3.6 - (2020-03-03)
        ---------------------------
        * Change: Add jenkins badge
          [valentinab25]
        
        3.5 - (2020-02-26)
        --------------------------
        * Feature: merged source code so it now works on both Python 2 and Python 3
          [alecghica refs #110159]
        * Feature: updated Jenkins pipeline
          [alecghica refs #110159]
        
        3.4 - (2019-01-28)
        --------------------------
        * Jenkins: Add sonarqube step
          [avoinea refs #101552]
        
        3.3 - (2018-12-11)
        --------------------------
        * Feature: when building the request from an endpoint that followed redirects
          the query works fine now
          [alecghica refs #100666]
        
        3.2 - (2018-06-22)
        -----------------------
        * Change: updated URLs pointing to eea.europa.eu with https://
          [alecghica refs #95849]
        
        3.1 - (2017-12-12)
        ------------------
        * Change: Replace eeacms/zptlint with eeacms/plone-test:4 zptlint
          [avoinea refs #90415]
        
        3.0 - (2017-11-14)
        ------------------
        * Change: Added handler for SAXParseException and wrote a test in order to
          cover this exception
          [petchesi-iulian refs #88573]
        
        2.9 - (2017-09-29)
        ------------------
        * Change: Changed the projects tests structure in order to make the tests work
          [petchesi-iulian refs #88509]
        
        2.8 - (2017-08-16)
        ------------------
        * Change: Added sparql export method formats (xml, xmlschema, json) to be stored
          and retrieved from cache
          [zoltan_andras refs #86464]
        
        2.7 - (2017-04-24)
        ------------------
        * Change: updated package information
          [eduard-fironda]
        
        2.6 - (2016-10-04)
        ------------------
        * Change: added timeout parameter for _get_response
        
        2.5 - (2016-07-29)
        ------------------
        * Bug fix: Safely get __version__ from version.txt
          [voineali refs #74283]
        
        2.4 - (2016-07-29)
        ------------------
        * Bug fix: Read __version__ from version.txt
          [voineali refs #74283]
        
        2.3 - (2016-07-19)
        ------------------
        * Change: fixed changelog markup and removed __version__
          [alecghica refs #74151]
        
        2.2 - (2016-06-16)
        ------------------
        * Feature: Fix Comment in sparql queries
          [lucas refs #72876]
        
        2.1 - (2016-06-02)
        ------------------
        * Bug fix: Fix passing of method from service to query
        
        2.0 - (2016-04-18)
        ------------------
        * Bug fix: fixed error reporting when running query
          [alecghica refs #68990]
        
        1.9 - (2016-02-01)
        ------------------
        * Bug fix: fix timeout exception call now that we have moved to eventlet
          [ichim-david refs #17334]
        
        1.8 - (2015-10-05)
        ------------------
        * Bug fix: set socket timeout to prevent Zope instances hanging out when the external service is not responding
          [lucas refs #29063]
        
        1.7 - (2015-07-28)
        ------------------
        * Change: Replace pycurl2 with eventlet
          [david-batranu refs #25721]
        
        1.6 - (2014-09-15)
        ------------------
        * Feature: change the default query method from GET to POST.
          [pasoviul refs #20501]
        
        1.5 - (2013-11-21)
        ------------------
        * Feature: added "method" as a parameter for query() and now we can use
          either GET or POST methods
          [ghicaale refs #14491]
        
        1.4 - (2013-07-08)
        ------------------
        * Bug fix: Use a temporary file for parsing instead of using a huge string
          [szabozo0 refs #14826]
        
        1.3 - (2013-05-20)
        ------------------
        * Bug fix: fixed ReST merkup under HISTORY.txt
          [ghicaale refs #14554]
        
        1.2 - (2013-05-20)
        ------------------
        * Upgrade step:
           - install system dependency libcurl3-dev (Debian/Ubuntu) / curl-devel (CentOS)
           - [szabozo0 refs #14349]
        * Change: Use pycurl2 instead of pycurl
          [szabozo0 refs #14349]
        * Bug fix: Use pycurl instead of urllib2, added timeout functionality
          [szabozo0 refs #14349]
        
        1.1 - (2013-03-15)
        ------------------
        * Feature: Removed sparql error handling quickfix
          [szabozo0 refs #13705]
        
        1.0 - (2013-01-28)
        ------------------
        * Feature: Handle sparql errors
          [szabozo0 #9608]
        
        0.16 - (2013-01-15)
        -------------------
        * Bug fix: Strip the endpoint url
          [szabozo0]
        
        0.15 - (2013-01-10)
        -------------------
        * Packaging fix: inline contents of version.txt
          [moregale]
        
        0.14 - (2013-01-10)
        -------------------
        * Bug fix: updated History.txt
          [ghicaale]
        * Buf fix: unit test
          [moregale]
        
        0.13 - (2012-09-11)
        -------------------
        * Change: changed from HTTP POST to GET
          [roug]
        
        0.12 - (2012-09-11)
        -------------------
        * No changes
        
        0.11 - (2012-04-15)
        -------------------
        * Feature: added copyright message to sparql.py
          [roug]
        
        0.10 - (2012-03-05)
        -------------------
        * Feature: map the ``xsd:int`` type to Python's ``int``
          [moregale]
        
        0.9 - (2011-10-24)
        ------------------
        * Feature: new argument `convert_type` for `unpack_row`
          [moregale]
        
        0.8 - (2011-08-29)
        ------------------
        * First version available on PyPI
          [roug, moregale]
        
Keywords: Sparql Client
Platform: UNKNOWN
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/x-rst
Provides-Extra: test
