Source code

Download source archive ↓

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}")