update docs, prepare bump version.

Author: nightsailer

docs/source/api.rst

@@ -8,6 +8,8 @@ Structs
 
 .. autoclass:: Struct
 
+.. autoclass:: StructMeta
+
 .. autofunction:: field
 
 .. autofunction:: defstruct

docs/source/changelog.rst

@@ -3,6 +3,90 @@ Changelog
 
 .. currentmodule:: msgspec
 
+Version 0.20.0 (2025-01-03)
+---------------------------
+
+**🎉 MAJOR: Community Fork Release**
+
+This is the first release of ``msgspec-x``, a community-driven fork of the original msgspec library by Jim Crist-Harif. This fork was created to accelerate community contributions and provide a platform for extended features while maintaining full backward compatibility.
+
+**🚀 NEW MAJOR FEATURE: StructMeta Subclasses Support**
+
+- **Add comprehensive support for StructMeta subclasses** - the primary feature that motivated this fork.
+- Enable custom metaclasses that inherit from `StructMeta` to work seamlessly with all msgspec functions.
+- **TECHNICAL**: Modified C code to use `PyType_IsSubtype()` instead of direct type comparison for StructMeta detection.
+- Affected functions now support StructMeta subclasses:
+
+  - `msgspec.structs.asdict` - Convert struct instances to dictionaries
+  - `msgspec.structs.astuple` - Convert struct instances to tuples  
+  - `msgspec.structs.replace` - Create modified copies of struct instances
+  - `msgspec.structs.force_setattr` - Force attribute setting on frozen structs
+  - JSON encoding/decoding operations
+  - MessagePack encoding/decoding operations
+  - `msgspec.convert` - Type conversion operations
+  - `msgspec.to_builtins` - Convert to builtin types
+
+- Comprehensive test coverage for StructMeta subclasses including:
+
+  - Single-level StructMeta inheritance
+  - Multi-level StructMeta inheritance chains
+  - Integration with all struct utility functions
+  - Encoder/decoder compatibility testing
+  - Nested struct support with custom metaclasses
+
+- **Use Cases**: This enables advanced users to create custom struct behaviors through metaclass programming while maintaining full compatibility with msgspec's serialization ecosystem.
+
+**Project Rename and Fork**
+
+- **BREAKING**: Project renamed from ``msgspec`` to ``msgspec-x``. Do not install both packages simultaneously.
+- Fork created due to slow upstream maintenance and to enable faster community contribution cycles.
+- All project metadata, URLs, and documentation updated to reflect the new ``msgspec-x`` identity.
+- Repository moved to ``https://github.com/nightsailer/msgspec-x``.
+- Maintainer changed to Night Sailer (nightsailer@gmail.com).
+
+**Dual Namespace Architecture**
+
+- Introduce dual namespace architecture to support both compatibility and extensions:
+
+  - ``msgspec`` namespace: 100% API compatibility with the original library for drop-in replacement.
+  - ``msgspec_x`` namespace: Extended features and community contributions (placeholder structure created).
+
+- All existing code using ``import msgspec`` will continue to work without changes.
+- New extended features will be available under ``msgspec_x`` namespace.
+
+**Installation and Distribution**
+
+- Package name changed to ``msgspec-x`` on PyPI.
+- Updated installation commands: ``pip install msgspec-x`` and ``conda install msgspec-x -c conda-forge``.
+- Added clear warnings about not installing both ``msgspec`` and ``msgspec-x`` in the same environment.
+- Updated versioneer configuration to use ``msgspec-x-`` prefix for source distributions.
+
+**Documentation Overhaul**
+
+- Comprehensive documentation update to reflect the project fork and new architecture.
+- Added explanation of the dual namespace system and community-driven development model.
+- Updated all GitHub links, issue tracker URLs, and example source references.
+- Enhanced installation documentation with compatibility warnings.
+- Updated contributing guidelines and security policies for the new project structure.
+
+**Community and Development**
+
+- Established faster review and merge cycles for community contributions.
+- Updated GitHub issue templates and workflows for the new repository.
+- Created placeholder structure for experimental features in ``msgspec_x`` namespace.
+- Enhanced project documentation to welcome community contributions.
+
+**Technical Infrastructure**
+
+- Updated build configuration (``setup.py``, ``setup.cfg``, ``MANIFEST.in``) for the new package structure.
+- Enhanced CI/CD workflows for the dual namespace architecture.
+- Updated type stub files and package metadata for both namespaces.
+- Maintained all existing performance characteristics and API compatibility.
+
+**Acknowledgments**
+
+This release acknowledges and thanks Jim Crist-Harif for creating the original msgspec library. This fork exists to complement and extend his excellent work, not to replace it.
+
 Version 0.19.0 (2024-12-27)
 ---------------------------
 

docs/source/index.rst

@@ -25,6 +25,10 @@ support for JSON_, MessagePack_, YAML_, and TOML_. It features:
   use dataclasses_ or attrs_, :doc:`structs` should feel familiar. However,
   they're :ref:`5-60x <struct-benchmark>` faster for common operations.
 
+- 🆕 **StructMeta subclasses support** for advanced metaclass programming. 
+  Create custom struct behaviors while maintaining full compatibility with
+  all msgspec operations. See :ref:`struct-meta-subclasses` for details.
+
 All of this is included in a :ref:`lightweight library
 <benchmark-library-size>` with no required dependencies.
 
@@ -101,6 +105,11 @@ Highlights
   compliant with their respective specifications, providing stronger guarantees
   of compatibility with other systems.
 
+- ``msgspec-x`` is **extensible**. The new :ref:`StructMeta subclasses 
+  <struct-meta-subclasses>` support enables advanced users to create custom
+  struct behaviors through metaclass programming while maintaining full
+  compatibility with all msgspec operations.
+
 Used By
 -------
 
@@ -201,4 +210,4 @@ few:
 
     api.rst
     examples/index.rst
-    changelog.rst
+    changelog.rst

docs/source/structs.rst

@@ -998,6 +998,201 @@ container types. It is your responsibility to ensure cycles with these objects
 don't occur, as a cycle containing only ``gc=False`` structs will *never* be
 collected (leading to a memory leak).
 
+
+.. _struct-meta-subclasses:
+
+StructMeta Subclasses (Advanced)
+-------------------------------
+
+.. versionadded:: 0.20.0
+
+``msgspec-x`` provides comprehensive support for custom metaclasses that inherit from `msgspec.StructMeta`. This advanced feature enables users to create custom struct behaviors through metaclass programming while maintaining full compatibility with msgspec's serialization ecosystem.
+
+**What are StructMeta Subclasses?**
+
+StructMeta subclasses allow you to extend or customize the behavior of struct creation and management by defining your own metaclass that inherits from `msgspec.StructMeta`. This enables advanced patterns like:
+
+- Adding custom validation logic during struct class creation
+- Implementing custom field processing or transformation
+- Integrating with external frameworks or ORMs
+- Creating domain-specific struct variants with specialized behaviors
+
+**Basic Usage**
+
+Here's a simple example of creating and using a custom StructMeta subclass:
+
+.. code-block:: python
+
+    >>> import msgspec
+    >>> from msgspec import StructMeta
+
+    >>> class CustomMeta(StructMeta):
+    ...     """A custom metaclass that extends StructMeta"""
+    ...     def __new__(cls, name, bases, namespace):
+    ...         # Custom logic during class creation
+    ...         print(f"Creating struct class: {name}")
+    ...         return super().__new__(cls, name, bases, namespace)
+
+    >>> class CustomStruct(metaclass=CustomMeta):
+    ...     x: int
+    ...     y: str
+    ...     z: float = 3.14
+    Creating struct class: CustomStruct
+
+    >>> # Instances work exactly like regular structs
+    ... obj = CustomStruct(x=42, y="hello")
+    >>> obj
+    CustomStruct(x=42, y='hello', z=3.14)
+
+**Full Compatibility with msgspec Functions**
+
+Structures created with StructMeta subclasses work seamlessly with all msgspec operations:
+
+.. code-block:: python
+
+    >>> from msgspec.structs import asdict, astuple, replace, force_setattr
+
+    >>> # All struct utility functions work
+    >>> asdict(obj)
+    {'x': 42, 'y': 'hello', 'z': 3.14}
+
+    >>> astuple(obj)
+    (42, 'hello', 3.14)
+
+    >>> replace(obj, x=100)
+    CustomStruct(x=100, y='hello', z=3.14)
+
+    >>> # JSON encoding/decoding works
+    >>> import msgspec.json
+    >>> data = msgspec.json.encode(obj)
+    >>> msgspec.json.decode(data, type=CustomStruct)
+    CustomStruct(x=42, y='hello', z=3.14)
+
+    >>> # MessagePack encoding/decoding works
+    >>> import msgspec.msgpack
+    >>> data = msgspec.msgpack.encode(obj)
+    >>> msgspec.msgpack.decode(data, type=CustomStruct)
+    CustomStruct(x=42, y='hello', z=3.14)
+
+    >>> # Type conversion works
+    >>> msgspec.convert({'x': 1, 'y': 'test', 'z': 2.5}, type=CustomStruct)
+    CustomStruct(x=1, y='test', z=2.5)
+
+**Multi-Level Inheritance**
+
+StructMeta subclasses support inheritance chains, allowing for sophisticated metaclass hierarchies:
+
+.. code-block:: python
+
+    >>> class BaseMeta(StructMeta):
+    ...     """Base custom metaclass"""
+    ...     pass
+
+    >>> class DerivedMeta(BaseMeta):
+    ...     """Derived custom metaclass"""
+    ...     def __new__(cls, name, bases, namespace):
+    ...         # Add custom behavior
+    ...         result = super().__new__(cls, name, bases, namespace)
+    ...         result._custom_attribute = f"Enhanced {name}"
+    ...         return result
+
+    >>> class EnhancedStruct(metaclass=DerivedMeta):
+    ...     value: int
+    ...     name: str
+
+    >>> obj = EnhancedStruct(value=123, name="test")
+    >>> obj._custom_attribute
+    'Enhanced EnhancedStruct'
+
+    >>> # All msgspec functions still work
+    >>> asdict(obj)
+    {'value': 123, 'name': 'test'}
+
+**Nested Structures**
+
+StructMeta subclasses work correctly with nested structures and complex serialization scenarios:
+
+.. code-block:: python
+
+    >>> class ContainerMeta(StructMeta):
+    ...     """Metaclass for container structures"""
+    ...     pass
+
+    >>> class Item(metaclass=ContainerMeta):
+    ...     id: int
+    ...     name: str
+
+    >>> class Container(metaclass=ContainerMeta):
+    ...     items: list[Item]
+    ...     count: int
+
+    >>> container = Container(
+    ...     items=[Item(id=1, name="first"), Item(id=2, name="second")],
+    ...     count=2
+    ... )
+
+    >>> # Complex nested encoding/decoding works
+    >>> data = msgspec.json.encode(container)
+    >>> decoded = msgspec.json.decode(data, type=Container)
+    >>> decoded.items[0].name
+    'first'
+
+**Integration with Struct Options**
+
+StructMeta subclasses work with all struct configuration options:
+
+.. code-block:: python
+
+    >>> class FrozenMeta(StructMeta):
+    ...     """Metaclass for immutable structures"""
+    ...     pass
+
+    >>> class ImmutablePoint(metaclass=FrozenMeta, frozen=True, order=True):
+    ...     x: float
+    ...     y: float
+
+    >>> p1 = ImmutablePoint(1.0, 2.0)
+    >>> p2 = ImmutablePoint(3.0, 4.0)
+
+    >>> # Frozen behavior works
+    >>> try:
+    ...     p1.x = 5.0
+    ... except AttributeError as e:
+    ...     print(f"Expected error: {e}")
+    Expected error: immutable type: 'ImmutablePoint'
+
+    >>> # Ordering works
+    >>> p1 < p2
+    True
+
+    >>> # All msgspec functions work
+    >>> replace(p1, x=10.0)
+    ImmutablePoint(x=10.0, y=2.0)
+
+**Technical Implementation**
+
+``msgspec-x`` achieves StructMeta subclass support by modifying the core C implementation to use `PyType_IsSubtype()` checks instead of direct type comparisons. This change affects all core msgspec operations including:
+
+- Type validation during encoding/decoding
+- Struct utility functions (asdict, astuple, replace, etc.)
+- Type conversion operations
+- Tagged union resolution
+- Performance optimizations
+
+The implementation maintains full backward compatibility - existing code continues to work unchanged, while new code can take advantage of the enhanced metaclass support.
+
+**Use Cases**
+
+StructMeta subclasses enable advanced patterns such as:
+
+- **Framework Integration**: Creating structs that automatically integrate with web frameworks, ORMs, or validation libraries
+- **Domain-Specific Languages**: Building specialized struct types for specific problem domains
+- **Automatic Documentation**: Metaclasses that generate documentation or schema information
+- **Validation Enhancement**: Adding complex validation logic at the class level
+- **Serialization Customization**: Implementing custom serialization behaviors for specific use cases
+
+This feature is particularly valuable for library authors who want to build higher-level abstractions on top of msgspec's fast serialization capabilities.
+
 .. _type annotations: https://docs.python.org/3/library/typing.html
 .. _pattern matching: https://docs.python.org/3/reference/compound_stmts.html#the-match-statement
 .. _PEP 636: https://peps.python.org/pep-0636/