Add class for Python docstrings

src/jcloud_docsgen/core/python/definitions.py

@@ -16,8 +16,11 @@ from __future__ import annotations
 from typing import Union
 import ast
 from .arguments import PythonFunctionArgument, PythonASTArgumentsListParser
+from .docstrings import PythonDocstring
 import keyword
 from ...exceptions import InvalidPythonIdentifierError
+from ...utils import assert_that_is_instance
+import types
 
 __all__ = [
     'PythonDefinition',
@@ -26,6 +29,20 @@ __all__ = [
     'PythonClassDefinition'
 ]
 
+def _python_docstring(doc: Union[str, None]) -> Union[PythonDocstring, None]:
+    '''
+    Returns the PythonDocstring object if the docstring is a string and
+    not ``None``.
+
+    :param doc: The docstring.
+    :type doc: Union[str, None]
+
+    :return: The PythonDocstring object or ``None``.
+    :rtype: Union[PythonDocstring, None]
+    '''
+
+    return PythonDocstring(doc) if doc is not None else None
+
 class PythonDefinition:
     '''
     A base class for Python definition (a class, function or asynchronous
@@ -34,7 +51,7 @@ class PythonDefinition:
     :param name: The name of the definition.
     :type name: str
     :param doc: The docstring.
-    :type doc: Union[str, None]
+    :type doc: Union[PythonDocstring, None]
     :param decorators: The definition decorators.
     :type decorators: list[str]
 
@@ -42,10 +59,12 @@ class PythonDefinition:
                                           Python identifier.
     '''
 
-    def __init__(self, name: str, doc: Union[str, None], decorators: list[str]) -> None:
+    def __init__(self, name: str, doc: Union[PythonDocstring, None], decorators: list[str]) -> None:
         if keyword.iskeyword(name) or not name.isidentifier() or not name:
             raise InvalidPythonIdentifierError('invalid identifier', identifier = name)
 
+        assert_that_is_instance(doc, (PythonDocstring, types.NoneType))
+
         self.name = name
         self.doc = doc
         self.decorators = decorators
@@ -71,7 +90,7 @@ class PythonDefinition:
 
         return cls(
             node.name,
-            ast.get_docstring(node),
+            _python_docstring(ast.get_docstring(node)),
             [ast.unparse(d) for d in node.decorator_list]
         )
     
@@ -92,7 +111,7 @@ class PythonFunctionDefinition(PythonDefinition):
     :param returns: The return type of the function or class.
     :type returns: Union[str, None]
     :param doc: The docstring.
-    :type doc: Union[str, None]
+    :type doc: Union[PythonDocstring, None]
     :param decorators: The definition decorators.
     :type decorators: list[str]
 
@@ -100,7 +119,7 @@ class PythonFunctionDefinition(PythonDefinition):
                                           Python identifier.
     '''
 
-    def __init__(self, name: str, args: list[PythonFunctionArgument], returns: Union[str, None], doc: Union[str, None], decorators: list[str]) -> None:
+    def __init__(self, name: str, args: list[PythonFunctionArgument], returns: Union[str, None], doc: Union[PythonDocstring, None], decorators: list[str]) -> None:
         super().__init__(name, doc, decorators)
         self.args = args
         self.returns = returns
@@ -127,7 +146,7 @@ class PythonFunctionDefinition(PythonDefinition):
             node.name,
             PythonASTArgumentsListParser(node.args).to_argument_list(),
             ast.unparse(node.returns) if node.returns is not None else None,
-            ast.get_docstring(node),
+            _python_docstring(ast.get_docstring(node)),
             [ast.unparse(d) for d in node.decorator_list]
         )
 
@@ -143,7 +162,7 @@ class PythonAsyncFunctionDefinition(PythonFunctionDefinition):
     :param returns: The return type of the function or class.
     :type returns: Union[str, None]
     :param doc: The docstring.
-    :type doc: Union[str, None]
+    :type doc: Union[PythonDocstring, None]
     :param decorators: The definition decorators.
     :type decorators: list[str]
 
@@ -160,7 +179,7 @@ class PythonClassDefinition(PythonDefinition):
     :param bases: The base classes.
     :type bases: list[str]
     :param doc: The docstring.
-    :type doc: Union[str, None]
+    :type doc: Union[PythonDocstring, None]
     :param decorators: The definition decorators.
     :type decorators: list[str]
     :param body:
@@ -170,7 +189,7 @@ class PythonClassDefinition(PythonDefinition):
                                           Python identifier.
     '''
 
-    def __init__(self, name: str, bases: list[str], doc: Union[str, None], decorators: list[str], body: list[PythonDefinition]) -> None:
+    def __init__(self, name: str, bases: list[str], doc: Union[PythonDocstring, None], decorators: list[str], body: list[PythonDefinition]) -> None:
         super().__init__(name, doc, decorators)
         self.bases = bases
         self.body = body
@@ -196,7 +215,7 @@ class PythonClassDefinition(PythonDefinition):
         return cls(
             node.name,
             [ast.unparse(b) for b in node.bases],
-            ast.get_docstring(node),
+            _python_docstring(ast.get_docstring(node)),
             [ast.unparse(d) for d in node.decorator_list],
             [
                 PythonFunctionDefinition.from_node(expr)