WIP: Generate module definitions as well as the class definitions.

NOTE: Not to be merged yet, but wanted to let you see the changes that I needed to make for the jp.JPackage('cern') style static analysis. I propose that the new API in https://github.com/jpype-project/jpype/issues/933 might be the thing that we eventually target, rather than doing the JPackage thing.

These definitions can be used from a top-level stub, such as in JPype itself to declare top-level names. For example, in the JPype stubs:

@typing.overload
def JPackage(__package_name: typing.Literal['java']) -> java.module: ...

Would allow type checking of jpype.JPackage('java').lang.String etc.

cmmnbuild_dep_manager/_stubgenj.py

@@ -74,6 +74,13 @@ def generateJavaStubs(parentPackages: List[jpype.JPackage], useStubsSuffix: bool
 
     log.info('Collected %d packages ...' % len(packages))
 
+    # A mapping from package name to a list of direct child packages.
+    childPackages = {}
+    for pkg in packages:
+        if '.' in pkg.__name__:
+            parent, name = pkg.__name__.rsplit('.', 1)
+            childPackages.setdefault(parent, []).append(name)
+
     outputPath = pathlib.Path(outputDir)
     for pkg in packages:
         pathParts = pkg.__name__.split('.')
@@ -86,7 +93,10 @@ def generateJavaStubs(parentPackages: List[jpype.JPackage], useStubsSuffix: bool
             initFile = submodulePath / '__init__.pyi'
             initFile.touch()
 
-        generateStubsForJavaPackage(pkg, submodulePath / '__init__.pyi')
+        generateStubsForJavaPackage(
+            pkg, submodulePath / '__init__.pyi',
+            childPackages=childPackages.get(pkg.__name__, []),
+        )
 
 
 def filterClassNamesInPackage(packageName: str, types: Set[str]) -> Set[str]:
@@ -122,7 +132,7 @@ def provideCustomizerStubs(customizersUsed: Set[Type], importOutput: List[str],
         importOutput.append(f'from {c.__module__} import {c.__name__}')
 
 
-def generateStubsForJavaPackage(package: jpype.JPackage, outputFile: str) -> None:
+def generateStubsForJavaPackage(package: jpype.JPackage, outputFile: str, childPackages: List[str]) -> None:
     """ Generate stubs for a single Java package, represented as a python package with a single __init__ module. """
     javaClasses = packageClasses(package)
     log.info('Generating stubs for %s (%d classes)' % (package.__name__, len(javaClasses)))
@@ -168,9 +178,26 @@ def generateStubsForJavaPackage(package: jpype.JPackage, outputFile: str) -> Non
                 # So the way to mimic this behavior in the stubs is to generate an empty "fake" stub for the private
                 # class "OuterClass.InnerClass".
                 log.warning('reference to missing class %s - generating empty stub' % missingPrivateClass)
-                classOutput.append('')
+                classOutput.extend([''] * 2)
                 generateEmptyClassStub(missingPrivateClass, classesDone=classesDone, output=classOutput)
 
+    classesInModule = [className for className in classesDone if '$' not in className]
+    protocolOutput = ['class module(typing.Protocol):']
+
+    for className in classesInModule:
+        protocolOutput.append(f'    {className}: typing.Type[{className}]')
+
+    pkg_name = package.__name__
+    for childPackage in childPackages:
+        importOutput.append(f'import {pkg_name}.{childPackage}')
+        protocolOutput.append(f'    {childPackage}: {pkg_name}.{childPackage}.module')
+    if len(protocolOutput) < 2:
+        # No public classes, nor attributes.
+        protocolOutput.append('    pass')
+
+    classOutput.extend([''] * 2)
+    classOutput.extend(protocolOutput)
+
     if any(('typing.' in line) for line in classOutput):
         importOutput.append('import typing')
 
@@ -182,7 +209,7 @@ def generateStubsForJavaPackage(package: jpype.JPackage, outputFile: str) -> Non
     for line in sorted(set(importOutput)):
         output.append(line)
 
-    output.append('')
+    output.extend([''] * 2)
     for line in classOutput:
         output.append(line)
     with open(outputFile, 'w') as file: