Examples

This section provides practical examples of using the JSONCrack Sphinx extension.

Automatic Schema Documentation

This example demonstrates how schemas are automatically included when using autodoc.

Example module demonstrating the Sphinx extension.

class example_module.User(name: str, email: str)

Bases: object

User management class.

create(user_data: Dict[str, Any]) → Dict[str, Any]

Create a new user.

This method creates a new user with the provided data. The schema for this method is automatically loaded from User.create.schema.json.

Parameters:

user_data – User data dictionary

Returns:

Created user information

example() → Dict[str, Any]

Get an example user object.

This method returns an example user object structure. The example data is automatically loaded from User.example.json.

Returns:

Example user object

update(user_id: int, update_data: Dict[str, Any]) → Dict[str, Any]

Update an existing user.

This method updates user information with the provided data. The schema for this method is automatically loaded from User.update.schema.json.

Parameters:

• user_id – ID of the user to update

• update_data – Data to update

Returns:

Updated user information

example_module.process_data(data: List[Dict[str, Any]], options: Dict[str, Any] | None = None) → Dict[str, Any]

Process input data according to specified options.

This function processes input data and returns the results. The schema for this function is automatically loaded from process_data.schema.json.

Parameters:

• data – Input data to process

• options – Processing options

Returns:

Processing results

Manual Schema Inclusion

The following examples show how to manually include schemas using the schema directive.

User Creation Schema

Schema for creating new users

User Creation Schema

Data Processing Schema with Auto-load

Schema for processing data

Data Processing Schema

User Update Schema with Different Direction

Schema for updating existing users

User Update Schema

Complex Schema with OnScreen Rendering

Complex example schema with detailed structure

User Example Schema

Schema Files

The examples use the following schema files located in the examples/schemas/ directory:

• User.create.schema.json - Schema for user creation

• User.update.schema.json - Schema for user updates

• User.example.json - Example user data structure

• process_data.schema.json - Schema for data processing

• ProductService.similar.schema.json - Example for complex naming patterns

These schemas demonstrate various JSON Schema features including:

• Object definitions with required and optional properties

• Array handling with item schemas

• String pattern validation

• Numeric constraints

• Nested object structures

• Conditional schema validation

Advanced Search Policy Examples

Complex Object Names

This example shows how the new search policy handles complex object names like perekrestok_api.endpoints.catalog.ProductService.similar.

With the default search policy, the extension automatically finds ProductService.similar.schema.json:

Schema for finding similar products in the catalog

Product Service Similar Items

Custom Search Patterns

You can configure custom search patterns in your conf.py:

from jsoncrack_for_sphinx.config import SearchPolicy, PathSeparator

jsoncrack_default_options = {
    'search_policy': SearchPolicy(
        include_package_name=True,
        path_to_file_separator=PathSeparator.SLASH,
        custom_patterns=[
            'api_{class_name}_{method_name}.json',
            '{object_name}_spec.json'
        ]
    )
}

This configuration would search for schemas in this order:

1. ProductService.similar.schema.json (highest priority)

2. api_ProductService_similar.json (custom pattern)

3. perekrestok_api.endpoints.catalog.ProductService.similar_spec.json (custom pattern)

4. perekrestok_api/endpoints/catalog/ProductService.similar.schema.json (with package path)

5. catalog/ProductService.similar.schema.json (parent module)

6. similar.schema.json (method name only)

Debug Output Example

When jsoncrack_debug_logging = True is enabled, you’ll see output like:

DEBUG: Searching for schema for object: perekrestok_api.endpoints.catalog.ProductService.similar
DEBUG: Generated search patterns:
DEBUG:   1. ProductService.similar.schema.json (priority: 100)
DEBUG:   2. catalog.ProductService.similar.schema.json (priority: 80)
DEBUG:   3. similar.schema.json (priority: 60)
DEBUG:   4. perekrestok_api.endpoints.catalog.ProductService.similar.schema.json (priority: 40)
DEBUG: Checking file: /path/to/schemas/ProductService.similar.schema.json
DEBUG: ✓ Found schema file: ProductService.similar.schema.json