Add "how-to" documentation for extending IronPython with a C# module

Task: create a python module containing classes

• which can be imported by its name
• whose internals are hidden from python

E.g. behaves like a built-in StdLib module.

At the moment I subclass PythonModule and add an instance to the engines language context via PublishModule(name, instance). But this way I can not add a static class definition of a PythonModule. Also Python code can access all members of the module added this way.

After looking into the IronPython3 sources I neither unstand how that PythonModule assembly declaration magic works nor how I can use this magic on my own and import them via code which seems to be "internal" only as CreateBuiltinModule() ... .

The use case for a good behaving Python module written in C# are manifold - but for me its the main feature of using IronPython as a scripting language: to NOT use import clr and NOT using C# classes and syntax... . Which does not seem to work if the module is not a seperate .dll ...

In case of multi language libraries it makes sense to wrap the C# implementation into a real Python module in a way that Python source using it does not to be changed at all. There are cases were this is the ONLY option as the native Python implementation uses a syntax not implemented by IronPython yet...

The IronPython documentation about extending looks like copy&paste from CPython and doesn't help at all. And even for me as someone who has some knowledge of CPython internals, looking at IronPython sources is a little bit "confusing" as it is a total different "beast"...

For every IronPython user giving their appplications end users well known Python syntax for a library is a feature whose value should be top priority .

Best way would be a working example project which:

• uses the nuget packages of IronPython, IronPython.StdLib
• declares are PythonModule (static class)
• have some static members hidden from Python
• have C# code setup some internal values needed later
• declares a PythonObject within that PythonModule
• have some members of the PythonObject hidden from Python
• show how to make "native" IronPython functions with funcName(Context ..) and show why this might be a good idea or when to avoid that
• declares a sub module
• add a PythonModule to the engine so that it can be used via python "import xxx" using a name which is a C# keyword (like "by")
• provide Python code which uses "import xxx" and creates an object of the python class defined in the module

As not having this documentation available wastes every programmers time it would be nice (if possible) to provide a link to an article, video etc. ASAP were this is shown until the "real solution" is there. The only one I found was a presentation which was cancelled...

Start with the existing IronPython extending documentation and the PythonModule, PublishModule, and CreateBuiltinModule entry points mentioned in the issue. Build a working example using the IronPython and IronPython.StdLib NuGet packages, covering a static module, hidden members, a PythonObject, a submodule, native functions, and importing a C# keyword-named module; done means the accompanying Python code runs unchanged.