docs: Add documentation for post_build and post_generate hooks

Added comprehensive documentation for the new lifecycle hooks:

- Created two example files demonstrating post_build and post_generate usage
- Added "Lifecycle Hooks" section to configuration.rst documentation
- Examples show practical use cases:
  - post_build: Modifying created instances (e.g., auto-verifying test accounts)
  - post_generate: Computing derived fields before model creation (e.g., calculating total price with tax)

Addresses reviewer feedback on PR litestar-org#667 requesting documentation.

Author: claude

docs/examples/configuration/test_example_12.py

@@ -0,0 +1,42 @@
+from dataclasses import dataclass
+
+from polyfactory.factories import DataclassFactory
+
+
+@dataclass
+class Account:
+    """User account model."""
+
+    username: str
+    email: str
+    is_verified: bool
+    verification_token: str
+
+
+class AccountFactory(DataclassFactory[Account]):
+    """Factory for Account with post_build hook."""
+
+    @classmethod
+    def post_build(cls, account: Account) -> Account:
+        """Post-build hook to modify the created instance.
+
+        This hook is called after the model instance is created,
+        allowing you to run custom logic on the fully-generated object.
+        """
+        # Auto-verify accounts in test environment
+        if account.username.startswith("test_"):
+            account.is_verified = True
+            account.verification_token = ""
+
+        return account
+
+
+def test_post_build_hook() -> None:
+    # Regular account will have random is_verified value
+    regular_account = AccountFactory.build(username="john_doe")
+    assert regular_account.username == "john_doe"
+
+    # Test account will be auto-verified by the post_build hook
+    test_account = AccountFactory.build(username="test_user")
+    assert test_account.is_verified is True
+    assert test_account.verification_token == ""

docs/examples/configuration/test_example_13.py

@@ -0,0 +1,45 @@
+from dataclasses import dataclass
+from typing import Any, Dict
+
+from polyfactory.factories import DataclassFactory
+
+
+@dataclass
+class Product:
+    """Product model."""
+
+    name: str
+    price: float
+    tax_rate: float
+    total_price: float
+
+
+class ProductFactory(DataclassFactory[Product]):
+    """Factory for Product with post_generate hook."""
+
+    @classmethod
+    def post_generate(cls, result: Dict[str, Any]) -> Dict[str, Any]:
+        """Post-generate hook to modify kwargs before model creation.
+
+        This hook is called after field values are generated but before
+        the model instance is created, allowing you to compute derived
+        fields based on other generated values.
+        """
+        # Calculate total_price based on price and tax_rate
+        price = result["price"]
+        tax_rate = result["tax_rate"]
+        result["total_price"] = price * (1 + tax_rate)
+
+        return result
+
+
+def test_post_generate_hook() -> None:
+    product = ProductFactory.build()
+
+    # Verify total_price was calculated correctly
+    expected_total = product.price * (1 + product.tax_rate)
+    assert abs(product.total_price - expected_total) < 0.01
+
+    # Verify with specific values
+    product = ProductFactory.build(price=100.0, tax_rate=0.2)
+    assert product.total_price == 120.0

docs/usage/configuration.rst

@@ -164,3 +164,39 @@ forward reference names to their resolved types.
 .. note::
     The Pydantic ModelFactory has a default forward reference mapping for ``JsonValue`` to resolve to ``str``
     to avoid recursive issues with Pydantic's JsonValue type.
+
+Lifecycle Hooks
+---------------
+
+Factories provide two lifecycle hooks that allow you to customize the model creation process:
+
+Post-Build Hook
+^^^^^^^^^^^^^^^^
+
+The :meth:`~polyfactory.factories.base.BaseFactory.post_build` hook is called after a model instance
+is created. This is useful for running custom logic on the fully-generated object, such as setting up
+relationships, calculating derived fields, or modifying the instance based on its generated values.
+
+.. literalinclude:: /examples/configuration/test_example_12.py
+    :caption: Using the post_build hook
+    :language: python
+
+The ``post_build`` method receives the created model instance and must return it (potentially modified).
+
+Post-Generate Hook
+^^^^^^^^^^^^^^^^^^^
+
+The :meth:`~polyfactory.factories.base.BaseFactory.post_generate` hook is called after field values
+are generated but before the model instance is created. This allows you to modify the kwargs dictionary
+that will be passed to the model constructor, making it ideal for computing derived fields or ensuring
+consistency between related fields.
+
+.. literalinclude:: /examples/configuration/test_example_13.py
+    :caption: Using the post_generate hook
+    :language: python
+
+The ``post_generate`` method receives the generated kwargs dictionary and must return it (potentially modified).
+
+.. note::
+    Both hooks are classmethods that can be overridden in your factory class. They are called automatically
+    by ``build()``, ``batch()``, and all persistence methods.