0
# Native Types
1

2
Specialized template environments that render templates to native Python types instead of strings. Returns actual Python objects (integers, lists, dictionaries, etc.) when possible, with string fallback for complex expressions.
3

4
## Capabilities
5

6
### Native Environment
7

8
Environment that renders templates to native Python types using custom code generation and concatenation logic.
9

10
```python { .api }
11
class NativeEnvironment(Environment):
12
    """
13
    An environment that renders templates to native Python types.
14
    
15
    Uses a specialized code generator that avoids converting values to strings,
16
    allowing templates to return actual Python objects like integers, lists,
17
    and dictionaries when the template output can be parsed as valid Python literals.
18
    """
19
```
20

21
### Native Template
22

23
Template class that works with NativeEnvironment to produce native Python values instead of string output.
24

25
```python { .api }
26
class NativeTemplate(Template):
27
    """
28
    Template that renders to native Python types.
29
    
30
    Automatically uses NativeEnvironment as its environment class.
31
    """
32
    
33
    def render(self, *args, **kwargs):
34
        """
35
        Render the template to produce a native Python type.
36
        
37
        If the result is a single node, its value is returned. Otherwise, the
38
        nodes are concatenated as strings. If the result can be parsed with
39
        ast.literal_eval, the parsed value is returned. Otherwise, the string
40
        is returned.
41
        
42
        Parameters:
43
            *args: Template context arguments
44
            **kwargs: Template context keyword arguments
45
            
46
        Returns:
47
            Any: Native Python type or string
48
        """
49
    
50
    def render_async(self, *args, **kwargs):
51
        """
52
        Async version of render() for native type rendering.
53
        
54
        Parameters:
55
            *args: Template context arguments  
56
            **kwargs: Template context keyword arguments
57
            
58
        Returns:
59
            Any: Native Python type or string
60
        """
61
```
62

63
### Native Concatenation
64

65
Core function that handles conversion from template output to native Python types.
66

67
```python { .api }
68
def native_concat(values):
69
    """
70
    Return a native Python type from the list of compiled nodes.
71
    
72
    If the result is a single node, its value is returned. Otherwise, the
73
    nodes are concatenated as strings. If the result can be parsed with
74
    ast.literal_eval, the parsed value is returned. Otherwise, the string
75
    is returned.
76
    
77
    Parameters:
78
        values: Iterable of outputs to concatenate
79
        
80
    Returns:
81
        Any: Native Python type or None
82
    """
83
```
84

85
## Usage Examples
86

87
### Basic Native Rendering
88

89
```python
90
from jinja2.nativetypes import NativeEnvironment, NativeTemplate
91

92
# Using NativeEnvironment
93
env = NativeEnvironment()
94

95
# Template returning integer
96
template = env.from_string('{{ 42 }}')
97
result = template.render()
98
assert result == 42  # Integer, not string "42"
99

100
# Template returning list
101
template = env.from_string('{{ items }}')
102
result = template.render(items=[1, 2, 3])
103
assert result == [1, 2, 3]  # List, not string "[1, 2, 3]"
104

105
# Template returning dictionary
106
template = env.from_string('{{ {"name": name, "age": age} }}')
107
result = template.render(name="Alice", age=30)
108
assert result == {"name": "Alice", "age": 30}  # Dict, not string
109
```
110

111
### Using NativeTemplate Directly
112

113
```python
114
from jinja2.nativetypes import NativeTemplate
115

116
# Create template directly
117
template = NativeTemplate('{{ value * 2 }}')
118
result = template.render(value=21)
119
assert result == 42  # Integer 42, not string "42"
120

121
# Template with complex expression
122
template = NativeTemplate('{{ [x for x in range(count)] }}')
123
result = template.render(count=5)
124
assert result == [0, 1, 2, 3, 4]  # List of integers
125
```
126

127
### Mixed Content Handling
128

129
```python
130
from jinja2.nativetypes import NativeEnvironment
131

132
env = NativeEnvironment()
133

134
# Mixed content falls back to string
135
template = env.from_string('The answer is {{ 42 }}')
136
result = template.render()
137
assert result == "The answer is 42"  # String fallback
138

139
# Pure value returns native type
140
template = env.from_string('{{ 42 }}')
141
result = template.render()
142
assert result == 42  # Native integer
143
```
144

145
### Async Native Rendering
146

147
```python
148
import asyncio
149
from jinja2.nativetypes import NativeEnvironment
150

151
async def main():
152
    env = NativeEnvironment(enable_async=True)
153
    
154
    template = env.from_string('{{ await_value }}')
155
    result = await template.render_async(await_value=42)
156
    assert result == 42
157

158
asyncio.run(main())
159
```
160

161
## Types
162

163
```python { .api }
164
class NativeEnvironment(Environment):
165
    """
166
    Environment that renders templates to native Python types.
167
    
168
    Inherits all Environment functionality but uses specialized code generation
169
    and concatenation to produce native Python values when possible.
170
    """
171

172
class NativeTemplate(Template):
173
    """
174
    Template that renders to native Python types.
175
    
176
    Attributes:
177
        environment_class: Set to NativeEnvironment automatically
178
    """
179
```