Expose StructMeta in Python API

[apoorvkh]

Re-opening PR for #843 and #844. Copying @nightsailer's initial PR message below:

---

Expose and Enable Inheritance of StructMeta Metaclass

Changes

• Exposed StructMeta metaclass to Python for direct use
• Added Py_TPFLAGS_BASETYPE flag to enable Python inheritance of StructMeta
• Created tests to verify functionality

Why

This allows users to:

• Use StructMeta directly without subclassing Struct
• Create custom metaclasses that extend StructMeta behavior
• Implement reusable patterns across multiple struct classes

This PR resolves:

• Issue Inheritable kw_only for Struct (e.g., kw_only_default=True) #841
• Issue Expose metaclass for msgspec.Struct #837

Example

from msgspec import StructMeta

# Custom metaclass with kw_only_default parameter
class KwOnlyMeta(StructMeta):
    _kw_only_default_settings = {}
    
    def __new__(mcls, name, bases, namespace, **kwargs):
        # Store and inherit kw_only_default
        kw_only_default = kwargs.pop('kw_only_default', None)
        if kw_only_default is None:
            for base in bases:
                if base.__name__ in mcls._kw_only_default_settings:
                    kw_only_default = mcls._kw_only_default_settings[base.__name__]
                    break
        else:
            mcls._kw_only_default_settings[name] = kw_only_default
            
        # Apply kw_only_default if kw_only not specified
        if 'kw_only' not in kwargs and kw_only_default is not None:
            kwargs['kw_only'] = kw_only_default
            
        return super().__new__(mcls, name, bases, namespace, **kwargs)

# Base model requiring keyword arguments
class BaseModel(metaclass=KwOnlyMeta, kw_only_default=True):
    pass

# Child class inherits kw_only=True
class User(BaseModel):
    name: str
    age: int

# Must use keyword arguments
user = User(name="John", age=30)

Technical Details

Added StructMeta to module exports in _core.c Added Py_TPFLAGS_BASETYPE flag to StructMetaType Updated init.py to import and expose StructMeta Added type hints in init.pyi

Compatibility

These changes are backward compatible and only add new capabilities without modifying existing behavior.

Related Issues

[ofek]

Thanks! Just to confirm, you pretty much used this comparison right? main...nightsailer:msgspec-x:f9bd49fc907fa4b683f582257a463f3470e1a359

[apoorvkh]

Yes, that's right!

[jacopoabramo]

It would be worthwhile to document these changes as well, maybe with some use cases as examples

EDIT: @ofek ahah, synchronized comments

[ofek]

I'll review later tonight but at a quick glance I noticed there is no information about how to use the new capabilities. Do you think you could take a crack at writing some very basic docs and then I can expand or touch up as need be?

[apoorvkh]

Yeah, good point. No problem, will add something simple!

[apoorvkh]

How's this, @ofek?

[ofek]

Thanks a lot for picking this back up!

[apoorvkh]

Amazing, glad to see this is finally merged!! Thank you!

[landeholt]

which version had this exposed? I'm using 0.19.0 and cannot import it.

uv run python
Python 3.12.10 (main, Apr  9 2025, 03:49:38) [Clang 20.1.0 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import msgspec
>>> dir(msgspec)
['DecodeError', 'EncodeError', 'Meta', 'MsgspecError', 'NODEFAULT', 'Raw', 'Struct', 'UNSET', 'UnsetType', 'ValidationError', '_Field', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__path__', '__spec__', '__version__', '_core', '_json_schema', '_utils', '_version', 'convert', 'defstruct', 'field', 'inspect', 'json', 'msgpack', 'structs', 'to_builtins', 'toml', 'yaml']
>>> msgspec.StructMeta
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: module 'msgspec' has no attribute 'StructMeta'

[jacopoabramo]

@landeholt this feature has not been released on pypi yet, it's only available if you clone the main branch of the repository