# PySPARQL Anything
###### The SPARQL Anything Python Library
## Table of Contents
1. [User Guide](#user_guide)
1. [Installation](#installation)
2. [Basic Usage](#basic_usage)
3. [Keyword Arguments](#kwargs)
2. [API](#api)
1. [Methods](#methods)
3. [Development and Maintanance](#dev_guide)
1. [Building PySPARQL Anything](#build)
2. [SPARQL Anything Updates](#sa_updates)
## 1. USER GUIDE <a name="user_guide"></a>
### 1.1. INSTALLATION <a name="installation"></a>
To install PySPARQL Anything on your machine type the following in your command prompt:
```powershell
$ pip install pysparql-anything
```
To remove PySPARQL Anything from your machine, do the following.
In your command prompt execute
```python
$ python
>>> import pysparql_anything as sa
>>> sa.utilities.remove_sparql_anything()
>>> exit()
$ pip uninstall pysparql-anything
```
### 1.2. BASIC USAGE <a name="basic_usage"></a>
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:
```python
>>> 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:
```python
>>> engine = sa.SparqlAnything()
```
5) Run the query:
```python
>>> engine.run(**kwargs)
```
### 1.3. KEYWORD ARGUMENTS <a name="kwargs"></a>
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](https://github.com/SPARQL-Anything/sparql.anything#command-line-interface-cli) for more info).
For example:
```python
>>> 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,
```powershell
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
```python
>>> 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 <a name="api"></a>
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
``` python
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
```python
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](https://github.com/SPARQL-Anything/PySPARQL-Anything/issues/6) for more information on this issue.
### 2.1. METHODS <a name="methods"></a>
``` python
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)
```python
SparqlAnything.ask(**kwargs) -> bool
```
Executes an ASK query and returns a Python boolean True or False.
```python
SparqlAnything.construct(**kwargs) -> rdflib.graph.Graph
```
Executes a CONSTRUCT query and returns a rdflib graph object.
```python
SparqlAnything.select(**kwargs) -> dict
```
Executes a SELECT query and returns the result as a Python dictionary.
## 3. DEVELOPMENT AND MAINTAINANCE <a name="dev_guide"></a>
### 3.1. Building PySPARQL Anything <a name="build"></a>
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
```powershell
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
```powershell
twine upload dist/*
```
and enter the relevant PyPI credentials for this project.
### 3.2. SPARQL Anything Updates <a name="sa_updates"></a>
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
```python
# 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.
Raw data
{
"_id": null,
"home_page": "",
"name": "pysparql-anything",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "RDF,SPARQL,knowledge graphs,linked data,rdflib,sematic web",
"author": "",
"author_email": "Marco Ratta <marco.ratta@open.ac.uk>, Enrico Daga <enrico.daga@open.ac.uk>",
"download_url": "https://files.pythonhosted.org/packages/df/ec/c47d4415f9e2495775e93322e4d78e7aee0adf8e70617bf00fda91b0f350/pysparql_anything-0.9.0.1.tar.gz",
"platform": null,
"description": "# PySPARQL Anything\n###### The SPARQL Anything Python Library\n\n## Table of Contents\n1. [User Guide](#user_guide)\n 1. [Installation](#installation)\n 2. [Basic Usage](#basic_usage)\n 3. [Keyword Arguments](#kwargs)\n2. [API](#api)\n 1. [Methods](#methods)\n3. [Development and Maintanance](#dev_guide)\n 1. [Building PySPARQL Anything](#build)\n 2. [SPARQL Anything Updates](#sa_updates)\n \n## 1. USER GUIDE <a name=\"user_guide\"></a>\n\n### 1.1. INSTALLATION <a name=\"installation\"></a>\n\nTo install PySPARQL Anything on your machine type the following in your command prompt:\n```powershell\n$ pip install pysparql-anything \n```\n\nTo remove PySPARQL Anything from your machine, do the following.\n\nIn your command prompt execute\n```python\n$ python\n>>> import pysparql_anything as sa\n>>> sa.utilities.remove_sparql_anything()\n>>> exit()\n$ pip uninstall pysparql-anything\n```\n\n### 1.2. BASIC USAGE <a name=\"basic_usage\"></a>\n\n1) Open the command prompt with the current working directory set to the main folder of a SPARQL Anything project.\n\n2) Launch Python: \n```\n$ python \n```\n \n3) Import PySPARQL Anything: \n```python\n>>> import pysparql_anything as sa\n```\n\nIf the SPARQL Anything jar isn't installed in the API's folder it will now be downloaded there automatically.\n\n4) Initialise a ```pysparql_anything.sparql_anything.SparqlAnything``` object:\n```python\n>>> engine = sa.SparqlAnything()\n```\n\n5) Run the query:\n```python\n>>> engine.run(**kwargs)\n```\n\n### 1.3. KEYWORD ARGUMENTS <a name=\"kwargs\"></a>\n\nThe 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](https://github.com/SPARQL-Anything/sparql.anything#command-line-interface-cli) for more info).\n\nFor example:\n```python\n>>> engine.run(q='queries/getFacade.sparql', f='TTL', o='C:/Users/Marco/Desktop/facade.ttl')\n```\n\nAll of the keyword arguments except for ```v``` must be assigned a string literal. \n\n```v``` requires to be assigned a Python dictionary, as in the following example.\n\nTo execute the following query from the SPARQL Anything MusicXML showcase,\n```powershell\njava -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\n```\n\nwith PySPARQL Anything, do\n```python\n>>> engine.run(\n \tq='queries/populateOntology.sparql',\n \tf='ttl',\n \tv={\n 'filePath' : './musicXMLFiles/AltDeu10/AltDeu10-017.musicxml',\n 'fileName' : 'AltDeu10-017'\n \t}\n )\n```\n\nThe currently supported arguments are as follows.\n\n```\n q: str - The path to the file storing the query to execute or the query itself.\n\n o: str - OPTIONAL - The path to the output file. [Default: STDOUT]\n\n l: str - OPTIONAL - The path to one RDF file or a folder including a set of\n files to be loaded. When present, the data is loaded in memory and\n the query executed against it.\n\n f: str - OPTIONAL - Format of the output file. Supported values: JSON, XML,\n CSV, TEXT, TTL, NT, NQ. [Default:TEXT or TTL]\n\n v: dict[str, str] - OPTIONAL - Values passed as input parameter to a query template.\n When by substituting variable names with the values provided.\n The argument can be used in two ways:\n (1) Providing a single SPARQL ResultSet file. In this case,\n the query is executed for each set of bindings in the input result set.\n Only 1 file is allowed.\n (2) Named variable bindings: the argument value must follow the syntax:\n var_name=var_value. The argument can be passed multiple times and\n the query repeated for each set of values.\n```\n\n## 2. API <a name=\"api\"></a>\n\nAll of PySPARQL Anything functionalities can be accessed via the following four methods of the class \n``` pysparql_anything.sparql_anything.SparqlAnything ```.\n\nThe constructor for this class is\n``` python\npysparql_anything.SparqlAnything(*jvm_options: str) -> pysparql_anything.sparql_anything.SparqlAnything\n```\nwhere ```*jvm_options``` are the optional string arguments representing the user's preferred JVM options.\n\nAs an example, one may have\n```python\nengine = sa.SparqlAnything('-Xrs', '-Xmx6g')\n```\nNOTE: the ```*jvm_options``` are final. Once they are set they cannot be changed without starting a new process.\nThis limitation is unfortunately due to the nature of the interaction between the JVM and the Python environment.\nPlease see [#6](https://github.com/SPARQL-Anything/PySPARQL-Anything/issues/6) for more information on this issue.\n\n### 2.1. METHODS <a name=\"methods\"></a>\n``` python\nSparqlAnything.run(**kwargs) -> None\n```\n\nReflects the functionalities of the original SPARQL Anything CLI. This can be used to run a query the output of\nwhich is to be printed on the command line or saved to a file. (See example above)\n\n```python\nSparqlAnything.ask(**kwargs) -> bool\n```\n\nExecutes an ASK query and returns a Python boolean True or False.\n\n```python\nSparqlAnything.construct(**kwargs) -> rdflib.graph.Graph\n```\n\nExecutes a CONSTRUCT query and returns a rdflib graph object.\n\n```python\nSparqlAnything.select(**kwargs) -> dict\n```\n\nExecutes a SELECT query and returns the result as a Python dictionary. \n\n## 3. DEVELOPMENT AND MAINTAINANCE <a name=\"dev_guide\"></a>\n\n### 3.1. Building PySPARQL Anything <a name=\"build\"></a>\n\nTo build the source distribution and binary distribution we proceed as follows. \n\nFirst, the tools we require are ```build``` as the build frontend, ```hatch``` as the build backend and ```twine``` to upload the distribution files to PyPI.\n\nAll of these can be installed via ```pip install x``` if required.\n\nOnce the tools are ready, the build metadata can be configured in the ```pyproject.toml``` file. \n\nNOTE: 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).\n\nAfter the build metadata has been defined, one can proceed to build the distribution archives.\n\nTo do this, open the command prompt on the directory containing the ```pyproject.toml``` file and run\n```powershell\npy -m build\n```\nThis command should output a lot of text and once completed should generate a ```dist``` directory containing two files:\n```\ndist/\n\u251c\u2500\u2500 pysparql_anything-0.8.1.2-py3-none-any.whl\n\u2514\u2500\u2500 pysparql_anything-0.8.1.2.tar.gz\n```\nfor example. Here the ```tar.gz``` file is a source distribution whereas the ```.whl``` file is a binary distribution.\n\nTo upload the distributions one does \n```powershell\ntwine upload dist/*\n```\nand enter the relevant PyPI credentials for this project. \n\n### 3.2. SPARQL Anything Updates <a name=\"sa_updates\"></a>\n\nEach 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. \n\nAssuming 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.\n\nAs an example, to update from ```v0.8.1``` to ```v0.8.2``` of SPARQL Anything, we would have\n```python\n# PySPARQL Anything version variable\n__version__ = '0.8.1.2' # --> '0.8.2.1' # PySPARQL version for the build process.\n\n# SPARQL Anything metadata\n__SparqlAnything__ = 'v0.8.1' # --> 'v0.8.2' # Downloads v0.8.2 of SPARQL Anything.\n__uri__ = 'SPARQL-Anything/sparql.anything' # Software's GitHub URI.\n```\nAfter this build the new distribution files and upload them to PyPI.\n",
"bugtrack_url": null,
"license": "",
"summary": "The SPARQL Anything Python library.",
"version": "0.9.0.1",
"project_urls": {
"Documentation": "https://github.com/SPARQL-Anything/PySPARQL-Anything/blob/main/README.md",
"Issues": "https://github.com/SPARQL-Anything/PySPARQL-Anything/issues",
"Source": "https://github.com/SPARQL-Anything/PySPARQL-Anything"
},
"split_keywords": [
"rdf",
"sparql",
"knowledge graphs",
"linked data",
"rdflib",
"sematic web"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f9b98653b1c9bbeadcbb9c4d6bc2556d04f6f3b1e18e94025051a62020a89650",
"md5": "0e67e75786d6a5f155bdd936ee07c51e",
"sha256": "1f109fb208b65f25b144053995a82cffafc4365c8e08b2ee1f74a700ae1bc50a"
},
"downloads": -1,
"filename": "pysparql_anything-0.9.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0e67e75786d6a5f155bdd936ee07c51e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 14798,
"upload_time": "2023-12-18T15:40:57",
"upload_time_iso_8601": "2023-12-18T15:40:57.595768Z",
"url": "https://files.pythonhosted.org/packages/f9/b9/8653b1c9bbeadcbb9c4d6bc2556d04f6f3b1e18e94025051a62020a89650/pysparql_anything-0.9.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dfecc47d4415f9e2495775e93322e4d78e7aee0adf8e70617bf00fda91b0f350",
"md5": "0a9681a0316805dde460b24533e979b3",
"sha256": "5295c17b64f95aa3fe7cab8a5756ca776266d13224e3ec4a264ba6bc5c94ea73"
},
"downloads": -1,
"filename": "pysparql_anything-0.9.0.1.tar.gz",
"has_sig": false,
"md5_digest": "0a9681a0316805dde460b24533e979b3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 44396,
"upload_time": "2023-12-18T15:40:58",
"upload_time_iso_8601": "2023-12-18T15:40:58.954337Z",
"url": "https://files.pythonhosted.org/packages/df/ec/c47d4415f9e2495775e93322e4d78e7aee0adf8e70617bf00fda91b0f350/pysparql_anything-0.9.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-18 15:40:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SPARQL-Anything",
"github_project": "PySPARQL-Anything",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pysparql-anything"
}
JSON
