src/rdflib/term.py
1"""
2This module defines the different types of terms. Terms are the kinds of
3objects that can appear in a quoted/asserted triple. This includes those
4that are core to RDF:
5
6* [Blank Nodes][rdflib.term.BNode] - Blank Nodes
7* [URI References][rdflib.term.URIRef] - URI References
8* [Literals][rdflib.term.Literal] - Literals (which consist of a literal value, datatype and language tag)
9
10Those that extend the RDF model into N3:
11
12* [`QuotedGraph`][rdflib.graph.QuotedGraph] - Formulae
13* [`Variable`][rdflib.term.Variable] - Universal Quantifications (Variables)
14
15And those that are primarily for matching against 'Nodes' in the
16underlying Graph:
17
18* REGEX Expressions
19* Date Ranges
20* Numerical Ranges
21"""
22
23from __future__ import annotations
24
25import abc
26import re
27from fractions import Fraction
28
29__all__ = [
30 "bind",
31 "_is_valid_uri",
32 "Node",
33 "IdentifiedNode",
34 "Identifier",
35 "URIRef",
36 "BNode",
37 "Literal",
38 "Variable",
39]
40import logging
41import math
42import warnings
43import xml.dom.minidom
44from base64 import b64decode, b64encode
45from binascii import hexlify, unhexlify
46from collections import defaultdict
47from datetime import date, datetime, time, timedelta
48from decimal import Decimal
49from re import compile, sub
50from types import GeneratorType
51from typing import (
52 TYPE_CHECKING,
53 Any,
54 Callable,
55 Dict,
56 Generator,
57 List,
58 Optional,
59 Tuple,
60 Type,
61 TypeVar,
62 Union,
63)
64from urllib.parse import urldefrag, urljoin, urlparse
65from uuid import uuid4
66
67import rdflib
68import rdflib.util
69from rdflib.compat import long_type
70
71from .xsd_datetime import ( # type: ignore[attr-defined]
72 Duration,
73 duration_isoformat,
74 parse_datetime,
75 parse_time,
76 parse_xsd_date,
77 parse_xsd_duration,
78)
79
80if TYPE_CHECKING:
81 from .namespace import NamespaceManager
82 from .paths import AlternativePath, InvPath, NegatedPath, Path, SequencePath
83
84_HAS_HTML5RDF = False
85
86try:
87 import html5rdf
88
89 _HAS_HTML5RDF = True
90except ImportError:
91 html5rdf = None
92
93_SKOLEM_DEFAULT_AUTHORITY = "https://rdflib.github.io"
94
95logger = logging.getLogger(__name__)
96skolem_genid = "/.well-known/genid/"
97rdflib_skolem_genid = "/.well-known/genid/rdflib/"
98skolems: Dict[str, BNode] = {}
99
100
101_invalid_uri_chars = '<>" {}|\\^`'
102
103
104def _is_valid_uri(uri: str) -> bool:
105 for c in _invalid_uri_chars:
106 if c in uri:
107 return False
108 return True
109
110
111_lang_tag_regex = compile("^[a-zA-Z]+(?:-[a-zA-Z0-9]+)*$")
112
113
114def _is_valid_langtag(tag: str) -> bool:
115 return bool(_lang_tag_regex.match(tag))
116
117
118def _is_valid_unicode(value: Union[str, bytes]) -> bool:
119 """
120 Verify that the provided value can be converted into a Python
121 unicode object.
122 """
123 if isinstance(value, bytes):
124 coding_func, param = getattr(value, "decode"), "utf-8"
125 else:
126 coding_func, param = str, value
127
128 # try to convert value into unicode
129 try:
130 coding_func(param)
131 except UnicodeError:
132 return False
133 return True
134
135
136class Node(abc.ABC):
137 """A Node in the Graph."""
138
139 __slots__ = ()
140
141 @abc.abstractmethod
142 def n3(self, namespace_manager: Optional[NamespaceManager] = None) -> str: ...
143
144
145class Identifier(Node, str): # allow Identifiers to be Nodes in the Graph
146 """See http://www.w3.org/2002/07/rdf-identifer-terminology/
147 regarding choice of terminology."""
148
149 __slots__ = ()
150
151 def __new__(cls, value: str):
152 return str.__new__(cls, value)
153
154 def eq(self, other: Any) -> bool:
155 """A "semantic"/interpreted equality function,
156 by default, same as __eq__"""
157 return self.__eq__(other)
158
159 def neq(self, other: Any) -> bool:
160 """A "semantic"/interpreted not equal function,
161 by default, same as __ne__"""
162 return self.__ne__(other)
163
164 def __ne__(self, other: Any) -> bool:
165 return not self.__eq__(other)
166
167 def __eq__(self, other: Any) -> bool:
168 """Equality for Nodes.
169
170 ```python
171 >>> BNode("foo")==None
172 False
173 >>> BNode("foo")==URIRef("foo")
174 False
175 >>> URIRef("foo")==BNode("foo")
176 False
177 >>> BNode("foo")!=URIRef("foo")
178 True
179 >>> URIRef("foo")!=BNode("foo")
180 True
181 >>> Variable('a')!=URIRef('a')
182 True
183 >>> Variable('a')!=Variable('a')
184 False
185
186 ```
187 """
188
189 if type(self) is type(other):
190 return str(self) == str(other)
191 else:
192 return False
193
194 def __gt__(self, other: Any) -> bool:
195 """This implements ordering for Nodes.
196
197 This tries to implement this:
198 http://www.w3.org/TR/sparql11-query/#modOrderBy
199
200 Variables are not included in the SPARQL list, but
201 they are greater than BNodes and smaller than everything else
202 """
203 if other is None:
204 return True # everything bigger than None
205 elif type(self) is type(other):
206 return str(self) > str(other)
207 elif isinstance(other, Node):
208 return _ORDERING[type(self)] > _ORDERING[type(other)]
209
210 return NotImplemented
211
212 def __lt__(self, other: Any) -> bool:
213 if other is None:
214 return False # Nothing is less than None
215 elif type(self) is type(other):
216 return str(self) < str(other)
217 elif isinstance(other, Node):
218 return _ORDERING[type(self)] < _ORDERING[type(other)]
219
220 return NotImplemented
221
222 def __le__(self, other: Any) -> bool:
223 r = self.__lt__(other)
224 if r:
225 return True
226 return self == other
227
228 def __ge__(self, other: Any) -> bool:
229 r = self.__gt__(other)
230 if r:
231 return True
232 return self == other
233
234 # type error: Argument 1 of "startswith" is incompatible with supertype "str"; supertype defines the argument type as "Union[str, Tuple[str, ...]]"
235 # FIXME: this does not accommodate prefix of type Tuple[str, ...] which is a
236 # valid for str.startswith
237 def startswith(self, prefix: str, start=..., end=...) -> bool: # type: ignore[override] # FIXME
238 return str(self).startswith(str(prefix))
239
240 # use parent's hash for efficiency reasons
241 # clashes of 'foo', URIRef('foo') and Literal('foo') are typically so rare
242 # that they don't justify additional overhead. Notice that even in case of
243 # clash __eq__ is still the fallback and very quick in those cases.
244 __hash__ = str.__hash__
245
246
247class IdentifiedNode(Identifier):
248 """
249 An abstract class, primarily defined to identify Nodes that are not Literals.
250
251 The name "Identified Node" is not explicitly defined in the RDF specification, but can be drawn from this section: https://www.w3.org/TR/rdf-concepts/#section-URI-Vocabulary
252 """
253
254 __slots__ = ()
255
256 def __getnewargs__(self) -> Tuple[str]:
257 return (str(self),)
258
259 def n3(self, namespace_manager: Optional[NamespaceManager] = None) -> str:
260 raise NotImplementedError()
261
262 def toPython(self) -> str: # noqa: N802
263 return str(self)
264
265
266class URIRef(IdentifiedNode):
267 """[RDF 1.1's IRI Section](https://www.w3.org/TR/rdf11-concepts/#section-IRIs)
268
269 !!! info "Terminology"
270 Documentation on RDF outside of RDFLib uses the term IRI or URI whereas this class is called URIRef. This is because it was made when the first version of the RDF specification was current, and it used the term *URIRef*, see [RDF 1.0 URIRef](http://www.w3.org/TR/rdf-concepts/#section-Graph-URIref)
271
272 An IRI (Internationalized Resource Identifier) within an RDF graph is a Unicode string that conforms to the syntax defined in RFC 3987.
273
274 IRIs in the RDF abstract syntax MUST be absolute, and MAY contain a fragment identifier.
275
276 IRIs are a generalization of URIs [RFC3986] that permits a wider range of Unicode characters.
277 """
278
279 __slots__ = ()
280
281 __or__: Callable[[URIRef, Union[URIRef, Path]], AlternativePath]
282 __invert__: Callable[[URIRef], InvPath]
283 __neg__: Callable[[URIRef], NegatedPath]
284 __truediv__: Callable[[URIRef, Union[URIRef, Path]], SequencePath]
285
286 def __new__(cls, value: str, base: Optional[str] = None):
287 if base is not None:
288 ends_in_hash = value.endswith("#")
289 # type error: Argument "allow_fragments" to "urljoin" has incompatible type "int"; expected "bool"
290 value = urljoin(base, value, allow_fragments=1) # type: ignore[arg-type]
291 if ends_in_hash:
292 if not value.endswith("#"):
293 value += "#"
294
295 if not _is_valid_uri(value):
296 logger.warning(
297 f"{value} does not look like a valid URI, trying to serialize this will break."
298 )
299
300 try:
301 rt = str.__new__(cls, value)
302 except UnicodeDecodeError:
303 # type error: No overload variant of "__new__" of "str" matches argument types "Type[URIRef]", "str", "str"
304 rt = str.__new__(cls, value, "utf-8") # type: ignore[call-overload]
305 return rt
306
307 def n3(self, namespace_manager: Optional[NamespaceManager] = None) -> str:
308 """This will do a limited check for valid URIs,
309 essentially just making sure that the string includes no illegal
310 characters (`<, >, ", {, }, |, \\, `, ^`)
311
312 Args:
313 namespace_manager: if not None, will be used to make up a prefixed name
314 """
315
316 if not _is_valid_uri(self):
317 raise Exception(
318 f'"{self}" does not look like a valid URI, I cannot serialize this as N3/Turtle. Perhaps you wanted to urlencode it?'
319 )
320
321 if namespace_manager:
322 return namespace_manager.normalizeUri(self)
323 else:
324 return f"<{self}>"
325
326 def defrag(self) -> URIRef:
327 if "#" in self:
328 url, frag = urldefrag(self)
329 return URIRef(url)
330 else:
331 return self
332
333 @property
334 def fragment(self) -> str:
335 """Return the URL Fragment
336
337 ```python
338 >>> URIRef("http://example.com/some/path/#some-fragment").fragment
339 'some-fragment'
340 >>> URIRef("http://example.com/some/path/").fragment
341 ''
342
343 ```
344 """
345 return urlparse(self).fragment
346
347 def __reduce__(self) -> Tuple[Type[URIRef], Tuple[str]]:
348 return (URIRef, (str(self),))
349
350 def __repr__(self) -> str:
351 if self.__class__ is URIRef:
352 clsName = "rdflib.term.URIRef" # noqa: N806
353 else:
354 clsName = self.__class__.__name__ # noqa: N806
355
356 return f"{clsName}({str.__repr__(self)})"
357
358 def __add__(self, other) -> URIRef:
359 return self.__class__(str(self) + other)
360
361 def __radd__(self, other) -> URIRef:
362 return self.__class__(other + str(self))
363
364 def __mod__(self, other) -> URIRef:
365 return self.__class__(str(self) % other)
366
367 def de_skolemize(self) -> BNode:
368 """Create a Blank Node from a skolem URI, in accordance
369 with http://www.w3.org/TR/rdf11-concepts/#section-skolemization.
370 This function accepts only rdflib type skolemization, to provide
371 a round-tripping within the system.
372
373 Added in version 4.0
374 """
375 if isinstance(self, RDFLibGenid):
376 parsed_uri = urlparse(f"{self}")
377 return BNode(value=parsed_uri.path[len(rdflib_skolem_genid) :])
378 elif isinstance(self, Genid):
379 bnode_id = f"{self}"
380 if bnode_id in skolems:
381 return skolems[bnode_id]
382 else:
383 retval = BNode()
384 skolems[bnode_id] = retval
385 return retval
386 else:
387 raise Exception(f"<{self}> is not a skolem URI")
388
389
390class Genid(URIRef):
391 __slots__ = ()
392
393 @staticmethod
394 def _is_external_skolem(uri: Any) -> bool:
395 if not isinstance(uri, str):
396 uri = str(uri)
397 parsed_uri = urlparse(uri)
398 gen_id = parsed_uri.path.rfind(skolem_genid)
399 if gen_id != 0:
400 return False
401 return True
402
403
404class RDFLibGenid(Genid):
405 __slots__ = ()
406
407 @staticmethod
408 def _is_rdflib_skolem(uri: Any) -> bool:
409 if not isinstance(uri, str):
410 uri = str(uri)
411 parsed_uri = urlparse(uri)
412 if (
413 parsed_uri.params != ""
414 or parsed_uri.query != ""
415 or parsed_uri.fragment != ""
416 ):
417 return False
418 gen_id = parsed_uri.path.rfind(rdflib_skolem_genid)
419 if gen_id != 0:
420 return False
421 return True
422
423
424def _unique_id() -> str:
425 # Used to read: """Create a (hopefully) unique prefix"""
426 # now retained merely to leave internal API unchanged.
427 # From BNode.__new__() below ...
428 #
429 # acceptable bnode value range for RDF/XML needs to be
430 # something that can be serialzed as a nodeID for N3
431 #
432 # BNode identifiers must be valid NCNames" _:[A-Za-z][A-Za-z0-9]*
433 # http://www.w3.org/TR/2004/REC-rdf-testcases-20040210/#nodeID
434 return "N" # ensure that id starts with a letter
435
436
437class BNode(IdentifiedNode):
438 """
439 RDF 1.1's Blank Nodes Section: https://www.w3.org/TR/rdf11-concepts/#section-blank-nodes
440
441 Blank Nodes are local identifiers for unnamed nodes in RDF graphs that are used in
442 some concrete RDF syntaxes or RDF store implementations. They are always locally
443 scoped to the file or RDF store, and are not persistent or portable identifiers for
444 blank nodes. The identifiers for Blank Nodes are not part of the RDF abstract
445 syntax, but are entirely dependent on particular concrete syntax or implementation
446 (such as Turtle, JSON-LD).
447
448 ---
449
450 RDFLib's `BNode` class makes unique IDs for all the Blank Nodes in a Graph but you
451 should *never* expect, or reply on, BNodes' IDs to match across graphs, or even for
452 multiple copies of the same graph, if they are regenerated from some non-RDFLib
453 source, such as loading from RDF data.
454 """
455
456 __slots__ = ()
457
458 def __new__(
459 cls,
460 value: Optional[str] = None,
461 _sn_gen: Optional[Union[Callable[[], str], Generator]] = None,
462 _prefix: str = _unique_id(),
463 ):
464 """
465 # only store implementations should pass in a value
466 """
467 if value is None:
468 # so that BNode values do not collide with ones created with
469 # a different instance of this module at some other time.
470 if _sn_gen is not None:
471 if callable(_sn_gen):
472 sn_result: Union[str, Generator] = _sn_gen()
473 else:
474 sn_result = _sn_gen
475 if isinstance(sn_result, GeneratorType):
476 node_id = next(sn_result)
477 else:
478 node_id = sn_result
479 else:
480 node_id = uuid4().hex
481 # note, for two (and only two) string variables,
482 # concat with + is faster than f"{x}{y}"
483 value = _prefix + f"{node_id}"
484 else:
485 # TODO: check that value falls within acceptable bnode value range
486 # for RDF/XML needs to be something that can be serialized
487 # as a nodeID for N3 ?? Unless we require these
488 # constraints be enforced elsewhere?
489 pass # assert is_ncname(str(value)), "BNode identifiers
490 # must be valid NCNames" _:[A-Za-z][A-Za-z0-9]*
491 # http://www.w3.org/TR/2004/REC-rdf-testcases-20040210/#nodeID
492 # type error: Incompatible return value type (got "Identifier", expected "BNode")
493 return Identifier.__new__(cls, value)
494
495 def n3(self, namespace_manager: Optional[NamespaceManager] = None) -> str:
496 # note - for two strings, concat with + is faster than f"{x}{y}"
497 return "_:" + self
498
499 def __reduce__(self) -> Tuple[Type[BNode], Tuple[str]]:
500 return (BNode, (str(self),))
501
502 def __repr__(self) -> str:
503 if self.__class__ is BNode:
504 clsName = "rdflib.term.BNode" # noqa: N806
505 else:
506 clsName = self.__class__.__name__ # noqa: N806
507 return f"{clsName}({str.__repr__(self)})"
508
509 def skolemize(
510 self, authority: Optional[str] = None, basepath: Optional[str] = None
511 ) -> URIRef:
512 """Create a URIRef "skolem" representation of the BNode, in accordance
513 with http://www.w3.org/TR/rdf11-concepts/#section-skolemization
514
515 Added in version 4.0
516 """
517 if authority is None:
518 authority = _SKOLEM_DEFAULT_AUTHORITY
519 if basepath is None:
520 basepath = rdflib_skolem_genid
521 skolem = basepath + str(self)
522 return URIRef(urljoin(authority, skolem))
523
524
525class Literal(Identifier):
526 """
527
528 RDF 1.1's Literals Section: http://www.w3.org/TR/rdf-concepts/#section-Graph-Literal
529
530 Literals are used for values such as strings, numbers, and dates.
531
532 A literal in an RDF graph consists of two or three elements:
533
534 * a lexical form, being a Unicode string, which SHOULD be in Normal Form C
535 * a datatype IRI, being an IRI identifying a datatype that determines how the lexical form maps to a literal value, and
536 * if and only if the datatype IRI is `http://www.w3.org/1999/02/22-rdf-syntax-ns#langString`, a non-empty language tag. The language tag MUST be well-formed according to section 2.2.9 of `Tags for identifying languages <http://tools.ietf.org/html/bcp47>`_.
537
538 A literal is a language-tagged string if the third element is present. Lexical representations of language tags MAY be converted to lower case. The value space of language tags is always in lower case.
539
540 ---
541
542 For valid XSD datatypes, the lexical form is optionally normalized
543 at construction time. Default behaviour is set by `rdflib.NORMALIZE_LITERALS`
544 and can be overridden by the normalize parameter to `__new__`
545
546 Equality and hashing of Literals are done based on the lexical form, i.e.:
547
548 ```python
549 >>> from rdflib.namespace import XSD
550 >>> Literal('01') != Literal('1') # clear - strings differ
551 True
552
553 ```
554
555 but with data-type they get normalized:
556
557 ```python
558 >>> Literal('01', datatype=XSD.integer) != Literal('1', datatype=XSD.integer)
559 False
560
561 ```
562
563 unless disabled:
564
565 ```python
566 >>> Literal('01', datatype=XSD.integer, normalize=False) != Literal('1', datatype=XSD.integer)
567 True
568
569 ```
570
571 Value based comparison is possible:
572
573 ```python
574 >>> Literal('01', datatype=XSD.integer).eq(Literal('1', datatype=XSD.float))
575 True
576
577 ```
578
579 The eq method also provides limited support for basic python types:
580
581 ```python
582 >>> Literal(1).eq(1) # fine - int compatible with xsd:integer
583 True
584 >>> Literal('a').eq('b') # fine - str compatible with plain-lit
585 False
586 >>> Literal('a', datatype=XSD.string).eq('a') # fine - str compatible with xsd:string
587 True
588 >>> Literal('a').eq(1) # not fine, int incompatible with plain-lit
589 NotImplemented
590
591 ```
592
593 Greater-than/less-than ordering comparisons are also done in value
594 space, when compatible datatypes are used. Incompatible datatypes
595 are ordered by DT, or by lang-tag. For other nodes the ordering
596 is None < BNode < URIRef < Literal
597
598 Any comparison with non-rdflib Node are "NotImplemented"
599 In PY3 this is an error.
600
601 ```python
602 >>> from rdflib import Literal, XSD
603 >>> lit2006 = Literal('2006-01-01',datatype=XSD.date)
604 >>> lit2006.toPython()
605 datetime.date(2006, 1, 1)
606 >>> lit2006 < Literal('2007-01-01',datatype=XSD.date)
607 True
608 >>> Literal(datetime.utcnow()).datatype
609 rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#dateTime')
610 >>> Literal(1) > Literal(2) # by value
611 False
612 >>> Literal(1) > Literal(2.0) # by value
613 False
614 >>> Literal('1') > Literal(1) # by DT
615 True
616 >>> Literal('1') < Literal('1') # by lexical form
617 False
618 >>> Literal('a', lang='en') > Literal('a', lang='fr') # by lang-tag
619 False
620 >>> Literal(1) > URIRef('foo') # by node-type
621 True
622
623 ```
624
625 The > < operators will eat this NotImplemented and throw a TypeError (py3k):
626
627 ```python
628 >>> Literal(1).__gt__(2.0)
629 NotImplemented
630
631 ```
632 """
633
634 _value: Any
635 _language: Optional[str]
636 # NOTE: _datatype should maybe be of type URIRef, and not optional.
637 _datatype: Optional[URIRef]
638 _ill_typed: Optional[bool]
639 __slots__ = ("_language", "_datatype", "_value", "_ill_typed")
640
641 def __new__(
642 cls,
643 lexical_or_value: Any,
644 lang: Optional[str] = None,
645 datatype: Optional[str] = None,
646 normalize: Optional[bool] = None,
647 ):
648 """Create a new Literal instance."""
649 if lang == "":
650 lang = None # no empty lang-tags in RDF
651
652 normalize = normalize if normalize is not None else rdflib.NORMALIZE_LITERALS
653
654 if lang is not None and datatype is not None:
655 raise TypeError(
656 "A Literal can only have one of lang or datatype, "
657 "per http://www.w3.org/TR/rdf-concepts/#section-Graph-Literal"
658 )
659
660 if lang is not None and not _is_valid_langtag(lang):
661 raise ValueError(f"'{str(lang)}' is not a valid language tag!")
662
663 if datatype is not None:
664 datatype = URIRef(datatype)
665
666 value = None
667 ill_typed: Optional[bool] = None
668 if isinstance(lexical_or_value, Literal):
669 # create from another Literal instance
670
671 lang = lang or lexical_or_value.language
672 if datatype is not None:
673 # override datatype
674 value = _castLexicalToPython(lexical_or_value, datatype)
675 else:
676 datatype = lexical_or_value.datatype
677 value = lexical_or_value.value
678
679 elif isinstance(lexical_or_value, str) or isinstance(lexical_or_value, bytes):
680 # passed a string
681 # try parsing lexical form of datatyped literal
682 value = _castLexicalToPython(lexical_or_value, datatype)
683 if datatype is not None and datatype in _toPythonMapping:
684 # datatype is a recognized datatype IRI:
685 # https://www.w3.org/TR/rdf11-concepts/#dfn-recognized-datatype-iris
686 dt_uri: URIRef = URIRef(datatype)
687 checker = _check_well_formed_types.get(dt_uri, _well_formed_by_value)
688 well_formed = checker(lexical_or_value, value)
689 ill_typed = ill_typed or (not well_formed)
690 if value is not None and normalize:
691 _value, _datatype = _castPythonToLiteral(value, datatype)
692 if _value is not None and _is_valid_unicode(_value):
693 lexical_or_value = _value
694
695 else:
696 # passed some python object
697 value = lexical_or_value
698 _value, _datatype = _castPythonToLiteral(lexical_or_value, datatype)
699
700 _datatype = None if _datatype is None else URIRef(_datatype)
701
702 datatype = rdflib.util._coalesce(datatype, _datatype)
703 if _value is not None:
704 lexical_or_value = _value
705 if datatype is not None:
706 lang = None
707
708 if isinstance(lexical_or_value, bytes):
709 lexical_or_value = lexical_or_value.decode("utf-8")
710
711 if datatype in (_XSD_NORMALISED_STRING, _XSD_TOKEN):
712 lexical_or_value = _normalise_XSD_STRING(lexical_or_value)
713
714 if datatype in (_XSD_TOKEN,):
715 lexical_or_value = _strip_and_collapse_whitespace(lexical_or_value)
716
717 try:
718 inst = str.__new__(cls, lexical_or_value)
719 except UnicodeDecodeError:
720 inst = str.__new__(cls, lexical_or_value, "utf-8")
721
722 inst._language = lang
723 inst._datatype = datatype
724 inst._value = value
725 inst._ill_typed = ill_typed
726
727 return inst
728
729 def normalize(self) -> Literal:
730 """
731 Returns a new literal with a normalised lexical representation
732 of this literal
733
734 ```python
735 >>> from rdflib import XSD
736 >>> Literal("01", datatype=XSD.integer, normalize=False).normalize()
737 rdflib.term.Literal('1', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#integer'))
738
739 ```
740
741 Illegal lexical forms for the datatype given are simply passed on
742
743 ```python
744 >>> Literal("a", datatype=XSD.integer, normalize=False)
745 rdflib.term.Literal('a', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#integer'))
746
747 ```
748 """
749
750 if self.value is not None:
751 return Literal(self.value, datatype=self.datatype, lang=self.language)
752 else:
753 return self
754
755 @property
756 def ill_typed(self) -> Optional[bool]:
757 """
758 For `recognized datatype IRIs
759 <https://www.w3.org/TR/rdf11-concepts/#dfn-recognized-datatype-iris>`_,
760 this value will be `True` if the literal is ill formed, otherwise it
761 will be `False`. `Literal.value` (i.e. the `literal value <https://www.w3.org/TR/rdf11-concepts/#dfn-literal-value>`_) should always be defined if this property is `False`, but should not be considered reliable if this property is `True`.
762
763 If the literal's datatype is `None` or not in the set of `recognized datatype IRIs
764 <https://www.w3.org/TR/rdf11-concepts/#dfn-recognized-datatype-iris>`_ this value will be `None`.
765 """
766 return self._ill_typed
767
768 @property
769 def value(self) -> Any:
770 return self._value
771
772 @property
773 def language(self) -> Optional[str]:
774 return self._language
775
776 @property
777 def datatype(self) -> Optional[URIRef]:
778 return self._datatype
779
780 def __reduce__(
781 self,
782 ) -> Tuple[Type[Literal], Tuple[str, Union[str, None], Union[str, None]]]:
783 return (
784 Literal,
785 (str(self), self.language, self.datatype),
786 )
787
788 def __getstate__(self) -> Tuple[None, Dict[str, Union[str, None]]]:
789 return (None, dict(language=self.language, datatype=self.datatype))
790
791 def __setstate__(self, arg: Tuple[Any, Dict[str, Any]]) -> None:
792 _, d = arg
793 self._language = d["language"]
794 self._datatype = d["datatype"]
795
796 def __add__(self, val: Any) -> Literal:
797 """
798 ```python
799 >>> from rdflib.namespace import XSD
800 >>> Literal(1) + 1
801 rdflib.term.Literal('2', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#integer'))
802 >>> Literal("1") + "1"
803 rdflib.term.Literal('11')
804
805 # Handling dateTime/date/time based operations in Literals
806 >>> a = Literal('2006-01-01T20:50:00', datatype=XSD.dateTime)
807 >>> b = Literal('P31D', datatype=XSD.duration)
808 >>> (a + b)
809 rdflib.term.Literal('2006-02-01T20:50:00', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#dateTime'))
810 >>> from rdflib.namespace import XSD
811 >>> a = Literal('2006-07-01T20:52:00', datatype=XSD.dateTime)
812 >>> b = Literal('P122DT15H58M', datatype=XSD.duration)
813 >>> (a + b)
814 rdflib.term.Literal('2006-11-01T12:50:00', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#dateTime'))
815
816 ```
817 """
818
819 # if no val is supplied, return this Literal
820 if val is None:
821 return self
822
823 # convert the val to a Literal, if it isn't already one
824 if not isinstance(val, Literal):
825 val = Literal(val)
826
827 # if self is datetime based and value is duration
828 if (
829 self.datatype in (_XSD_DATETIME, _XSD_DATE)
830 and val.datatype in _TIME_DELTA_TYPES
831 ):
832 date1: Union[datetime, date] = self.toPython()
833 duration: Union[Duration, timedelta] = val.toPython()
834 difference = date1 + duration
835 return Literal(difference, datatype=self.datatype)
836
837 # if self is time based and value is duration
838 elif self.datatype == _XSD_TIME and val.datatype in _TIME_DELTA_TYPES:
839 selfv: time = self.toPython()
840 valv: Union[Duration, timedelta] = val.toPython()
841 sdt = datetime.combine(date(2000, 1, 1), selfv) + valv
842 return Literal(sdt.time(), datatype=self.datatype)
843
844 # if self is datetime based and value is not or vice versa
845 elif (
846 (
847 self.datatype in _ALL_DATE_AND_TIME_TYPES
848 and val.datatype not in _ALL_DATE_AND_TIME_TYPES
849 )
850 or (
851 self.datatype not in _ALL_DATE_AND_TIME_TYPES
852 and val.datatype in _ALL_DATE_AND_TIME_TYPES
853 )
854 or (
855 self.datatype in _TIME_DELTA_TYPES
856 and (
857 (val.datatype not in _TIME_DELTA_TYPES)
858 or (self.datatype != val.datatype)
859 )
860 )
861 ):
862 raise TypeError(
863 f"Cannot add a Literal of datatype {str(val.datatype)} to a Literal of datatype {str(self.datatype)}"
864 )
865
866 # if the datatypes are the same, just add the Python values and convert back
867 if self.datatype == val.datatype:
868 return Literal(
869 self.toPython() + val.toPython(), self.language, datatype=self.datatype
870 )
871 # if the datatypes are not the same but are both numeric, add the Python values and strip off decimal junk
872 # (i.e. tiny numbers (more than 17 decimal places) and trailing zeros) and return as a decimal
873 elif (
874 self.datatype in _NUMERIC_LITERAL_TYPES
875 and val.datatype in _NUMERIC_LITERAL_TYPES
876 ):
877 return Literal(
878 Decimal(
879 f"{round(Decimal(self.toPython()) + Decimal(val.toPython()), 15):f}".rstrip(
880 "0"
881 ).rstrip(
882 "."
883 )
884 ),
885 datatype=_XSD_DECIMAL,
886 )
887 # in all other cases, perform string concatenation
888 else:
889 try:
890 s = str.__add__(self, val)
891 except TypeError:
892 s = str(self.value) + str(val)
893
894 # if the original datatype is string-like, use that
895 if self.datatype in _STRING_LITERAL_TYPES:
896 new_datatype = self.datatype
897 # if not, use string
898 else:
899 new_datatype = _XSD_STRING
900
901 return Literal(s, self.language, datatype=new_datatype)
902
903 def __sub__(self, val: Any) -> Literal:
904 """Implements subtraction between Literals or between a Literal and a Python object.
905
906 Example:
907 ```python
908 from rdflib.namespace import XSD
909
910 # Basic numeric subtraction
911 Literal(2) - 1
912 # rdflib.term.Literal('1', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#integer'))
913
914 Literal(1.1) - 1.0
915 # rdflib.term.Literal('0.10000000000000009', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#double'))
916
917 Literal(1.1) - 1
918 # rdflib.term.Literal('0.1', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#decimal'))
919
920 Literal(1.1, datatype=XSD.float) - Literal(1.0, datatype=XSD.float)
921 # rdflib.term.Literal('0.10000000000000009', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#float'))
922
923 # This will raise a TypeError
924 Literal("1.1") - 1.0
925 # TypeError: Not a number; rdflib.term.Literal('1.1')
926
927 Literal(1.1, datatype=XSD.integer) - Literal(1.0, datatype=XSD.integer)
928 # rdflib.term.Literal('0.10000000000000009', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#integer'))
929
930 # Handling dateTime/date/time based operations in Literals
931 a = Literal('2006-01-01T20:50:00', datatype=XSD.dateTime)
932 b = Literal('2006-02-01T20:50:00', datatype=XSD.dateTime)
933 (b - a)
934 # rdflib.term.Literal('P31D', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#duration'))
935
936 a = Literal('2006-07-01T20:52:00', datatype=XSD.dateTime)
937 b = Literal('2006-11-01T12:50:00', datatype=XSD.dateTime)
938 (a - b)
939 # rdflib.term.Literal('-P122DT15H58M', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#duration'))
940 (b - a)
941 # rdflib.term.Literal('P122DT15H58M', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#duration'))
942 ```
943 """
944 # if no val is supplied, return this Literal
945 if val is None:
946 return self
947
948 # convert the val to a Literal, if it isn't already one
949 if not isinstance(val, Literal):
950 val = Literal(val)
951
952 if not getattr(self, "datatype"):
953 raise TypeError(
954 "Minuend Literal must have Numeric, Date, Datetime or Time datatype."
955 )
956 elif not getattr(val, "datatype"):
957 raise TypeError(
958 "Subtrahend Literal must have Numeric, Date, Datetime or Time datatype."
959 )
960
961 if (
962 self.datatype in (_XSD_DATETIME, _XSD_DATE)
963 and val.datatype in _TIME_DELTA_TYPES
964 ):
965 date1: Union[datetime, date] = self.toPython()
966 duration: Union[Duration, timedelta] = val.toPython()
967 difference = date1 - duration
968 return Literal(difference, datatype=self.datatype)
969
970 # if self is time based and value is duration
971 elif self.datatype == _XSD_TIME and val.datatype in _TIME_DELTA_TYPES:
972 selfv: time = self.toPython()
973 valv: Union[Duration, timedelta] = val.toPython()
974 sdt = datetime.combine(date(2000, 1, 1), selfv) - valv
975 return Literal(sdt.time(), datatype=self.datatype)
976
977 # if the datatypes are the same, just subtract the Python values and convert back
978 if self.datatype == val.datatype:
979 if self.datatype == _XSD_TIME:
980 sdt = datetime.combine(date.today(), self.toPython())
981 vdt = datetime.combine(date.today(), val.toPython())
982 return Literal(sdt - vdt, datatype=_XSD_DURATION)
983 else:
984 return Literal(
985 self.toPython() - val.toPython(),
986 self.language,
987 datatype=(
988 _XSD_DURATION
989 if self.datatype in (_XSD_DATETIME, _XSD_DATE, _XSD_TIME)
990 else self.datatype
991 ),
992 )
993
994 # if the datatypes are not the same but are both numeric, subtract the Python values and strip off decimal junk
995 # (i.e. tiny numbers (more than 17 decimal places) and trailing zeros) and return as a decimal
996 elif (
997 self.datatype in _NUMERIC_LITERAL_TYPES
998 and val.datatype in _NUMERIC_LITERAL_TYPES
999 ):
1000 return Literal(
1001 Decimal(
1002 f"{round(Decimal(self.toPython()) - Decimal(val.toPython()), 15):f}".rstrip(
1003 "0"
1004 ).rstrip(
1005 "."
1006 )
1007 ),
1008 datatype=_XSD_DECIMAL,
1009 )
1010 # in all other cases, perform string concatenation
1011 else:
1012 raise TypeError(
1013 f"Cannot subtract a Literal of datatype {str(val.datatype)} from a Literal of datatype {str(self.datatype)}"
1014 )
1015
1016 def __bool__(self) -> bool:
1017 """Determines the truth value of the Literal.
1018
1019 Used for if statements, bool(literal), etc.
1020 """
1021 if self.value is not None:
1022 return bool(self.value)
1023 return len(self) != 0
1024
1025 def __neg__(self) -> Literal:
1026 """Implements unary negation for Literals with numeric values.
1027
1028 Example:
1029 ```python
1030 # Negating an integer Literal
1031 -Literal(1)
1032 # rdflib.term.Literal('-1', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#integer'))
1033
1034 # Negating a float Literal
1035 -Literal(10.5)
1036 # rdflib.term.Literal('-10.5', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#double'))
1037
1038 # Using a string with a datatype
1039 from rdflib.namespace import XSD
1040 -Literal("1", datatype=XSD.integer)
1041 # rdflib.term.Literal('-1', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#integer'))
1042
1043 # This will raise a TypeError
1044 -Literal("1")
1045 # TypeError: Not a number; rdflib.term.Literal('1')
1046 ```
1047 """
1048
1049 if isinstance(self.value, (int, long_type, float)):
1050 return Literal(self.value.__neg__())
1051 else:
1052 raise TypeError(f"Not a number; {self!r}")
1053
1054 def __pos__(self) -> Literal:
1055 """Implements unary plus operation for Literals with numeric values.
1056
1057 Example:
1058 ```python
1059 # Applying unary plus to an integer Literal
1060 +Literal(1)
1061 # rdflib.term.Literal('1', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#integer'))
1062
1063 # Applying unary plus to a negative integer Literal
1064 +Literal(-1)
1065 # rdflib.term.Literal('-1', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#integer'))
1066
1067 # Using a string with a datatype
1068 from rdflib.namespace import XSD
1069 +Literal("-1", datatype=XSD.integer)
1070 # rdflib.term.Literal('-1', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#integer'))
1071
1072 # This will raise a TypeError
1073 +Literal("1")
1074 # TypeError: Not a number; rdflib.term.Literal('1')
1075 ```
1076 """
1077 if isinstance(self.value, (int, long_type, float)):
1078 return Literal(self.value.__pos__())
1079 else:
1080 raise TypeError(f"Not a number; {self!r}")
1081
1082 def __abs__(self) -> Literal:
1083 """Implements absolute value operation for Literals with numeric values.
1084
1085 Example:
1086 ```python
1087 # Absolute value of a negative integer Literal
1088 abs(Literal(-1))
1089 # rdflib.term.Literal('1', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#integer'))
1090
1091 # Using a string with a datatype
1092 from rdflib.namespace import XSD
1093 abs(Literal("-1", datatype=XSD.integer))
1094 # rdflib.term.Literal('1', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#integer'))
1095
1096 # This will raise a TypeError
1097 abs(Literal("1"))
1098 # TypeError: Not a number; rdflib.term.Literal('1')
1099 ```
1100 """
1101 if isinstance(self.value, (int, long_type, float)):
1102 return Literal(self.value.__abs__())
1103 else:
1104 raise TypeError(f"Not a number; {self!r}")
1105
1106 def __invert__(self) -> Literal:
1107 """Implements bitwise NOT operation for Literals with numeric values.
1108
1109 Example:
1110 ```python
1111 # Bitwise NOT of a negative integer Literal
1112 ~(Literal(-1))
1113 # rdflib.term.Literal('0', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#integer'))
1114
1115 # Using a string with a datatype
1116 from rdflib.namespace import XSD
1117 ~(Literal("-1", datatype=XSD.integer))
1118 # rdflib.term.Literal('0', datatype=rdflib.term.URIRef('http://www.w3.org/2001/XMLSchema#integer'))
1119
1120 # This will raise a TypeError
1121 ~(Literal("1"))
1122 # TypeError: Not a number; rdflib.term.Literal('1')
1123 ```
1124 """
1125 if isinstance(self.value, (int, long_type, float)):
1126 # type error: Unsupported operand type for ~ ("float")
1127 return Literal(self.value.__invert__()) # type: ignore[operator] # FIXME
1128 else:
1129 raise TypeError(f"Not a number; {self!r}")
1130
1131 def __gt__(self, other: Any) -> bool:
1132 """Implements the greater-than comparison for Literals.
1133
1134 This is the base method for ordering comparisons - other comparison methods delegate here.
1135
1136 Implements the ordering rules described in http://www.w3.org/TR/sparql11-query/#modOrderBy
1137
1138 In summary:
1139 1. Literals with compatible data-types are ordered in value space
1140 2. Incompatible datatypes are ordered by their datatype URIs
1141 3. Literals with language tags are ordered by their language tags
1142 4. Plain literals come before xsd:string literals
1143 5. In the node order: None < BNode < URIRef < Literal
1144
1145 Example:
1146 ```python
1147 from rdflib import XSD
1148 from decimal import Decimal
1149
1150 # Comparing numeric literals in value space
1151 Literal(1) > Literal(2) # int/int
1152 # False
1153
1154 Literal(2.0) > Literal(1) # double/int
1155 # True
1156
1157 Literal(Decimal("3.3")) > Literal(2.0) # decimal/double
1158 # True
1159
1160 Literal(Decimal("3.3")) < Literal(4.0) # decimal/double
1161 # True
1162
1163 # Comparing string literals
1164 Literal('b') > Literal('a') # plain lit/plain lit
1165 # True
1166
1167 Literal('b') > Literal('a', datatype=XSD.string) # plain lit/xsd:str
1168 # True
1169
1170 # Incompatible datatypes ordered by DT
1171 Literal(1) > Literal("2") # int>string
1172 # False
1173
1174 # Langtagged literals ordered by lang tag
1175 Literal("a", lang="en") > Literal("a", lang="fr")
1176 # False
1177 ```
1178 """
1179 if other is None:
1180 return True # Everything is greater than None
1181 if isinstance(other, Literal):
1182 # Fast path for comparing numeric literals
1183 # that are not ill-typed and don't have a None value
1184 if (
1185 (
1186 self.datatype in _NUMERIC_LITERAL_TYPES
1187 and other.datatype in _NUMERIC_LITERAL_TYPES
1188 )
1189 and ((not self.ill_typed) and (not other.ill_typed))
1190 and (self.value is not None and other.value is not None)
1191 ):
1192 return self.value > other.value
1193
1194 # plain-literals and xsd:string literals
1195 # are "the same"
1196 dtself = rdflib.util._coalesce(self.datatype, default=_XSD_STRING)
1197 dtother = rdflib.util._coalesce(other.datatype, default=_XSD_STRING)
1198
1199 if dtself != dtother:
1200 if rdflib.DAWG_LITERAL_COLLATION:
1201 return NotImplemented
1202 else:
1203 return dtself > dtother
1204
1205 if self.language != other.language:
1206 if not self.language:
1207 return False
1208 elif not other.language:
1209 return True
1210 else:
1211 return self.language > other.language
1212
1213 if self.value is not None and other.value is not None:
1214 if type(self.value) in _TOTAL_ORDER_CASTERS:
1215 caster = _TOTAL_ORDER_CASTERS[type(self.value)]
1216 return caster(self.value) > caster(other.value)
1217
1218 try:
1219 return self.value > other.value
1220 except TypeError:
1221 pass
1222
1223 if str(self) != str(other):
1224 return str(self) > str(other)
1225
1226 # same language, same lexical form, check real dt
1227 # plain-literals come before xsd:string!
1228 if self.datatype != other.datatype:
1229 if self.datatype is None:
1230 return False
1231 elif other.datatype is None:
1232 return True
1233 else:
1234 return self.datatype > other.datatype
1235
1236 return False # they are the same
1237
1238 elif isinstance(other, Node):
1239 return True # Literal are the greatest!
1240 else:
1241 return NotImplemented # we can only compare to nodes
1242
1243 def __lt__(self, other: Any) -> bool:
1244 if other is None:
1245 return False # Nothing is less than None
1246 if isinstance(other, Literal):
1247 try:
1248 return not self.__gt__(other) and not self.eq(other)
1249 except TypeError:
1250 return NotImplemented
1251 if isinstance(other, Node):
1252 return False # all nodes are less-than Literals
1253
1254 return NotImplemented
1255
1256 def __le__(self, other: Any) -> bool:
1257 """Less than or equal operator for Literals.
1258
1259 Example:
1260 ```python
1261 from rdflib.namespace import XSD
1262 Literal('2007-01-01T10:00:00', datatype=XSD.dateTime) <= Literal('2007-01-01T10:00:00', datatype=XSD.dateTime)
1263 # True
1264 ```
1265 """
1266 r = self.__lt__(other)
1267 if r:
1268 return True
1269 try:
1270 return self.eq(other)
1271 except TypeError:
1272 return NotImplemented
1273
1274 def __ge__(self, other: Any) -> bool:
1275 r = self.__gt__(other)
1276 if r:
1277 return True
1278 try:
1279 return self.eq(other)
1280 except TypeError:
1281 return NotImplemented
1282
1283 def _comparable_to(self, other: Any) -> bool:
1284 """Helper method to decide which things are meaningful to rich-compare with this literal."""
1285 if isinstance(other, Literal):
1286 if self.datatype is not None and other.datatype is not None:
1287 # two datatyped literals
1288 if (
1289 self.datatype not in XSDToPython
1290 or other.datatype not in XSDToPython
1291 ):
1292 # non XSD DTs must match
1293 if self.datatype != other.datatype:
1294 return False
1295
1296 else:
1297 # xsd:string may be compared with plain literals
1298 if not (self.datatype == _XSD_STRING and not other.datatype) or (
1299 other.datatype == _XSD_STRING and not self.datatype
1300 ):
1301 return False
1302
1303 # if given lang-tag has to be case insensitive equal
1304 if (self.language or "").lower() != (other.language or "").lower():
1305 return False
1306
1307 return True
1308
1309 # type error: Signature of "__hash__" incompatible with supertype "Identifier"
1310 # Superclass: def __hash__(self: str) -> int
1311 # Subclass: def __hash__(self) -> int
1312 # NOTE for type ignore: This can possibly be fixed by changing how __hash__ is implemented in Identifier
1313 def __hash__(self) -> int: # type: ignore[override]
1314 """Hash function for Literals to enable their use as dictionary keys.
1315
1316 Example:
1317 ```python
1318 from rdflib.namespace import XSD
1319 a = {Literal('1', datatype=XSD.integer):'one'}
1320 Literal('1', datatype=XSD.double) in a
1321 # False
1322 ```
1323
1324 Notes:
1325 "Called for the key object for dictionary operations,
1326 and by the built-in function hash(). Should return
1327 a 32-bit integer usable as a hash value for
1328 dictionary operations. The only required property
1329 is that objects which compare equal have the same
1330 hash value; it is advised to somehow mix together
1331 (e.g., using exclusive or) the hash values for the
1332 components of the object that also play a part in
1333 comparison of objects." -- 3.4.1 Basic customization (Python)
1334
1335 "Two literals are equal if and only if all of the following hold:
1336 * The strings of the two lexical forms compare equal, character by character.
1337 * Either both or neither have language tags.
1338 * The language tags, if any, compare equal.
1339 * Either both or neither have datatype URIs.
1340 * The two datatype URIs, if any, compare equal, character by character."
1341 -- 6.5.1 Literal Equality (RDF: Concepts and Abstract Syntax)
1342 """
1343 # don't use super()... for efficiency reasons, see Identifier.__hash__
1344 res = str.__hash__(self)
1345 # Directly accessing the member is faster than the property.
1346 if self._language:
1347 res ^= hash(self._language.lower())
1348 if self._datatype is not None:
1349 res ^= hash(self._datatype)
1350 return res
1351
1352 def __eq__(self, other: Any) -> bool:
1353 """Equality operator for Literals.
1354
1355 Literals are only equal to other literals.
1356
1357 Notes:
1358 "Two literals are equal if and only if all of the following hold:
1359 * The strings of the two lexical forms compare equal, character by character.
1360 * Either both or neither have language tags.
1361 * The language tags, if any, compare equal.
1362 * Either both or neither have datatype URIs.
1363 * The two datatype URIs, if any, compare equal, character by character."
1364 -- 6.5.1 Literal Equality (RDF: Concepts and Abstract Syntax)
1365
1366 Example:
1367 ```python
1368 Literal("1", datatype=URIRef("foo")) == Literal("1", datatype=URIRef("foo"))
1369 # True
1370 Literal("1", datatype=URIRef("foo")) == Literal("1", datatype=URIRef("foo2"))
1371 # False
1372
1373 Literal("1", datatype=URIRef("foo")) == Literal("2", datatype=URIRef("foo"))
1374 # False
1375 Literal("1", datatype=URIRef("foo")) == "asdf"
1376 # False
1377
1378 from rdflib import XSD
1379 Literal('2007-01-01', datatype=XSD.date) == Literal('2007-01-01', datatype=XSD.date)
1380 # True
1381 Literal('2007-01-01', datatype=XSD.date) == date(2007, 1, 1)
1382 # False
1383
1384 Literal("one", lang="en") == Literal("one", lang="en")
1385 # True
1386 Literal("hast", lang='en') == Literal("hast", lang='de')
1387 # False
1388
1389 Literal("1", datatype=XSD.integer) == Literal(1)
1390 # True
1391 Literal("1", datatype=XSD.integer) == Literal("01", datatype=XSD.integer)
1392 # True
1393 ```
1394 """
1395 if self is other:
1396 return True
1397 if other is None:
1398 return False
1399 # Directly accessing the member is faster than the property.
1400 if isinstance(other, Literal):
1401 return (
1402 self._datatype == other._datatype
1403 and (self._language.lower() if self._language else None)
1404 == (other._language.lower() if other._language else None)
1405 and str.__eq__(self, other)
1406 )
1407
1408 return False
1409
1410 def eq(self, other: Any) -> bool:
1411 """Compare the value of this literal with something else.
1412
1413 This comparison can be done in two ways:
1414
1415 1. With the value of another literal - comparisons are then done in literal "value space"
1416 according to the rules of XSD subtype-substitution/type-promotion
1417
1418 2. With a Python object:
1419 * string objects can be compared with plain-literals or those with datatype xsd:string
1420 * bool objects with xsd:boolean
1421 * int, long or float with numeric xsd types
1422 * date, time, datetime objects with xsd:date, xsd:time, xsd:datetime
1423
1424 Any other operations returns NotImplemented.
1425 """
1426 if isinstance(other, Literal):
1427 # Fast path for comparing numeric literals
1428 # that are not ill-typed and don't have a None value
1429 if (
1430 (
1431 self.datatype in _NUMERIC_LITERAL_TYPES
1432 and other.datatype in _NUMERIC_LITERAL_TYPES
1433 )
1434 and ((not self.ill_typed) and (not other.ill_typed))
1435 and (self.value is not None and other.value is not None)
1436 ):
1437 if self.value is not None and other.value is not None:
1438 return self.value == other.value
1439 else:
1440 if str.__eq__(self, other):
1441 return True
1442 raise TypeError(
1443 # TODO: Should this use repr strings in the error message?
1444 "I cannot know that these two lexical forms do not map to the "
1445 f"same value: {self} and {other}"
1446 )
1447 if (self.language or "").lower() != (other.language or "").lower():
1448 return False
1449
1450 dtself = rdflib.util._coalesce(self.datatype, default=_XSD_STRING)
1451 dtother = rdflib.util._coalesce(other.datatype, default=_XSD_STRING)
1452
1453 if dtself == _XSD_STRING and dtother == _XSD_STRING:
1454 # string/plain literals, compare on lexical form
1455 return str.__eq__(self, other)
1456
1457 # XML can be compared to HTML, only if html5rdf is enabled
1458 if (
1459 (dtself in _XML_COMPARABLE and dtother in _XML_COMPARABLE)
1460 and
1461 # Ill-typed can be None if unknown, but we don't want it to be True.
1462 ((self.ill_typed is not True) and (other.ill_typed is not True))
1463 and (self.value is not None and other.value is not None)
1464 ):
1465 return _isEqualXMLNode(self.value, other.value)
1466
1467 if dtself != dtother:
1468 if rdflib.DAWG_LITERAL_COLLATION:
1469 raise TypeError(
1470 f"I don't know how to compare literals with datatypes {self.datatype} and {other.datatype}"
1471 )
1472 else:
1473 return False
1474
1475 # matching non-string DTs now - do we compare values or
1476 # lexical form first? comparing two ints is far quicker -
1477 # maybe there are counter examples
1478
1479 if self.value is not None and other.value is not None:
1480 return self.value == other.value
1481 else:
1482 if str.__eq__(self, other):
1483 return True
1484
1485 if self.datatype == _XSD_STRING:
1486 return False # string value space=lexical space
1487
1488 # matching DTs, but not matching, we cannot compare!
1489 raise TypeError(
1490 # TODO: Should this use repr strings in the error message?
1491 "I cannot know that these two lexical forms do not map to the same "
1492 f"value: {self} and {other}"
1493 )
1494
1495 elif isinstance(other, Node):
1496 return False # no non-Literal nodes are equal to a literal
1497
1498 elif isinstance(other, str):
1499 # only plain-literals can be directly compared to strings
1500
1501 # TODO: Is "blah"@en eq "blah" ?
1502 if self.language is not None:
1503 return False
1504
1505 if self.datatype == _XSD_STRING or self.datatype is None:
1506 return str(self) == other
1507
1508 elif isinstance(other, (int, long_type, float)):
1509 if self.datatype in _NUMERIC_LITERAL_TYPES:
1510 return self.value == other
1511 elif isinstance(other, (date, datetime, time)):
1512 if self.datatype in (_XSD_DATETIME, _XSD_DATE, _XSD_TIME):
1513 return self.value == other
1514 elif isinstance(other, (timedelta, Duration)):
1515 if self.datatype in (
1516 _XSD_DURATION,
1517 _XSD_DAYTIMEDURATION,
1518 _XSD_YEARMONTHDURATION,
1519 ):
1520 return self.value == other
1521 # NOTE for type ignore: bool is a subclass of int so this won't ever run.
1522 elif isinstance(other, bool): # type: ignore[unreachable, unused-ignore]
1523 if self.datatype == _XSD_BOOLEAN:
1524 return self.value == other
1525
1526 return NotImplemented
1527
1528 def neq(self, other: Any) -> bool:
1529 return not self.eq(other)
1530
1531 def n3(self, namespace_manager: Optional[NamespaceManager] = None) -> str:
1532 r'''Returns a representation in the N3 format.
1533
1534 ```python
1535 >>> Literal("foo").n3()
1536 '"foo"'
1537
1538 ```
1539
1540 Strings with newlines or triple-quotes:
1541
1542 ```python
1543 >>> Literal("foo\nbar").n3()
1544 '"""foo\nbar"""'
1545 >>> Literal("''\'").n3()
1546 '"\'\'\'"'
1547 >>> Literal('"""').n3()
1548 '"\\"\\"\\""'
1549
1550 ```
1551
1552 Language:
1553
1554 ```python
1555 >>> Literal("hello", lang="en").n3()
1556 '"hello"@en'
1557
1558 ```
1559
1560 Datatypes:
1561
1562 ```python
1563 >>> Literal(1).n3()
1564 '"1"^^<http://www.w3.org/2001/XMLSchema#integer>'
1565 >>> Literal(1.0).n3()
1566 '"1.0"^^<http://www.w3.org/2001/XMLSchema#double>'
1567 >>> Literal(True).n3()
1568 '"true"^^<http://www.w3.org/2001/XMLSchema#boolean>'
1569
1570 ```
1571
1572 Datatype and language isn't allowed (datatype takes precedence):
1573
1574 ```python
1575 >>> Literal(1, lang="en").n3()
1576 '"1"^^<http://www.w3.org/2001/XMLSchema#integer>'
1577
1578 ```
1579
1580 Custom datatype:
1581
1582 ```python
1583 >>> footype = URIRef("http://example.org/ns#foo")
1584 >>> Literal("1", datatype=footype).n3()
1585 '"1"^^<http://example.org/ns#foo>'
1586
1587 ```
1588
1589 Passing a namespace-manager will use it to abbreviate datatype URIs:
1590
1591 ```python
1592 >>> from rdflib import Graph
1593 >>> Literal(1).n3(Graph().namespace_manager)
1594 '"1"^^xsd:integer'
1595
1596 ```
1597 '''
1598 if namespace_manager:
1599 return self._literal_n3(qname_callback=namespace_manager.normalizeUri)
1600 else:
1601 return self._literal_n3()
1602
1603 def _literal_n3(
1604 self,
1605 use_plain: bool = False,
1606 qname_callback: Optional[Callable[[URIRef], Optional[str]]] = None,
1607 ) -> str:
1608 """Internal method for N3 serialization with more options.
1609
1610 Args:
1611 use_plain: Whether to use plain literal (shorthand) output
1612 qname_callback: Function to convert URIs to prefixed names
1613
1614 Example:
1615 Using plain literal (shorthand) output:
1616
1617 ```python
1618 >>> from rdflib.namespace import XSD
1619
1620 >>> Literal(1)._literal_n3(use_plain=True)
1621 '1'
1622
1623 >>> Literal(1.0)._literal_n3(use_plain=True)
1624 '1e+00'
1625
1626 >>> Literal(1.0, datatype=XSD.decimal)._literal_n3(use_plain=True)
1627 '1.0'
1628
1629 >>> Literal(1.0, datatype=XSD.float)._literal_n3(use_plain=True)
1630 '"1.0"^^<http://www.w3.org/2001/XMLSchema#float>'
1631
1632 >>> Literal("foo", datatype=XSD.string)._literal_n3(use_plain=True)
1633 '"foo"^^<http://www.w3.org/2001/XMLSchema#string>'
1634
1635 >>> Literal(True)._literal_n3(use_plain=True)
1636 'true'
1637
1638 >>> Literal(False)._literal_n3(use_plain=True)
1639 'false'
1640
1641 >>> Literal(1.91)._literal_n3(use_plain=True)
1642 '1.91e+00'
1643
1644 ```
1645
1646 Only limited precision available for floats:
1647
1648 ```python
1649 >>> Literal(0.123456789)._literal_n3(use_plain=True)
1650 '1.234568e-01'
1651
1652 >>> Literal('0.123456789', datatype=XSD.decimal)._literal_n3(use_plain=True)
1653 '0.123456789'
1654
1655 ```
1656
1657 Using callback for datatype QNames:
1658
1659 ```python
1660 >>> Literal(1)._literal_n3(qname_callback=lambda uri: "xsd:integer")
1661 '"1"^^xsd:integer'
1662
1663 ```
1664 """
1665 if use_plain and self.datatype in _PLAIN_LITERAL_TYPES:
1666 if self.value is not None:
1667 # If self is inf or NaN, we need a datatype
1668 # (there is no plain representation)
1669 if self.datatype in _NUMERIC_INF_NAN_LITERAL_TYPES:
1670 try:
1671 v = float(self)
1672 if math.isinf(v) or math.isnan(v):
1673 return self._literal_n3(False, qname_callback)
1674 except ValueError:
1675 return self._literal_n3(False, qname_callback)
1676
1677 # this is a bit of a mess -
1678 # we try to produce "pretty" output
1679 # that is compatible with n3 (turtle) notation
1680 if self.datatype == _XSD_DOUBLE:
1681 return sub("\\.?0*e", "e", f"{float(self):e}")
1682 elif self.datatype == _XSD_DECIMAL:
1683 s = f"{self}" # f"{self}" is faster than "%s" % self and str(self)
1684 if "." not in s and "e" not in s and "E" not in s:
1685 s += ".0"
1686 return s
1687 elif self.datatype == _XSD_BOOLEAN:
1688 return f"{self}".lower()
1689 else:
1690 return f"{self}"
1691
1692 encoded: str = self._quote_encode()
1693
1694 datatype = self.datatype
1695 quoted_dt = None
1696 if datatype is not None:
1697 if qname_callback:
1698 quoted_dt = qname_callback(datatype)
1699 if not quoted_dt:
1700 quoted_dt = f"<{datatype}>"
1701 if datatype in _NUMERIC_INF_NAN_LITERAL_TYPES:
1702 try:
1703 v = float(self)
1704 if math.isinf(v):
1705 # py string reps: float: 'inf', Decimal: 'Infinity"
1706 # both need to become "INF" in xsd datatypes
1707 encoded = encoded.replace("inf", "INF").replace(
1708 "Infinity", "INF"
1709 )
1710 if math.isnan(v):
1711 encoded = encoded.replace("nan", "NaN")
1712 except ValueError:
1713 # if we can't cast to float something is wrong, but we can
1714 # still serialize. Warn user about it
1715 warnings.warn(f"Serializing weird numerical {self!r}")
1716
1717 language = self.language
1718 if language:
1719 return f"{encoded}@{language}"
1720 elif datatype:
1721 return f"{encoded}^^{quoted_dt}"
1722 else:
1723 return encoded
1724
1725 def _quote_encode(self) -> str:
1726 # This simpler encoding doesn't work; a newline gets encoded as "\\n",
1727 # which is ok in sourcecode, but we want "\n".
1728 # encoded = self.encode('unicode-escape').replace(
1729 # '\\', '\\\\').replace('"','\\"')
1730 # encoded = self.replace.replace('\\', '\\\\').replace('"','\\"')
1731
1732 # NOTE: Could in theory chose quotes based on quotes appearing in the
1733 # string, i.e. '"' and "'", but N3/turtle doesn't allow "'"(?).
1734
1735 if "\n" in self:
1736 # Triple quote this string.
1737 encoded = self.replace("\\", "\\\\")
1738 if '"""' in self:
1739 # is this ok?
1740 encoded = encoded.replace('"""', '\\"\\"\\"')
1741 if encoded[-1] == '"' and encoded[-2] != "\\":
1742 encoded = encoded[:-1] + "\\" + '"'
1743 # TODO: Replace usage of %s here with fstrings
1744 # when we have ability to escape \r and \n inside
1745 # f-string inline function calls
1746 return '"""%s"""' % encoded.replace("\r", "\\r")
1747 else:
1748 return '"%s"' % self.replace("\n", "\\n").replace("\\", "\\\\").replace(
1749 '"', '\\"'
1750 ).replace("\r", "\\r")
1751
1752 def __repr__(self) -> str:
1753 args = [str.__repr__(self)]
1754 if self.language is not None:
1755 args.append("lang=" + repr(self.language))
1756 if self.datatype is not None:
1757 args.append("datatype=" + repr(self.datatype))
1758 if self.__class__ == Literal:
1759 clsName = "rdflib.term.Literal" # noqa: N806
1760 else:
1761 clsName = self.__class__.__name__ # noqa: N806
1762 return f"{clsName}({', '.join(args)})"
1763
1764 def toPython(self) -> Any: # noqa: N802
1765 """
1766 Returns an appropriate python datatype derived from this RDF Literal
1767 """
1768
1769 if self.value is not None:
1770 return self.value
1771 return self
1772
1773
1774def _parseXML(xmlstring: str) -> xml.dom.minidom.Document: # noqa: N802
1775 retval = xml.dom.minidom.parseString(
1776 f"<rdflibtoplevelelement>{xmlstring}</rdflibtoplevelelement>"
1777 )
1778 retval.normalize()
1779 return retval
1780
1781
1782def _parse_html(lexical_form: str) -> xml.dom.minidom.DocumentFragment:
1783 """
1784 Parse the lexical form of an HTML literal into a document fragment
1785 using the `dom` from html5rdf tree builder.
1786
1787 Args:
1788 lexical_form: The lexical form of the HTML literal.
1789
1790 Returns:
1791 A document fragment representing the HTML literal.
1792
1793 Raises:
1794 html5rdf.html5parser.ParseError: If the lexical form is not valid HTML.
1795 """
1796 parser = html5rdf.HTMLParser(
1797 tree=html5rdf.treebuilders.getTreeBuilder("dom"), strict=True
1798 )
1799 try:
1800 result: xml.dom.minidom.DocumentFragment = parser.parseFragment(lexical_form)
1801 except html5rdf.html5parser.ParseError as e:
1802 logger.info(f"Failed to parse HTML: {e}")
1803 raise e
1804 result.normalize()
1805 return result
1806
1807
1808def _write_html(value: xml.dom.minidom.DocumentFragment) -> bytes:
1809 """
1810 Serialize a document fragment representing an HTML literal into
1811 its lexical form.
1812
1813 Args:
1814 value: A document fragment representing an HTML literal.
1815
1816 Returns:
1817 The lexical form of the HTML literal.
1818 """
1819 result = html5rdf.serialize(value, tree="dom")
1820 return result
1821
1822
1823def _writeXML( # noqa: N802
1824 xmlnode: Union[xml.dom.minidom.Document, xml.dom.minidom.DocumentFragment]
1825) -> bytes:
1826 if isinstance(xmlnode, xml.dom.minidom.DocumentFragment):
1827 d = xml.dom.minidom.Document()
1828 d.childNodes += xmlnode.childNodes
1829 xmlnode = d
1830 s = xmlnode.toxml("utf-8")
1831 # for clean round-tripping, remove headers -- I have great and
1832 # specific worries that this will blow up later, but this margin
1833 # is too narrow to contain them
1834 if s.startswith(b'<?xml version="1.0" encoding="utf-8"?>'):
1835 s = s[38:]
1836 if s.startswith(b"<rdflibtoplevelelement>"):
1837 s = s[23:-24]
1838 if s == b"<rdflibtoplevelelement/>":
1839 s = b""
1840 return s
1841
1842
1843def _unhexlify(value: Union[str, bytes, Literal]) -> bytes:
1844 # In Python 3.2, unhexlify does not support str (only bytes)
1845 if isinstance(value, str):
1846 value = value.encode()
1847 return unhexlify(value)
1848
1849
1850def _parseBoolean(value: Union[str, bytes]) -> bool: # noqa: N802
1851 """
1852 Boolean is a datatype with value space {true,false},
1853 lexical space {"true", "false","1","0"} and
1854 lexical-to-value mapping {"true"→true, "false"→false, "1"→true, "0"→false}.
1855 """
1856 true_accepted_values = ["1", "true", b"1", b"true"]
1857 false_accepted_values = ["0", "false", b"0", b"false"]
1858 new_value = value.lower()
1859 if new_value in true_accepted_values:
1860 return True
1861 if new_value not in false_accepted_values:
1862 warnings.warn(
1863 f"Parsing weird boolean, {value!r} does not map to True or False",
1864 category=UserWarning,
1865 )
1866 return False
1867
1868
1869def _well_formed_by_value(lexical: Union[str, bytes], value: Any) -> bool:
1870 """
1871 This function is used as the fallback for detecting ill-typed/ill-formed
1872 literals and operates on the asumption that if a value (i.e.
1873 `Literal.value`) could be determined for a Literal then it is not
1874 ill-typed/ill-formed.
1875
1876 This function will be called with `Literal.lexical` and `Literal.value` as arguments.
1877 """
1878 return value is not None
1879
1880
1881def _well_formed_unsignedlong(lexical: Union[str, bytes], value: Any) -> bool:
1882 """
1883 xsd:unsignedInteger and xsd:unsignedLong must not be negative
1884 """
1885 return len(lexical) > 0 and isinstance(value, long_type) and value >= 0
1886
1887
1888def _well_formed_boolean(lexical: Union[str, bytes], value: Any) -> bool:
1889 """
1890 Boolean is a datatype with value space {true,false},
1891 lexical space {"true", "false","1","0"} and
1892 lexical-to-value mapping {"true"→true, "false"→false, "1"→true, "0"→false}.
1893 """
1894 return lexical in ("true", b"true", "false", b"false", "1", b"1", "0", b"0")
1895
1896
1897def _well_formed_int(lexical: Union[str, bytes], value: Any) -> bool:
1898 """
1899 The value space of xs:int is the set of common single size integers (32 bits),
1900 i.e., the integers between -2147483648 and 2147483647,
1901 its lexical space allows any number of insignificant leading zeros.
1902 """
1903 return (
1904 len(lexical) > 0
1905 and isinstance(value, int)
1906 and (-2147483648 <= value <= 2147483647)
1907 )
1908
1909
1910def _well_formed_unsignedint(lexical: Union[str, bytes], value: Any) -> bool:
1911 """
1912 xsd:unsignedInt has a 32bit value of between 0 and 4294967295
1913 """
1914 return len(lexical) > 0 and isinstance(value, int) and (0 <= value <= 4294967295)
1915
1916
1917def _well_formed_short(lexical: Union[str, bytes], value: Any) -> bool:
1918 """
1919 The value space of xs:short is the set of common short integers (16 bits),
1920 i.e., the integers between -32768 and 32767,
1921 its lexical space allows any number of insignificant leading zeros.
1922 """
1923 return len(lexical) > 0 and isinstance(value, int) and (-32768 <= value <= 32767)
1924
1925
1926def _well_formed_unsignedshort(lexical: Union[str, bytes], value: Any) -> bool:
1927 """
1928 xsd:unsignedShort has a 16bit value of between 0 and 65535
1929 """
1930 return len(lexical) > 0 and isinstance(value, int) and (0 <= value <= 65535)
1931
1932
1933def _well_formed_byte(lexical: Union[str, bytes], value: Any) -> bool:
1934 """
1935 The value space of xs:byte is the set of common single byte integers (8 bits),
1936 i.e., the integers between -128 and 127,
1937 its lexical space allows any number of insignificant leading zeros.
1938 """
1939 return len(lexical) > 0 and isinstance(value, int) and (-128 <= value <= 127)
1940
1941
1942def _well_formed_unsignedbyte(lexical: Union[str, bytes], value: Any) -> bool:
1943 """
1944 xsd:unsignedByte has a 8bit value of between 0 and 255
1945 """
1946 return len(lexical) > 0 and isinstance(value, int) and (0 <= value <= 255)
1947
1948
1949def _well_formed_non_negative_integer(lexical: Union[str, bytes], value: Any) -> bool:
1950 return isinstance(value, int) and value >= 0
1951
1952
1953def _well_formed_positive_integer(lexical: Union[str, bytes], value: Any) -> bool:
1954 return isinstance(value, int) and value > 0
1955
1956
1957def _well_formed_non_positive_integer(lexical: Union[str, bytes], value: Any) -> bool:
1958 return isinstance(value, int) and value <= 0
1959
1960
1961def _well_formed_negative_integer(lexical: Union[str, bytes], value: Any) -> bool:
1962 return isinstance(value, int) and value < 0
1963
1964
1965# Cannot import Namespace/XSD because of circular dependencies
1966_XSD_PFX = "http://www.w3.org/2001/XMLSchema#"
1967_RDF_PFX = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
1968
1969_RDF_XMLLITERAL = URIRef(_RDF_PFX + "XMLLiteral")
1970_RDF_HTMLLITERAL = URIRef(_RDF_PFX + "HTML")
1971
1972_XSD_STRING = URIRef(_XSD_PFX + "string")
1973_XSD_NORMALISED_STRING = URIRef(_XSD_PFX + "normalizedString")
1974_XSD_TOKEN = URIRef(_XSD_PFX + "token")
1975
1976_XSD_FLOAT = URIRef(_XSD_PFX + "float")
1977_XSD_DOUBLE = URIRef(_XSD_PFX + "double")
1978_XSD_DECIMAL = URIRef(_XSD_PFX + "decimal")
1979_XSD_INTEGER = URIRef(_XSD_PFX + "integer")
1980_XSD_BOOLEAN = URIRef(_XSD_PFX + "boolean")
1981
1982_XSD_DATETIME = URIRef(_XSD_PFX + "dateTime")
1983_XSD_DATE = URIRef(_XSD_PFX + "date")
1984_XSD_TIME = URIRef(_XSD_PFX + "time")
1985_XSD_DURATION = URIRef(_XSD_PFX + "duration")
1986_XSD_DAYTIMEDURATION = URIRef(_XSD_PFX + "dayTimeDuration")
1987_XSD_YEARMONTHDURATION = URIRef(_XSD_PFX + "yearMonthDuration")
1988
1989_OWL_RATIONAL = URIRef("http://www.w3.org/2002/07/owl#rational")
1990_XSD_B64BINARY = URIRef(_XSD_PFX + "base64Binary")
1991_XSD_HEXBINARY = URIRef(_XSD_PFX + "hexBinary")
1992_XSD_GYEAR = URIRef(_XSD_PFX + "gYear")
1993_XSD_GYEARMONTH = URIRef(_XSD_PFX + "gYearMonth")
1994# TODO: gMonthDay, gDay, gMonth
1995
1996_NUMERIC_LITERAL_TYPES: Tuple[URIRef, ...] = (
1997 _XSD_INTEGER,
1998 _XSD_DECIMAL,
1999 _XSD_DOUBLE,
2000 URIRef(_XSD_PFX + "float"),
2001 URIRef(_XSD_PFX + "byte"),
2002 URIRef(_XSD_PFX + "int"),
2003 URIRef(_XSD_PFX + "long"),
2004 URIRef(_XSD_PFX + "negativeInteger"),
2005 URIRef(_XSD_PFX + "nonNegativeInteger"),
2006 URIRef(_XSD_PFX + "nonPositiveInteger"),
2007 URIRef(_XSD_PFX + "positiveInteger"),
2008 URIRef(_XSD_PFX + "short"),
2009 URIRef(_XSD_PFX + "unsignedByte"),
2010 URIRef(_XSD_PFX + "unsignedInt"),
2011 URIRef(_XSD_PFX + "unsignedLong"),
2012 URIRef(_XSD_PFX + "unsignedShort"),
2013)
2014
2015# these have "native" syntax in N3/SPARQL
2016_PLAIN_LITERAL_TYPES: Tuple[URIRef, ...] = (
2017 _XSD_INTEGER,
2018 _XSD_BOOLEAN,
2019 _XSD_DOUBLE,
2020 _XSD_DECIMAL,
2021 _OWL_RATIONAL,
2022)
2023
2024# these have special INF and NaN XSD representations
2025_NUMERIC_INF_NAN_LITERAL_TYPES: Tuple[URIRef, ...] = (
2026 URIRef(_XSD_PFX + "float"),
2027 _XSD_DOUBLE,
2028 _XSD_DECIMAL,
2029)
2030
2031# these need dedicated operators
2032_DATE_AND_TIME_TYPES: Tuple[URIRef, ...] = (
2033 _XSD_DATETIME,
2034 _XSD_DATE,
2035 _XSD_TIME,
2036)
2037
2038# These are recognized datatype IRIs
2039# (https://www.w3.org/TR/rdf11-concepts/#dfn-recognized-datatype-iris) that
2040# represents durations.
2041_TIME_DELTA_TYPES: Tuple[URIRef, ...] = (
2042 _XSD_DURATION,
2043 _XSD_DAYTIMEDURATION,
2044)
2045
2046_ALL_DATE_AND_TIME_TYPES: Tuple[URIRef, ...] = _DATE_AND_TIME_TYPES + _TIME_DELTA_TYPES
2047
2048# the following types need special treatment for reasonable sorting because
2049# certain instances can't be compared to each other. We treat this by
2050# partitioning and then sorting within those partitions.
2051_TOTAL_ORDER_CASTERS: Dict[Type[Any], Callable[[Any], Any]] = {
2052 datetime: lambda value: (
2053 # naive vs. aware
2054 value.tzinfo is not None and value.tzinfo.utcoffset(value) is not None,
2055 value,
2056 ),
2057 time: lambda value: (
2058 # naive vs. aware
2059 value.tzinfo is not None and value.tzinfo.utcoffset(None) is not None,
2060 value,
2061 ),
2062 xml.dom.minidom.Document: lambda value: value.toxml(),
2063}
2064
2065
2066_STRING_LITERAL_TYPES: Tuple[URIRef, ...] = (
2067 _XSD_STRING,
2068 _RDF_XMLLITERAL,
2069 _RDF_HTMLLITERAL,
2070 URIRef(_XSD_PFX + "normalizedString"),
2071 URIRef(_XSD_PFX + "token"),
2072)
2073
2074_StrT = TypeVar("_StrT", bound=str)
2075
2076
2077def _py2literal(
2078 obj: Any,
2079 pType: Any, # noqa: N803
2080 castFunc: Optional[Callable[[Any], Any]], # noqa: N803
2081 dType: Optional[_StrT], # noqa: N803
2082) -> Tuple[Any, Optional[_StrT]]:
2083 if castFunc is not None:
2084 return castFunc(obj), dType
2085 elif dType is not None:
2086 return obj, dType
2087 else:
2088 return obj, None
2089
2090
2091def _castPythonToLiteral( # noqa: N802
2092 obj: Any, datatype: Optional[str]
2093) -> Tuple[Any, Optional[str]]:
2094 """
2095 Casts a tuple of a python type and a special datatype URI to a tuple of the lexical value and a
2096 datatype URI (or None)
2097 """
2098 castFunc: Optional[Callable[[Any], Union[str, bytes]]] # noqa: N806
2099 dType: Optional[str] # noqa: N806
2100 for (pType, dType), castFunc in _SpecificPythonToXSDRules: # noqa: N806
2101 if isinstance(obj, pType) and dType == datatype:
2102 return _py2literal(obj, pType, castFunc, dType)
2103
2104 for pType, (castFunc, dType) in _GenericPythonToXSDRules: # noqa: N806
2105 if isinstance(obj, pType):
2106 return _py2literal(obj, pType, castFunc, dType)
2107 return obj, None # TODO: is this right for the fall through case?
2108
2109
2110# Mappings from Python types to XSD datatypes and back (borrowed from sparta)
2111# datetime instances are also instances of date... so we need to order these.
2112
2113# SPARQL/Turtle/N3 has shortcuts for integer, double, decimal
2114# python has only float - to be in tune with sparql/n3/turtle
2115# we default to XSD.double for float literals
2116
2117# python ints are promoted to longs when overflowing
2118# python longs have no limit
2119# both map to the abstract integer type,
2120# rather than some concrete bit-limited datatype
2121_GenericPythonToXSDRules: List[
2122 Tuple[Type[Any], Tuple[Optional[Callable[[Any], Union[str, bytes]]], Optional[str]]]
2123] = [
2124 (str, (None, None)),
2125 (float, (None, _XSD_DOUBLE)),
2126 (bool, (lambda i: str(i).lower(), _XSD_BOOLEAN)),
2127 (int, (None, _XSD_INTEGER)),
2128 (long_type, (None, _XSD_INTEGER)),
2129 (Decimal, (lambda i: f"{i:f}", _XSD_DECIMAL)),
2130 (datetime, (lambda i: i.isoformat(), _XSD_DATETIME)),
2131 (date, (lambda i: i.isoformat(), _XSD_DATE)),
2132 (time, (lambda i: i.isoformat(), _XSD_TIME)),
2133 (Duration, (lambda i: duration_isoformat(i), _XSD_DURATION)),
2134 (timedelta, (lambda i: duration_isoformat(i), _XSD_DAYTIMEDURATION)),
2135 (xml.dom.minidom.Document, (_writeXML, _RDF_XMLLITERAL)),
2136 (Fraction, (None, _OWL_RATIONAL)),
2137]
2138
2139if html5rdf is not None:
2140 # This is a bit dirty, by accident the html5rdf parser produces
2141 # DocumentFragments, and the xml parser Documents, letting this
2142 # decide what datatype to use makes roundtripping easier, but its a
2143 # bit random.
2144
2145 # This must happen before _GenericPythonToXSDRules is assigned to
2146 # _OriginalGenericPythonToXSDRules.
2147 _GenericPythonToXSDRules.append(
2148 (xml.dom.minidom.DocumentFragment, (_write_html, _RDF_HTMLLITERAL))
2149 )
2150
2151_OriginalGenericPythonToXSDRules = list(_GenericPythonToXSDRules)
2152
2153_SpecificPythonToXSDRules: List[
2154 Tuple[Tuple[Type[Any], str], Optional[Callable[[Any], Union[str, bytes]]]]
2155] = [
2156 ((date, _XSD_GYEAR), lambda val: val.strftime("%Y").zfill(4)),
2157 ((date, _XSD_GYEARMONTH), lambda val: val.strftime("%Y-%m").zfill(7)),
2158 ((str, _XSD_HEXBINARY), hexlify),
2159 ((bytes, _XSD_HEXBINARY), hexlify),
2160 ((str, _XSD_B64BINARY), b64encode),
2161 ((bytes, _XSD_B64BINARY), b64encode),
2162]
2163
2164_OriginalSpecificPythonToXSDRules = list(_SpecificPythonToXSDRules)
2165
2166XSDToPython: Dict[Optional[str], Optional[Callable[[str], Any]]] = {
2167 None: None, # plain literals map directly to value space
2168 URIRef(_XSD_PFX + "time"): parse_time,
2169 URIRef(_XSD_PFX + "date"): parse_xsd_date,
2170 URIRef(_XSD_PFX + "dateTime"): parse_datetime,
2171 URIRef(_XSD_PFX + "duration"): parse_xsd_duration,
2172 URIRef(_XSD_PFX + "dayTimeDuration"): parse_xsd_duration,
2173 URIRef(_XSD_PFX + "yearMonthDuration"): parse_xsd_duration,
2174 URIRef(_XSD_PFX + "hexBinary"): _unhexlify,
2175 URIRef(_XSD_PFX + "string"): None,
2176 URIRef(_XSD_PFX + "normalizedString"): None,
2177 URIRef(_XSD_PFX + "token"): None,
2178 URIRef(_XSD_PFX + "language"): None,
2179 URIRef(_XSD_PFX + "boolean"): _parseBoolean,
2180 URIRef(_XSD_PFX + "decimal"): Decimal,
2181 URIRef(_XSD_PFX + "integer"): long_type,
2182 URIRef(_XSD_PFX + "nonPositiveInteger"): long_type,
2183 URIRef(_XSD_PFX + "long"): long_type,
2184 URIRef(_XSD_PFX + "nonNegativeInteger"): long_type,
2185 URIRef(_XSD_PFX + "negativeInteger"): long_type,
2186 URIRef(_XSD_PFX + "int"): int,
2187 URIRef(_XSD_PFX + "unsignedLong"): long_type,
2188 URIRef(_XSD_PFX + "positiveInteger"): long_type,
2189 URIRef(_XSD_PFX + "short"): int,
2190 URIRef(_XSD_PFX + "unsignedInt"): int,
2191 URIRef(_XSD_PFX + "byte"): int,
2192 URIRef(_XSD_PFX + "unsignedShort"): int,
2193 URIRef(_XSD_PFX + "unsignedByte"): int,
2194 URIRef(_XSD_PFX + "float"): float,
2195 URIRef(_XSD_PFX + "double"): float,
2196 URIRef(_XSD_PFX + "base64Binary"): b64decode,
2197 URIRef(_XSD_PFX + "anyURI"): None,
2198 _RDF_XMLLITERAL: _parseXML,
2199}
2200
2201if html5rdf is not None:
2202 # It is probably best to keep this close to the definition of
2203 # _GenericPythonToXSDRules so nobody misses it.
2204 XSDToPython[_RDF_HTMLLITERAL] = _parse_html
2205 _XML_COMPARABLE: Tuple[URIRef, ...] = (_RDF_XMLLITERAL, _RDF_HTMLLITERAL)
2206else:
2207 _XML_COMPARABLE = (_RDF_XMLLITERAL,)
2208
2209_check_well_formed_types: Dict[URIRef, Callable[[Union[str, bytes], Any], bool]] = {
2210 URIRef(_XSD_PFX + "boolean"): _well_formed_boolean,
2211 URIRef(_XSD_PFX + "nonPositiveInteger"): _well_formed_non_positive_integer,
2212 URIRef(_XSD_PFX + "nonNegativeInteger"): _well_formed_non_negative_integer,
2213 URIRef(_XSD_PFX + "negativeInteger"): _well_formed_negative_integer,
2214 URIRef(_XSD_PFX + "positiveInteger"): _well_formed_positive_integer,
2215 URIRef(_XSD_PFX + "int"): _well_formed_int,
2216 URIRef(_XSD_PFX + "short"): _well_formed_short,
2217 URIRef(_XSD_PFX + "byte"): _well_formed_byte,
2218 URIRef(_XSD_PFX + "unsignedInt"): _well_formed_unsignedint,
2219 URIRef(_XSD_PFX + "unsignedLong"): _well_formed_unsignedlong,
2220 URIRef(_XSD_PFX + "unsignedShort"): _well_formed_unsignedshort,
2221 URIRef(_XSD_PFX + "unsignedByte"): _well_formed_unsignedbyte,
2222}
2223
2224_toPythonMapping: Dict[Optional[str], Optional[Callable[[str], Any]]] = {} # noqa: N816
2225
2226_toPythonMapping.update(XSDToPython)
2227
2228
2229def _reset_bindings() -> None:
2230 """Reset lexical<->value space binding for `Literal`."""
2231 _toPythonMapping.clear()
2232 _toPythonMapping.update(XSDToPython)
2233
2234 _GenericPythonToXSDRules.clear()
2235 _GenericPythonToXSDRules.extend(_OriginalGenericPythonToXSDRules)
2236
2237 _SpecificPythonToXSDRules.clear()
2238 _SpecificPythonToXSDRules.extend(_OriginalSpecificPythonToXSDRules)
2239
2240
2241def _castLexicalToPython( # noqa: N802
2242 lexical: Union[str, bytes], datatype: Optional[URIRef]
2243) -> Any:
2244 """Map a lexical form to the value-space for the given datatype.
2245
2246 Returns:
2247 A python object for the value or `None`
2248 """
2249 try:
2250 conv_func = _toPythonMapping[datatype]
2251 except KeyError:
2252 # no conv_func -> unknown data-type
2253 return None
2254
2255 if conv_func is not None:
2256 try:
2257 # type error: Argument 1 has incompatible type "Union[str, bytes]"; expected "str"
2258 # NOTE for type ignore: various functions in _toPythonMapping will
2259 # only work for str, so there is some inconsistency here, the right
2260 # approach may be to change lexical to be of str type but this will
2261 # require runtime changes.
2262 return conv_func(lexical) # type: ignore[arg-type]
2263 except Exception:
2264 logger.warning(
2265 f"Failed to convert Literal lexical form to value. Datatype={datatype}, Converter={conv_func}",
2266 exc_info=True,
2267 )
2268 # not a valid lexical representation for this dt
2269 return None
2270 else:
2271 # no conv func means 1-1 lexical<->value-space mapping
2272 try:
2273 return str(lexical)
2274 except UnicodeDecodeError:
2275 # type error: Argument 1 to "str" has incompatible type "Union[str, bytes]"; expected "bytes"
2276 # NOTE for type ignore: code assumes that lexical is of type bytes
2277 # at this point.
2278 return str(lexical, "utf-8") # type: ignore[arg-type]
2279
2280
2281_AnyT = TypeVar("_AnyT", bound=Any)
2282
2283
2284def _normalise_XSD_STRING(lexical_or_value: _AnyT) -> _AnyT: # noqa: N802
2285 """Replaces \\t, \\n, \\r (#x9 (tab), #xA (linefeed), and #xD (carriage return)) with space without any whitespace collapsing."""
2286 if isinstance(lexical_or_value, str):
2287 # type error: Incompatible return value type (got "str", expected "_AnyT") [return-value]
2288 # NOTE for type ignore: this is an issue with mypy: https://github.com/python/mypy/issues/10003
2289 return lexical_or_value.replace("\t", " ").replace("\n", " ").replace("\r", " ") # type: ignore[return-value]
2290 return lexical_or_value
2291
2292
2293def _strip_and_collapse_whitespace(lexical_or_value: _AnyT) -> _AnyT:
2294 if isinstance(lexical_or_value, str):
2295 # Use regex to substitute contiguous whitespace into a single whitespace. Strip trailing whitespace.
2296 # type error: Incompatible return value type (got "str", expected "_AnyT") [return-value]
2297 # NOTE for type ignore: this is an issue with mypy: https://github.com/python/mypy/issues/10003
2298 return re.sub(" +", " ", lexical_or_value.strip()) # type: ignore[return-value]
2299 return lexical_or_value
2300
2301
2302def bind(
2303 datatype: str,
2304 pythontype: Type[Any],
2305 constructor: Optional[Callable[[str], Any]] = None,
2306 lexicalizer: Optional[Callable[[Any], Union[str, bytes]]] = None,
2307 datatype_specific: bool = False,
2308) -> None:
2309 """
2310 register a new datatype<->pythontype binding
2311
2312 Args:
2313 constructor: An optional function for converting lexical forms
2314 into a Python instances, if not given the pythontype
2315 is used directly
2316 lexicalizer: An optional function for converting python objects to
2317 lexical form, if not given object.__str__ is used
2318 datatype_specific: Makes the lexicalizer function be accessible
2319 from the pair (pythontype, datatype) if set to True
2320 or from the pythontype otherwise. False by default
2321 """
2322 if datatype_specific and datatype is None:
2323 raise Exception("No datatype given for a datatype-specific binding")
2324
2325 if datatype in _toPythonMapping:
2326 logger.warning(f"datatype '{datatype}' was already bound. Rebinding.")
2327
2328 if constructor is None:
2329 constructor = pythontype
2330 _toPythonMapping[datatype] = constructor
2331 if datatype_specific:
2332 _SpecificPythonToXSDRules.append(((pythontype, datatype), lexicalizer))
2333 else:
2334 _GenericPythonToXSDRules.append((pythontype, (lexicalizer, datatype)))
2335
2336
2337class Variable(Identifier):
2338 """
2339 A Variable - this is used for querying, or in Formula aware
2340 graphs, where Variables can be stored
2341 """
2342
2343 __slots__ = ()
2344
2345 def __new__(cls, value: str):
2346 if len(value) == 0:
2347 raise Exception("Attempted to create variable with empty string as name!")
2348 if value[0] == "?":
2349 value = value[1:]
2350 return str.__new__(cls, value)
2351
2352 def __repr__(self) -> str:
2353 if self.__class__ is Variable:
2354 clsName = "rdflib.term.Variable" # noqa: N806
2355 else:
2356 clsName = self.__class__.__name__ # noqa: N806
2357
2358 return f"{clsName}({str.__repr__(self)})"
2359
2360 def toPython(self) -> str: # noqa: N802
2361 return "?" + self
2362
2363 def n3(self, namespace_manager: Optional[NamespaceManager] = None) -> str:
2364 return "?" + self
2365
2366 def __reduce__(self) -> Tuple[Type[Variable], Tuple[str]]:
2367 return (Variable, (str(self),))
2368
2369
2370# Nodes are ordered like this
2371# See http://www.w3.org/TR/sparql11-query/#modOrderBy
2372# we leave "space" for more subclasses of Node elsewhere
2373# default-dict to grazefully fail for new subclasses
2374_ORDERING: Dict[Type[Node], int] = defaultdict(int)
2375_ORDERING.update({BNode: 10, Variable: 20, URIRef: 30, Literal: 40})
2376
2377
2378def _isEqualXMLNode( # noqa: N802
2379 node: Union[
2380 None,
2381 xml.dom.minidom.Attr,
2382 xml.dom.minidom.Comment,
2383 xml.dom.minidom.Document,
2384 xml.dom.minidom.DocumentFragment,
2385 xml.dom.minidom.DocumentType,
2386 xml.dom.minidom.Element,
2387 xml.dom.minidom.Entity,
2388 xml.dom.minidom.Notation,
2389 xml.dom.minidom.ProcessingInstruction,
2390 xml.dom.minidom.Text,
2391 ],
2392 other: Union[
2393 None,
2394 xml.dom.minidom.Attr,
2395 xml.dom.minidom.Comment,
2396 xml.dom.minidom.Document,
2397 xml.dom.minidom.DocumentFragment,
2398 xml.dom.minidom.DocumentType,
2399 xml.dom.minidom.Element,
2400 xml.dom.minidom.Entity,
2401 xml.dom.minidom.Notation,
2402 xml.dom.minidom.ProcessingInstruction,
2403 xml.dom.minidom.Text,
2404 ],
2405) -> bool:
2406 # importing xml.dom.minidom.Node as XMLNode to avoid confusion with
2407 # rdflib.term.Node
2408 from xml.dom.minidom import Node as XMLNode
2409
2410 def recurse():
2411 # Recursion through the children
2412 # In Python2, the semantics of 'map' is such that the check on
2413 # length would be unnecessary. In Python 3,
2414 # the semantics of map has changed (why, oh why???) and the check
2415 # for the length becomes necessary...
2416 # type error: Item "None" of "Union[None, Attr, Comment, Document, DocumentFragment, DocumentType, Element, Entity, Notation, ProcessingInstruction, Text]" has no attribute "childNodes"
2417 if len(node.childNodes) != len(other.childNodes): # type: ignore[union-attr]
2418 return False
2419 # type error: Item "None" of "Union[None, Attr, Comment, Document, DocumentFragment, DocumentType, Element, Entity, Notation, ProcessingInstruction, Text]" has no attribute "childNodes"
2420 for nc, oc in map(lambda x, y: (x, y), node.childNodes, other.childNodes): # type: ignore[union-attr]
2421 if not _isEqualXMLNode(nc, oc):
2422 return False
2423 # if we got here then everything is fine:
2424 return True
2425
2426 if node is None or other is None:
2427 return False
2428
2429 if node.nodeType != other.nodeType:
2430 return False
2431
2432 if node.nodeType in [XMLNode.DOCUMENT_NODE, XMLNode.DOCUMENT_FRAGMENT_NODE]:
2433 return recurse()
2434
2435 elif node.nodeType == XMLNode.ELEMENT_NODE:
2436 if TYPE_CHECKING:
2437 assert isinstance(node, xml.dom.minidom.Element)
2438 assert isinstance(other, xml.dom.minidom.Element)
2439 # Get the basics right
2440 if not (
2441 node.tagName == other.tagName and node.namespaceURI == other.namespaceURI
2442 ):
2443 return False
2444
2445 # Handle the (namespaced) attributes; the namespace setting key
2446 # should be ignored, though
2447 # Note that the minidom orders the keys already, so we do not have
2448 # to worry about that, which is a bonus...
2449 n_keys = [
2450 k
2451 for k in node.attributes.keysNS()
2452 if k[0] != "http://www.w3.org/2000/xmlns/"
2453 ]
2454 o_keys = [
2455 k
2456 for k in other.attributes.keysNS()
2457 if k[0] != "http://www.w3.org/2000/xmlns/"
2458 ]
2459 if len(n_keys) != len(o_keys):
2460 return False
2461 for k in n_keys:
2462 if not (
2463 k in o_keys
2464 and node.getAttributeNS(k[0], k[1]) == other.getAttributeNS(k[0], k[1])
2465 ):
2466 return False
2467
2468 # if we got here, the attributes are all right, we can go down
2469 # the tree recursively
2470 return recurse()
2471
2472 elif node.nodeType in [
2473 XMLNode.TEXT_NODE,
2474 XMLNode.COMMENT_NODE,
2475 XMLNode.CDATA_SECTION_NODE,
2476 XMLNode.NOTATION_NODE,
2477 ]:
2478 if TYPE_CHECKING:
2479 assert isinstance(
2480 node,
2481 (
2482 xml.dom.minidom.Text,
2483 xml.dom.minidom.Comment,
2484 xml.dom.minidom.CDATASection,
2485 xml.dom.minidom.Notation,
2486 ),
2487 )
2488 assert isinstance(
2489 other,
2490 (
2491 xml.dom.minidom.Text,
2492 xml.dom.minidom.Comment,
2493 xml.dom.minidom.CDATASection,
2494 xml.dom.minidom.Notation,
2495 ),
2496 )
2497 # type error: Item "Notation" of "Union[Comment, Document, Notation, Text]" has no attribute "data"
2498 return node.data == other.data # type: ignore[union-attr] # FIXME
2499
2500 elif node.nodeType == XMLNode.PROCESSING_INSTRUCTION_NODE:
2501 if TYPE_CHECKING:
2502 assert isinstance(node, xml.dom.minidom.ProcessingInstruction)
2503 assert isinstance(other, xml.dom.minidom.ProcessingInstruction)
2504 return node.data == other.data and node.target == other.target
2505
2506 elif node.nodeType == XMLNode.ENTITY_NODE:
2507 return node.nodeValue == other.nodeValue
2508
2509 elif node.nodeType == XMLNode.DOCUMENT_TYPE_NODE:
2510 if TYPE_CHECKING:
2511 assert isinstance(node, xml.dom.minidom.DocumentType)
2512 assert isinstance(other, xml.dom.minidom.DocumentType)
2513 return node.publicId == other.publicId and node.systemId == other.systemId
2514
2515 else:
2516 # should not happen, in fact
2517 raise Exception(f"I dont know how to compare XML Node type: {node.nodeType}")