Add namespaces classes

docs/CHANGELOG.md

@@ -8,3 +8,4 @@
 - Add function to format a list human-readable
 - Add function to assert that an object is an instance of a specific type
 - Add python project documentation generator class
+- Add namespaces classes

src/jcloud_docsgen/core/python/_core.py

@@ -12,7 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from .utils import ExistingDirectory, assert_that_is_instance
+from __future__ import annotations
+from ...utils import ExistingDirectory, assert_that_is_instance
 
 __all__ = [
     'PythonDocumentationGenerator'

src/jcloud_docsgen/core/python/namespaces.py

@@ -0,0 +1,76 @@
+# Copyright 2026 jCloud Services GbR
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from ...exceptions import InvalidNamespaceError, NamespaceNotFoundError
+
+class PythonNamespace:
+    '''
+    The base class for all python namespaces such as modules or packages.
+
+    :param name: The name of the namespace.
+    :type name: str
+    '''
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+class PythonPackageNamespace(PythonNamespace):
+    '''
+    A subclass of ``PythonNamespace`` for python package namespaces.
+
+    :param name: The name of the namespace.
+    :type name: str
+    :param sub_namespaces: The sub namespaces.
+    :type sub_namespaces: list[PythonNamespace]
+    '''
+
+    def __init__(self, name: str, sub_namespaces: dict[str, PythonNamespace]) -> None:
+        super().__init__(name)
+
+        self.sub_namespaces = sub_namespaces
+
+    def namespace(self, sub_namespaces: list[str]) -> PythonNamespace:
+        '''
+        Returns the namespace object with a specific identifier, such as
+        ``package.subpackage.module``.
+        '''
+
+        if not sub_namespaces:
+            raise InvalidNamespaceError('invalid namespace')
+
+        # check whether the sub namespace exists
+        if sub_namespaces[0] not in self.sub_namespaces:
+            raise NamespaceNotFoundError('no such namespace', namespace_identifier = sub_namespaces[0])
+        
+        sub_namespace = self.sub_namespaces[sub_namespaces[0]]
+
+        # package namespace
+        if isinstance(sub_namespace, PythonPackageNamespace):
+            if len(sub_namespaces) == 1:
+                return sub_namespace
+            return sub_namespace.namespace(sub_namespaces[1:])
+        # module namespace
+        else:
+            return sub_namespace
+
+
+class PythonModuleNamespace(PythonNamespace):
+    '''
+    A subclass of ``PythonNamespace`` for python module namespaces.
+
+    :param name: The name of the namespace.
+    :type name: str
+    '''
+
+    def __init__(self, name: str) -> None:
+        super().__init__(name)