The SPARQL Anything Python library.
Project description
PySPARQL Anything
The SPARQL Anything Python Library
Table of Contents
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
-
Open the command prompt with the current working directory set to the main folder of a SPARQL Anything project.
-
Launch Python:
$ python
- 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.
- Initialise a
pysparql_anything.sparql_anything.SparqlAnything
object:
>>> engine = sa.SparqlAnything()
- 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.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pysparql_anything-0.9.0.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5295c17b64f95aa3fe7cab8a5756ca776266d13224e3ec4a264ba6bc5c94ea73 |
|
MD5 | 0a9681a0316805dde460b24533e979b3 |
|
BLAKE2b-256 | dfecc47d4415f9e2495775e93322e4d78e7aee0adf8e70617bf00fda91b0f350 |
Hashes for pysparql_anything-0.9.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1f109fb208b65f25b144053995a82cffafc4365c8e08b2ee1f74a700ae1bc50a |
|
MD5 | 0e67e75786d6a5f155bdd936ee07c51e |
|
BLAKE2b-256 | f9b98653b1c9bbeadcbb9c4d6bc2556d04f6f3b1e18e94025051a62020a89650 |