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)

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 a LocalEndpoint provided by rdflib.

Parameters:

• prefixes – Graph object with attached namespace mappings to be applied to the new Endpoint
• base_uri – base URI to control the base namespace of the Endpoint as we see it.

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

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)

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

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)

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)

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()

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)

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)

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)

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)

Many URIRefs 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, the URIRef 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)

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)

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

peel(node)

Copies part of a graph starting at node, copying all facts linked at that node and continuing this transversal for each blank node that we find.

Parameters:node – URIRef starting point Returns:Graph object containing copied graph

Supporting Classes and Functions

class gastrodon.QName(name: str)

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’

toURIRef(manager: rdflib.namespace.NamespaceManager) → rdflib.term.URIRef

Convert to URI Reference

Parameters:manager – rdflib.namespace.NamespaceManager used to resolve namespace Returns:A rdflib.URIRef

gastrodon.inline(turtle)

Convert turtle-format RDF into a Graph

Parameters:turtle – str in Turtle Format Returns:Graph with corresponding triples

gastrodon.ttl(g: rdflib.store.Store)

Write out Graph (or other Store) in Turtle format to stdout.

Parameters:g – input Graph Returns:nothing

gastrodon.one(items)

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)

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

gastrodon.all_uri(g: rdflib.graph.Graph)

Returns the set of all URIRef objects inside Graph g appearing in the subject. predicate, or object position in any triple.

Parameters:g – input Graph Returns:a set of URIRef objects for all URIRefs that appear in this graph

gastrodon.show_image(filename)

Embed a PNG image with a filename relative to the current working directory into an IPython/Jupyter notebook.

Parameters:filename – Returns:nothing

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)

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.

to_uri_ref() → rdflib.term.URIRef

Returns:an RDFLib rdflib.URIRef

class gastrodon.GastrodonException(*args, **kwargs)

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)

Throws a new GastrodonException with the following positional and keyword arguments while suppressing the context of the Exception to enable short error messages in Jupyter

Parameters:

• args – positional arguments for Exception
• kwargs – keyword arguments for Exception

Returns:

does not return