API Reference¶
This reference is organized to put the most important information first, both overall and within each section. You will mainly be working with implementations of the Endpoint object such as LocalEndpoint and RemoteEndpoint
Endpoints¶
-
class
gastrodon.
Endpoint
(prefixes: rdflib.graph.Graph = None, base_uri=None)[source]¶ An Endpoint is something which can answer SPARQL queries. Endpoint is an abstract base class and cannot be instantiated on its own. Current implementations include a
RemoteEndpoint
via the SPARQL protocol or aLocalEndpoint
provided by rdflib.Parameters: Core Methods
The select, construct, and update methods are the ones that you will use most often. All of these do SPARQL queries or SPARQL updates on the RDF Graph fronted by this Endpoint. If the endpoint is large or remote, these functions could consume an unlimited time.
-
select
(sparql: str, **kwargs) → pandas.core.frame.DataFrame[source]¶ Perform a SPARQL SELECT query against the endpoint. To make interactive queries easy in the Jupyter environment, any variable with a name beginning with an underscore (eg. ?_var or @_var) in the SPARQL query will be replaced with an RDF serialized version of the variable (eg. var) in the python stack frame of the caller.
If you call this in a Jupyter notebook, it sees all variables that are accessible from the cells in the notebook. If you call it inside a function definition, it sees variables local to that definition.
Parameters: - sparql – SPARQL SELECT query
- kwargs – any keyword arguments are implementation-dependent
Returns: SELECT result as a Pandas DataFrame
-
construct
(sparql: str, _user_frame=2, **kwargs)[source]¶ Perform a SPARQL CONSTRUCT query, making the same substitutions as the select method. Returns a Graph
Parameters: - sparql – SPARQL SELECT query
- kwargs – any keyword arguments are implementation-dependent
Returns: result as a Graph
-
update
(sparql: str, _user_frame=1, **kwargs) → None[source]¶ Performs a SPARQL update statement with the same substitutions as the select method
Parameters: - sparql – SPARQL update query, as a str
- _user_frame – Number of stack frames to look back to find variables; defaults to 1, which gets variables from the caller, 2 gets them from the caller of the caller and so forth
- kwargs – dependent on implementation
Returns: nothing
Graph Conversion Methods
Methods in this category convert between complex RDF structures inside the endpoint (eg. RDF Collections, a document record containing blank nodes) to Python data structures outside the endpoint (such Lists, Sets, Bags, Counters, Trees, and even rdflib Graphs)
-
decollect
(node)[source]¶ Parameters: node – a URIRef pointing to an rdf:Seq, rdf:Bag, or rdf:Alt Returns: a Python List, Counter, or Set of POPOs
Local Methods
These methods run quickly because they do not depend on the fronted RDF Graph; these are appropriate to use by callers such as apply methods and variants used in Pandas and similar software.
-
to_python
(term)[source]¶ Convert a simple rdflib term into a idiomatic Python object.
A simple rdflib term is entirely self-contained; either a literal value or a signifier (a Resource) floating in space, without consideration of other facts in the graph.
For RDF literals and blank nodes, behavior is exactly the same as the toPython method, which this encloses. URIReferences are wrapped in GastrodonURI objects which look like short names (QNames) inside Jupyter and Pandas, but remember the full URI if they are later used with Gastrodon.
This is a method of an Endpoint as opposed to a static method or method of a term wrapper because the exact resolution to a QName is relative to the namespaces defined for that Endpoint.
Parameters: term – an RDFLib Node object Returns: a Plain Ordinary Python Object except for URI References which are returned as GastrodonURI
-
namespaces
()[source]¶ Display prefix to namespace mapping.
Produces a Pandas DataFrame that looks something like this
prefix namespace bibo http://purl.org/ontology/bibo/
cc http://creativecommons.org/ns#
dbo http://dbpedia.org/ontology/
… … where prefix is the index of the dataframe so you can look up a namespace like
endpoint.namespaces().at['bibo','namespace']
Returns: pandas.DataFrame
describing the prefix to namespace mapping used for this endpoint
-
ns_part
(url)[source]¶ Given a URI like
http://purl.org/ontology/bibo/AcademicArticle
return the namespace part of the URI, which would be
http://purl.org/ontology/bibo/
This is based on the syntax of the URI, not the declared prefixes associated with this URI.
Parameters: url – URIRef or string URL Returns: namespace part of URL as string
-
local_part
(url)[source]¶ Given a URI like
http://purl.org/ontology/bibo/AcademicArticle
return the localname part of the URI, which would be
AcademicArticle
This is based on the syntax of the URI, not the declared prefixes associated with this URI.
Parameters: url – URIRef or string URL Returns: localname part of URL as string
-
short_name
(term)[source]¶ Assuming we’ve made the following namespace declaration on this endpoint,
@prefix bibo: <http://purl.org/ontology/bibo/>
and given a URI like
http://purl.org/ontology/bibo/AcademicArticle
this returns
bibo:AcademicArticle
which can be used as a QName relative to the Endpoint.
Parameters: term – URIRef which can be expressed with a QName Returns: the QName, as a string
-
is_ok_qname
(url)[source]¶ Many
URIRef
s can be resolved to a namespace and written as a short name (QName), except when special characters such as parenthesis and colon are in the localpart of the domain. In that case, theURIRef
should be rendered in RDF as an absolute URI (ex.<http://example.com/>
).Parameters: url – a URIRef or a str for a URL Returns: true if the URIRef can be safely resolved to a namespace in short form.
-
Endpoint Implementations¶
If you wish to use an Endpoint you must instantiate one of the following implementations.
-
class
gastrodon.
LocalEndpoint
(graph: rdflib.graph.Graph, prefixes: rdflib.graph.Graph = None)[source]¶ LocalEndpoint for doing queries against a local RDFLib graph.
Parameters: - graph – Graph object that will be encapsulated
- prefixes – Graph defining prefixes for this Endpoint, will be the same as the input graph by default
- base_uri – base_uri for resolving URLs
-
class
gastrodon.
RemoteEndpoint
(url: str, prefixes: rdflib.graph.Graph = None, user=None, passwd=None, http_auth=None, default_graph=None, base_uri=None)[source]¶ Represents a SPARQL endpoint available under the SPARQL Protocol.
Parameters: - url – String URL for the SPARQL endpoint
- prefixes – Graph containing prefix declarations for this endpoint
- http_auth – http authentication method (eg. “BASIC”, “DIGEST”)
- default_graph – str URL for default graph
- base_uri – str for base URI for purposes of name resolution
Supporting Classes and Functions¶
-
class
gastrodon.
QName
(name: str)[source]¶ This class represents a qualified name.
This class makes it easy to write qualified names, without ambiguity, in Python variables that later get substituted into SPARQL variables. If
@prefix bibo: <http://purl.org/ontology/bibo/>
is declared for an Endpoint, and one writes in Python
objectType=QName("bibo:AcademicPaper")
then the SPARQL variable
?_objectType
will be replaced with a URI Referemce<http://purl.org/ontology/bibo/AcademicPaper>
for queries inside the scope in which _objectType is local. Note that if you simply wrote
objectType="bibo:AcademicPaper"
the value substituted in SPARQL would be just the string
"bibo:AcademicPaper"
If one wants to write a URI Reference as a full URI, simply use the URIRef class from rdflib, ex.
objectType=URIRef("http://purl.org/ontology/bibo/AcademicPaper")
Parameters: name – qualified name of the form ‘prefix:localname’, such as ‘rdf:type’
-
gastrodon.
inline
(turtle)[source]¶ Convert turtle-format RDF into a Graph
Parameters: turtle – str in Turtle Format Returns: Graph with corresponding triples
-
gastrodon.
ttl
(g: rdflib.store.Store)[source]¶ Write out Graph (or other Store) in Turtle format to stdout.
Parameters: g – input Graph Returns: nothing
-
gastrodon.
one
(items)[source]¶ In cases where a composite object has only a single element, returns the element.
Element types currently supported are:
- DataFrame
- returns single element of a single row
- List (or object castable to list)
- returns only element of list
Parameters: items – a composite object Returns: only member of composite object, otherwise throw exception
-
gastrodon.
member
(index)[source]¶ Return URIRef that (as ?predicate) states that ?object is the index(th) member of ?subject.
Parameters: index – non-negative integer index: Returns: URIRef rdf:_N for N=index+1
Objects Created Only By Gastrodon¶
You probably could (and should) get by without knowing about these two objects. Both of these are created by Gastrodon to play particular roles in the IPython and Pandas environment.
-
class
gastrodon.
GastrodonURI
(short, uri_ref)[source]¶ This class is used to wrap a URI that is passed from Gastrodon to Pandas and back again.
GastrodonURI subclasses str
It keeps track of both a shortened URI (if a namespace is given) and the full URI, so we can roundtrip this object out of the table and back into a SPARQL query without a chance of a short name being mistaken for an ordinary string.
-
class
gastrodon.
GastrodonException
(*args, **kwargs)[source]¶ Gastrodon-specific exception. The primary features of this is that it defines the method _render_traceback_ which controls the way the exception is drawn in IPython.
Parameters: - args – positional arguments for Exception
- kwargs – keyword arguments for Exception
-
static
throw
(*args, **kwargs)[source]¶ Throws a new
GastrodonException
with the following positional and keyword arguments while suppressing the context of theException
to enable short error messages in JupyterParameters: - args – positional arguments for Exception
- kwargs – keyword arguments for Exception
Returns: does not return