pyRdfa.options

  1# -*- coding: utf-8 -*-
  2"""
  3`Options` class collect the possible options that govern the parsing possibilities. The module also includes the `ProcessorGraph` class that handles the processor graph, per RDFa 1.1 (i.e., the graph containing errors and warnings). 
  4"""
  5
  6import datetime
  7
  8from rdflib import URIRef
  9from rdflib import Literal
 10from rdflib import BNode
 11from rdflib import Namespace
 12from rdflib import Graph
 13from rdflib import RDF as ns_rdf
 14
 15from .host import HostLanguage, content_to_host_language, predefined_1_0_rel, require_embedded_rdf
 16from . import ns_xsd, ns_distill, ns_rdfa
 17from . import RDFA_Error, RDFA_Warning, RDFA_Info
 18from .transform.lite import lite_prune
 19
 20ns_dc = Namespace("http://purl.org/dc/terms/")
 21ns_ht = Namespace("http://www.w3.org/2006/http#")
 22
 23class ProcessorGraph:
 24    """Wrapper around the 'processor graph', ie, the (RDF) Graph containing the warnings,
 25    error messages, and informational messages.
 26    """
 27    def __init__(self):
 28        self.graph = Graph()
 29        
 30    def add_triples(self, msg, top_class, info_class, context, node):
 31        """
 32        Add an error structure to the processor graph: a bnode with a number of predicates. The structure
 33        follows U{the processor graph vocabulary<http://www.w3.org/2010/02/rdfa/wiki/Processor_Graph_Vocabulary>} as described
 34        on the RDFa WG Wiki page.
 35        
 36        @param msg: the core error message, added as an object to a dc:description
 37        @param top_class: Error, Warning, or Info; an explicit rdf:type added to the bnode
 38        @type top_class: URIRef
 39        @param info_class: An additional error class, added as an rdf:type to the bnode in case it is not None
 40        @type info_class: URIRef
 41        @param context: An additional information added, if not None, as an object with rdfa:context as a predicate
 42        @type context: either an URIRef or a URI String (an URIRef will be created in the second case)
 43        @param node: The node's element name that contains the error
 44        @type node: string
 45        @return: the bnode that serves as a subject for the errors. The caller may add additional information
 46        @rtype: BNode
 47        """
 48        # Lazy binding of relevant prefixes
 49        self.graph.bind("dcterms", ns_dc)
 50        self.graph.bind("pyrdfa",  ns_distill)
 51        self.graph.bind("rdf",     ns_rdf)
 52        self.graph.bind("rdfa",    ns_rdfa)
 53        self.graph.bind("ht",      ns_ht)
 54        self.graph.bind("xsd",     ns_xsd)
 55
 56        is_context_string = isinstance(context, str)
 57
 58        bnode = BNode()
 59
 60        if node != None:
 61            try:
 62                full_msg = "[In element '%s'] %s" % (node.nodeName, msg)
 63            except:
 64                full_msg = "[In element '%s'] %s" % (node, msg)
 65        else:
 66            full_msg = msg
 67
 68        self.graph.add((bnode, ns_rdf["type"], top_class))
 69        if info_class:
 70            self.graph.add((bnode, ns_rdf["type"], info_class))
 71        self.graph.add((bnode, ns_dc["description"], Literal(full_msg)))
 72        self.graph.add((bnode, ns_dc["date"], Literal(datetime.datetime.utcnow().isoformat(),datatype=ns_xsd["dateTime"])))
 73        if context and (isinstance(context,URIRef) or is_context_string):
 74            htbnode = BNode()
 75            self.graph.add( (bnode,   ns_rdfa["context"],htbnode) )
 76            self.graph.add( (htbnode, ns_rdf["type"], ns_ht["Request"]) )
 77            self.graph.add( (htbnode, ns_ht["requestURI"], Literal("%s" % context)) )
 78        return bnode
 79    
 80    def add_http_context(self, subj, http_code):
 81        """
 82        Add an additional HTTP context to a message with subject in C{subj}, using the U{<http://www.w3.org/2006/http#>}
 83        vocabulary. Typically used to extend an error structure, as created by L{add_triples}.
 84        
 85        @param subj: an RDFLib resource, typically a blank node
 86        @param http_code: HTTP status code
 87        """
 88        bnode = BNode()
 89        self.graph.add((subj, ns_rdfa["context"], bnode))
 90        self.graph.add((bnode, ns_rdf["type"], ns_ht["Response"]))
 91        self.graph.add((bnode, ns_ht["responseCode"], URIRef("http://www.w3.org/2006/http#%s" % http_code)))
 92
 93class Options:
 94    '''Settable options. An instance of this class is stored in the `ExecutionContext` of the parser.'''
 95
 96    def __init__(self, output_default_graph =       True,
 97                       output_processor_graph =     False,
 98                       space_preserve =             True,
 99                       transformers =               [],
100                       embedded_rdf =               True,
101                       vocab_expansion =            False,
102                       vocab_cache =                True,
103                       vocab_cache_report =         False,
104                       refresh_vocab_cache =        False,
105                       add_informational_messages = False,
106                       check_lite =                 False,
107                       experimental_features =      False,
108                       certifi_verify =             True):
109
110        self.space_preserve =             space_preserve
111        '''whether plain literals should preserve spaces at output or not'''
112        self.transformers =               transformers
113        '''extra transformers'''
114        self.processor_graph =            ProcessorGraph()
115        '''the `ProcessorGraph`'''
116        self.output_default_graph =       output_default_graph
117        '''whether the 'default' graph should be returned to the user'''
118        self.output_processor_graph =     output_processor_graph
119        '''whether the 'processor' graph should be returned to the user'''
120        self.host_language =              HostLanguage.rdfa_core
121        '''the host language for the RDFa attributes. Default is HostLanguage.xhtml, but it can be HostLanguage.rdfa_core and HostLanguage.html5, or others...'''
122        self.vocab_cache_report =         vocab_cache_report
123        '''whether the details of vocabulary file caching process should be reported as information (mainly for debug)'''
124        self.refresh_vocab_cache =        refresh_vocab_cache
125        '''whether the caching checks of vocabs should be by-passed, ie, if caches should be re-generated regardless of the stored date (important for vocab development)'''
126        self.embedded_rdf =               embedded_rdf
127        '''whether embedded RDF (ie, turtle in an HTML script element or an RDF/XML content in SVG) should be extracted and added to the final graph. This is a non-standard option...'''
128        self.vocab_expansion =            vocab_expansion
129        '''whether the @vocab elements should be expanded and a mini-RDFS processing should be done on the merged graph'''
130        self.vocab_cache =                vocab_cache
131        '''whether the system should use the vocabulary caching mechanism when expanding via the mini-RDFS, or should just fetch the graphs every time'''
132        self.add_informational_messages = add_informational_messages
133        '''whether informational messages should also be added to the processor graph, or only errors and warnings'''
134        self.check_lite =                 check_lite
135        '''whether RDFa Lite should be checked, to generate warnings'''
136        self.experimental_features =      experimental_features
137        '''whether experimental features should be activated; that is a developer's option...'''
138        self.certifi_verify =             certifi_verify
139        '''whether the SSL certificate should be verified'''
140        if check_lite:
141            self.transformers.append(lite_prune)
142
143    def set_host_language(self, content_type):
144        """
145        Set the host language for processing, based on the recognized types. If this is not a recognized content type,
146        it falls back to RDFa core (i.e., XML)
147        @param content_type: content type
148        @type content_type: string
149        """
150        if content_type in content_to_host_language:
151            self.host_language = content_to_host_language[content_type]
152        else:
153            self.host_language = HostLanguage.rdfa_core
154            
155        if self.host_language in require_embedded_rdf:
156            self.embedded_rdf = True
157
158    def __str__(self):
159        retval = """Current options:
160        preserve space                         : %s
161        output processor graph                 : %s
162        output default graph                   : %s
163        host language                          : %s
164        accept embedded RDF                    : %s
165        perfom semantic postprocessing         : %s
166        cache vocabulary graphs                : %s
167        """
168        return retval % (self.space_preserve, self.output_processor_graph, self.output_default_graph, self.host_language, self.embedded_rdf, self.rdfa_sem, self.vocab_cache)
169
170    def reset_processor_graph(self):
171        """Empty the processor graph. This is necessary if the same options is reused
172        for several RDFa sources, and new error messages should be generated.
173        """
174        self.processor_graph.graph.remove((None,None,None))
175
176    def add_warning(self, txt, warning_type=None, context=None, node=None, buggy_value=None):
177        """Add a warning to the processor graph.
178        @param txt: the warning text. 
179        @keyword warning_type: Warning Class
180        @type warning_type: URIRef
181        @keyword context: possible context to be added to the processor graph
182        @type context: URIRef or String
183        @keyword buggy_value: a special case when a 'term' is not recognized; no warning is generated for that case if the value is part of the 'usual' XHTML terms, because almost all RDFa file contains some of those and that would pollute the output
184        @type buggy_value: String
185        """
186        if warning_type == ns_rdfa["UnresolvedTerm"] and buggy_value in predefined_1_0_rel:
187            return
188        return self.processor_graph.add_triples(txt, RDFA_Warning, warning_type, context, node)
189
190    def add_info(self, txt, info_type=None, context=None, node=None, buggy_value=None):
191        """Add an informational comment to the processor graph.
192        @param txt: the information text. 
193        @keyword info_type: Info Class
194        @type info_type: URIRef
195        @keyword context: possible context to be added to the processor graph
196        @type context: URIRef or String
197        @keyword buggy_value: a special case when a 'term' is not recognized; no information is generated for that case if the value is part of the 'usual' XHTML terms, because almost all RDFa file contains some of those and that would pollute the output
198        @type buggy_value: String
199        """
200        if self.add_informational_messages:
201            return self.processor_graph.add_triples(txt, RDFA_Info, info_type, context, node)
202        else:
203            return
204
205    def add_error(self, txt, err_type=None, context=None, node=None, buggy_value=None):
206        """Add an error  to the processor graph.
207        @param txt: the information text. 
208        @keyword err_type: Error Class
209        @type err_type: URIRef
210        @keyword context: possible context to be added to the processor graph
211        @type context: URIRef or String
212        @keyword buggy_value: a special case when a 'term' is not recognized; no error is generated for that case if the value is part of the 'usual' XHTML terms, because almost all RDFa file contains some of those and that would pollute the output
213        @type buggy_value: String
214        """
215        return self.processor_graph.add_triples(txt, RDFA_Error, err_type, context, node)