style: modernize docstrings (#2575)

Eliminate the use of `__doc__` where it is not needed, and move module
docstrings to the top of the files.

rdflib/collection.py

@@ -12,7 +12,7 @@
 
 
 class Collection:
-    __doc__ = """
+    """
     See "Emulating container types":
     https://docs.python.org/reference/datamodel.html#emulating-container-types
 

rdflib/events.py

@@ -1,6 +1,4 @@
-from __future__ import annotations
-
-__doc__ = """
+"""
 Dirt Simple Events
 
 A Dispatcher (or a subclass of Dispatcher) stores event handlers that
@@ -25,6 +23,7 @@
   <rdflib.events.Event ['data', 'foo', 'used_by']>
 """
 
+from __future__ import annotations
 
 from typing import Any, Dict, Optional
 

rdflib/extras/describer.py

@@ -1,4 +1,4 @@
-__doc__ = """
+"""
 A Describer is a stateful utility for creating RDF statements in a
 semi-declarative manner. It has methods for creating literal values, rel and
 rev resource relations (somewhat resembling RDFa).

rdflib/extras/external_graph_libs.py

@@ -1,12 +1,3 @@
-from __future__ import annotations
-
-import logging
-from typing import TYPE_CHECKING, Any, Dict, List
-
-if TYPE_CHECKING:
-    from rdflib.graph import Graph
-
-
 """Convert (to and) from rdflib graphs to other well known graph libraries.
 
 Currently the following libraries are supported:
@@ -17,6 +8,14 @@
 networkx or graph_tool are available and they would err otherwise.
 see ../../test/test_extras_external_graph_libs.py for conditional tests
 """
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Dict, List
+
+if TYPE_CHECKING:
+    from rdflib.graph import Graph
+
 
 logger = logging.getLogger(__name__)
 

rdflib/extras/infixowl.py

@@ -1,4 +1,4 @@
-__doc__ = """RDFLib Python binding for OWL Abstract Syntax
+"""RDFLib Python binding for OWL Abstract Syntax
 
 OWL Constructor     DL Syntax       Manchester OWL Syntax   Example
 ====================================================================================

rdflib/graph.py

@@ -1,126 +1,4 @@
-from __future__ import annotations
-
-import logging
-import pathlib
-import random
-from io import BytesIO
-from typing import (
-    IO,
-    TYPE_CHECKING,
-    Any,
-    BinaryIO,
-    Callable,
-    Dict,
-    Generator,
-    Iterable,
-    List,
-    Mapping,
-    NoReturn,
-    Optional,
-    Set,
-    TextIO,
-    Tuple,
-    Type,
-    TypeVar,
-    Union,
-    cast,
-    overload,
-)
-from urllib.parse import urlparse
-from urllib.request import url2pathname
-
-import rdflib.exceptions as exceptions
-import rdflib.namespace as namespace  # noqa: F401 # This is here because it is used in a docstring.
-import rdflib.plugin as plugin
-import rdflib.query as query
-import rdflib.util  # avoid circular dependency
-from rdflib.collection import Collection
-from rdflib.exceptions import ParserError
-from rdflib.namespace import RDF, Namespace, NamespaceManager
-from rdflib.parser import InputSource, Parser, create_input_source
-from rdflib.paths import Path
-from rdflib.resource import Resource
-from rdflib.serializer import Serializer
-from rdflib.store import Store
-from rdflib.term import (
-    BNode,
-    Genid,
-    IdentifiedNode,
-    Identifier,
-    Literal,
-    Node,
-    RDFLibGenid,
-    URIRef,
-)
-
-if TYPE_CHECKING:
-    import typing_extensions as te
-
-    import rdflib.query
-    from rdflib.plugins.sparql.sparql import Query, Update
-
-_SubjectType = Node
-_PredicateType = Node
-_ObjectType = Node
-_ContextIdentifierType = IdentifiedNode
-
-_TripleType = Tuple["_SubjectType", "_PredicateType", "_ObjectType"]
-_QuadType = Tuple["_SubjectType", "_PredicateType", "_ObjectType", "_ContextType"]
-_OptionalQuadType = Tuple[
-    "_SubjectType", "_PredicateType", "_ObjectType", Optional["_ContextType"]
-]
-_TripleOrOptionalQuadType = Union["_TripleType", "_OptionalQuadType"]
-_OptionalIdentifiedQuadType = Tuple[
-    "_SubjectType", "_PredicateType", "_ObjectType", Optional["_ContextIdentifierType"]
-]
-_TriplePatternType = Tuple[
-    Optional["_SubjectType"], Optional["_PredicateType"], Optional["_ObjectType"]
-]
-_TriplePathPatternType = Tuple[Optional["_SubjectType"], Path, Optional["_ObjectType"]]
-_QuadPatternType = Tuple[
-    Optional["_SubjectType"],
-    Optional["_PredicateType"],
-    Optional["_ObjectType"],
-    Optional["_ContextType"],
-]
-_QuadPathPatternType = Tuple[
-    Optional["_SubjectType"],
-    Path,
-    Optional["_ObjectType"],
-    Optional["_ContextType"],
-]
-_TripleOrQuadPatternType = Union["_TriplePatternType", "_QuadPatternType"]
-_TripleOrQuadPathPatternType = Union["_TriplePathPatternType", "_QuadPathPatternType"]
-_TripleSelectorType = Tuple[
-    Optional["_SubjectType"],
-    Optional[Union["Path", "_PredicateType"]],
-    Optional["_ObjectType"],
-]
-_QuadSelectorType = Tuple[
-    Optional["_SubjectType"],
-    Optional[Union["Path", "_PredicateType"]],
-    Optional["_ObjectType"],
-    Optional["_ContextType"],
-]
-_TripleOrQuadSelectorType = Union["_TripleSelectorType", "_QuadSelectorType"]
-_TriplePathType = Tuple["_SubjectType", Path, "_ObjectType"]
-_TripleOrTriplePathType = Union["_TripleType", "_TriplePathType"]
-
-_GraphT = TypeVar("_GraphT", bound="Graph")
-_ConjunctiveGraphT = TypeVar("_ConjunctiveGraphT", bound="ConjunctiveGraph")
-_DatasetT = TypeVar("_DatasetT", bound="Dataset")
-
-# type error: Function "Type[Literal]" could always be true in boolean contex
-assert Literal  # type: ignore[truthy-function] # avoid warning
-# type error: Function "Type[Namespace]" could always be true in boolean context
-assert Namespace  # type: ignore[truthy-function] # avoid warning
-
-if TYPE_CHECKING:
-    from rdflib._type_checking import _NamespaceSetString
-
-logger = logging.getLogger(__name__)
-
-__doc__ = """\
+"""\
 
 RDFLib defines the following kinds of Graphs:
 
@@ -366,6 +244,128 @@
 
 """
 
+from __future__ import annotations
+
+import logging
+import pathlib
+import random
+from io import BytesIO
+from typing import (
+    IO,
+    TYPE_CHECKING,
+    Any,
+    BinaryIO,
+    Callable,
+    Dict,
+    Generator,
+    Iterable,
+    List,
+    Mapping,
+    NoReturn,
+    Optional,
+    Set,
+    TextIO,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+    cast,
+    overload,
+)
+from urllib.parse import urlparse
+from urllib.request import url2pathname
+
+import rdflib.exceptions as exceptions
+import rdflib.namespace as namespace  # noqa: F401 # This is here because it is used in a docstring.
+import rdflib.plugin as plugin
+import rdflib.query as query
+import rdflib.util  # avoid circular dependency
+from rdflib.collection import Collection
+from rdflib.exceptions import ParserError
+from rdflib.namespace import RDF, Namespace, NamespaceManager
+from rdflib.parser import InputSource, Parser, create_input_source
+from rdflib.paths import Path
+from rdflib.resource import Resource
+from rdflib.serializer import Serializer
+from rdflib.store import Store
+from rdflib.term import (
+    BNode,
+    Genid,
+    IdentifiedNode,
+    Identifier,
+    Literal,
+    Node,
+    RDFLibGenid,
+    URIRef,
+)
+
+if TYPE_CHECKING:
+    import typing_extensions as te
+
+    import rdflib.query
+    from rdflib.plugins.sparql.sparql import Query, Update
+
+_SubjectType = Node
+_PredicateType = Node
+_ObjectType = Node
+_ContextIdentifierType = IdentifiedNode
+
+_TripleType = Tuple["_SubjectType", "_PredicateType", "_ObjectType"]
+_QuadType = Tuple["_SubjectType", "_PredicateType", "_ObjectType", "_ContextType"]
+_OptionalQuadType = Tuple[
+    "_SubjectType", "_PredicateType", "_ObjectType", Optional["_ContextType"]
+]
+_TripleOrOptionalQuadType = Union["_TripleType", "_OptionalQuadType"]
+_OptionalIdentifiedQuadType = Tuple[
+    "_SubjectType", "_PredicateType", "_ObjectType", Optional["_ContextIdentifierType"]
+]
+_TriplePatternType = Tuple[
+    Optional["_SubjectType"], Optional["_PredicateType"], Optional["_ObjectType"]
+]
+_TriplePathPatternType = Tuple[Optional["_SubjectType"], Path, Optional["_ObjectType"]]
+_QuadPatternType = Tuple[
+    Optional["_SubjectType"],
+    Optional["_PredicateType"],
+    Optional["_ObjectType"],
+    Optional["_ContextType"],
+]
+_QuadPathPatternType = Tuple[
+    Optional["_SubjectType"],
+    Path,
+    Optional["_ObjectType"],
+    Optional["_ContextType"],
+]
+_TripleOrQuadPatternType = Union["_TriplePatternType", "_QuadPatternType"]
+_TripleOrQuadPathPatternType = Union["_TriplePathPatternType", "_QuadPathPatternType"]
+_TripleSelectorType = Tuple[
+    Optional["_SubjectType"],
+    Optional[Union["Path", "_PredicateType"]],
+    Optional["_ObjectType"],
+]
+_QuadSelectorType = Tuple[
+    Optional["_SubjectType"],
+    Optional[Union["Path", "_PredicateType"]],
+    Optional["_ObjectType"],
+    Optional["_ContextType"],
+]
+_TripleOrQuadSelectorType = Union["_TripleSelectorType", "_QuadSelectorType"]
+_TriplePathType = Tuple["_SubjectType", Path, "_ObjectType"]
+_TripleOrTriplePathType = Union["_TripleType", "_TriplePathType"]
+
+_GraphT = TypeVar("_GraphT", bound="Graph")
+_ConjunctiveGraphT = TypeVar("_ConjunctiveGraphT", bound="ConjunctiveGraph")
+_DatasetT = TypeVar("_DatasetT", bound="Dataset")
+
+# type error: Function "Type[Literal]" could always be true in boolean contex
+assert Literal  # type: ignore[truthy-function] # avoid warning
+# type error: Function "Type[Namespace]" could always be true in boolean context
+assert Namespace  # type: ignore[truthy-function] # avoid warning
+
+if TYPE_CHECKING:
+    from rdflib._type_checking import _NamespaceSetString
+
+logger = logging.getLogger(__name__)
+
 
 __all__ = [
     "Graph",
@@ -2283,7 +2283,7 @@ def __reduce__(self) -> Tuple[Type[Graph], Tuple[Store, _ContextIdentifierType]]
 
 
 class Dataset(ConjunctiveGraph):
-    __doc__ = """
+    """
     RDF 1.1 Dataset. Small extension to the Conjunctive Graph:
     - the primary term is graphs in the datasets and not contexts with quads,
     so there is a separate method to set/retrieve a graph in a dataset and

rdflib/namespace/__init__.py

@@ -1,18 +1,4 @@
-import logging
-import warnings
-from functools import lru_cache
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Optional, Set, Tuple, Union
-from unicodedata import category
-from urllib.parse import urldefrag, urljoin
-
-from rdflib.term import URIRef, Variable, _is_valid_uri
-
-if TYPE_CHECKING:
-    from rdflib.graph import Graph
-    from rdflib.store import Store
-
-__doc__ = """
+"""
 ===================
 Namespace Utilities
 ===================
@@ -84,6 +70,21 @@
     rdflib.term.URIRef('http://www.w3.org/2000/01/rdf-schema#seeAlso')
 """
 
+import logging
+import warnings
+from functools import lru_cache
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Optional, Set, Tuple, Union
+from unicodedata import category
+from urllib.parse import urldefrag, urljoin
+
+from rdflib.term import URIRef, Variable, _is_valid_uri
+
+if TYPE_CHECKING:
+    from rdflib.graph import Graph
+    from rdflib.store import Store
+
+
 __all__ = [
     "is_ncname",
     "split_uri",

rdflib/paths.py

@@ -1,8 +1,4 @@
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-
-__doc__ = r"""
+r"""
 
 This module implements the SPARQL 1.1 Property path operators, as
 defined in:
@@ -183,9 +179,10 @@
  (rdflib.term.URIRef('ex:h'), rdflib.term.URIRef('ex:a'))]
 
 """
-
+from __future__ import annotations
 
 import warnings
+from abc import ABC, abstractmethod
 from functools import total_ordering
 from typing import (
     TYPE_CHECKING,