pysparql-anything 0.9.0.1

The SPARQL Anything Python library.

PySPARQL Anything

The SPARQL Anything Python Library

Table of Contents

1. User Guide
   1. Installation
   2. Basic Usage
   3. Keyword Arguments
2. API
   1. Methods
3. Development and Maintanance
   1. Building PySPARQL Anything
   2. SPARQL Anything Updates

1. USER GUIDE

1.1. INSTALLATION

To install PySPARQL Anything on your machine type the following in your command prompt:

$ pip install pysparql-anything 

To remove PySPARQL Anything from your machine, do the following.

In your command prompt execute

$ python
>>> import pysparql_anything as sa
>>> sa.utilities.remove_sparql_anything()
>>> exit()
$ pip uninstall pysparql-anything

1.2. BASIC USAGE

1. Open the command prompt with the current working directory set to the main folder of a SPARQL Anything project.

2. Launch Python:

$ python 

3. Import PySPARQL Anything:

>>> import pysparql_anything as sa

If the SPARQL Anything jar isn't installed in the API's folder it will now be downloaded there automatically.

4. Initialise a pysparql_anything.sparql_anything.SparqlAnything object:

>>> engine = sa.SparqlAnything()

5. Run the query:

>>> engine.run(**kwargs)

1.3. KEYWORD ARGUMENTS

The keyword arguments to be passed to any of the PySPARQL Anything methods are the same as those of the regular SPARQL Anything CLI (See here for more info).

For example:

>>> engine.run(q='queries/getFacade.sparql', f='TTL', o='C:/Users/Marco/Desktop/facade.ttl')

All of the keyword arguments except for v must be assigned a string literal.

v requires to be assigned a Python dictionary, as in the following example.

To execute the following query from the SPARQL Anything MusicXML showcase,

java -jar sparql-anything-0.8.0-SNAPSHOT.jar -q queries/populateOntology.sparql -v filePath="./musicXMLFiles/AltDeu10/AltDeu10-017.musicxml" -v fileName="AltDeu10-017" -f TTL

with PySPARQL Anything, do

>>> engine.run(
    	q='queries/populateOntology.sparql',
    	f='ttl',
    	v={
            'filePath' : './musicXMLFiles/AltDeu10/AltDeu10-017.musicxml',
            'fileName' : 'AltDeu10-017'
    	}
    )

The currently supported arguments are as follows.

 q: str - The path to the file storing the query to execute or the query itself.

 o: str - OPTIONAL - The path to the output file. [Default: STDOUT]

 l: str - OPTIONAL - The path to one RDF file or a folder including a set of
          files to be loaded. When present, the data is loaded in memory and
          the query executed against it.

 f: str - OPTIONAL -  Format of the output file. Supported values: JSON, XML,
          CSV, TEXT, TTL, NT, NQ. [Default:TEXT or TTL]

 v: dict[str, str] - OPTIONAL - Values passed as input parameter to a query template.
                     When by substituting variable names with the values provided.
                     The argument can be used in two ways:
                     (1) Providing a single SPARQL ResultSet file. In this case,
                     the query is executed for each set of bindings in the input result set.
                     Only 1 file is allowed.
                     (2) Named variable bindings: the argument value must follow the syntax:
                     var_name=var_value. The argument can be passed multiple times and
                     the query repeated for each set of values.

2. API

All of PySPARQL Anything functionalities can be accessed via the following four methods of the class pysparql_anything.sparql_anything.SparqlAnything.

The constructor for this class is

pysparql_anything.SparqlAnything(*jvm_options: str) -> pysparql_anything.sparql_anything.SparqlAnything

where *jvm_options are the optional string arguments representing the user's preferred JVM options.

As an example, one may have

engine = sa.SparqlAnything('-Xrs', '-Xmx6g')

NOTE: the *jvm_options are final. Once they are set they cannot be changed without starting a new process. This limitation is unfortunately due to the nature of the interaction between the JVM and the Python environment. Please see #6 for more information on this issue.

2.1. METHODS

SparqlAnything.run(**kwargs) -> None

Reflects the functionalities of the original SPARQL Anything CLI. This can be used to run a query the output of which is to be printed on the command line or saved to a file. (See example above)

SparqlAnything.ask(**kwargs) -> bool

Executes an ASK query and returns a Python boolean True or False.

SparqlAnything.construct(**kwargs) -> rdflib.graph.Graph

Executes a CONSTRUCT query and returns a rdflib graph object.

SparqlAnything.select(**kwargs) -> dict

Executes a SELECT query and returns the result as a Python dictionary.

3. DEVELOPMENT AND MAINTAINANCE

3.1. Building PySPARQL Anything

To build the source distribution and binary distribution we proceed as follows.

First, the tools we require are build as the build frontend, hatch as the build backend and twine to upload the distribution files to PyPI.

All of these can be installed via pip install x if required.

Once the tools are ready, the build metadata can be configured in the pyproject.toml file.

NOTE: it is not needed to amend anything in this file for versioning the software, as this is set dynamically (see below for how to perform this).

After the build metadata has been defined, one can proceed to build the distribution archives.

To do this, open the command prompt on the directory containing the pyproject.toml file and run

py -m build

This command should output a lot of text and once completed should generate a dist directory containing two files:

dist/
├── pysparql_anything-0.8.1.2-py3-none-any.whl
└── pysparql_anything-0.8.1.2.tar.gz

for example. Here the tar.gz file is a source distribution whereas the .whl file is a binary distribution.

To upload the distributions one does

twine upload dist/*

and enter the relevant PyPI credentials for this project.

3.2. SPARQL Anything Updates

Each version of PySPARQL Anything is tied to a released version of SPARQL Anything. Therefore, when a new version of the latter is released a new release of PySPARQL Anything should follow.

Assuming that there are no changes in the entry point of SPARQL Anyhing, this process simply involves updating the __about__.py module of the source code. To do this, set the __version__ and __SparqlAnything__ variables to the new values following the given structure.

As an example, to update from v0.8.1 to v0.8.2 of SPARQL Anything, we would have

# PySPARQL Anything version variable
__version__ = '0.8.1.2'  # --> '0.8.2.1'  # PySPARQL version for the build process.

# SPARQL Anything metadata
__SparqlAnything__ = 'v0.8.1'  # --> 'v0.8.2'  # Downloads v0.8.2 of SPARQL Anything.
__uri__ = 'SPARQL-Anything/sparql.anything'  # Software's GitHub URI.

After this build the new distribution files and upload them to PyPI.