0
# URL Routing
1

2
Django's URL routing system provides URL pattern matching, view resolution, reverse URL lookup, and URL configuration management for mapping URLs to view functions and classes.
3

4
## Core Imports
5

6
```python
7
# URL pattern functions
8
from django.urls import path, re_path, include
9

10
# URL utilities
11
from django.urls import reverse, reverse_lazy
12

13
# URL pattern classes
14
from django.urls.resolvers import URLPattern, URLResolver
15

16
# URL exceptions
17
from django.urls.exceptions import NoReverseMatch, Resolver404
18

19
# URL configuration
20
from django.conf.urls import handler404, handler500
21
```
22

23
## Capabilities
24

25
### URL Pattern Definition
26

27
Functions for defining URL patterns with path and regex syntax.
28

29
```python { .api }
30
def path(route: str, view, kwargs: dict = None, name: str = None) -> URLPattern:
31
    """
32
    Define URL pattern with path syntax using angle brackets for parameters.
33
    
34
    Args:
35
        route (str): URL pattern with parameter syntax like 'articles/<int:year>/'
36
        view: View function or class-based view
37
        kwargs (dict, optional): Extra keyword arguments to pass to view
38
        name (str, optional): Name for reverse URL lookup
39
    
40
    Returns:
41
        URLPattern: URL pattern object
42
    """
43

44
def re_path(route: str, view, kwargs: dict = None, name: str = None) -> URLPattern:
45
    """
46
    Define URL pattern with regular expression syntax.
47
    
48
    Args:
49
        route (str): Regular expression pattern for URL matching
50
        view: View function or class-based view  
51
        kwargs (dict, optional): Extra keyword arguments to pass to view
52
        name (str, optional): Name for reverse URL lookup
53
    
54
    Returns:
55
        URLPattern: URL pattern object
56
    """
57

58
def include(arg, namespace: str = None) -> tuple:
59
    """
60
    Include another URL configuration module or pattern list.
61
    
62
    Args:
63
        arg: Module path string, list of patterns, or (patterns, app_namespace) tuple
64
        namespace (str, optional): Instance namespace for included URLs
65
    
66
    Returns:
67
        tuple: URL include configuration
68
    """
69
```
70

71
### URL Resolution and Reverse Lookup
72

73
Functions for resolving URLs to views and generating URLs from view names.
74

75
```python { .api }
76
def reverse(viewname: str, urlconf: str = None, args: tuple = None, kwargs: dict = None, current_app: str = None) -> str:
77
    """
78
    Reverse lookup URL from view name and parameters.
79
    
80
    Args:
81
        viewname (str): View name or dotted path to view
82
        urlconf (str, optional): URL configuration module to use
83
        args (tuple, optional): Positional arguments for URL parameters
84
        kwargs (dict, optional): Keyword arguments for URL parameters
85
        current_app (str, optional): Current application namespace
86
    
87
    Returns:
88
        str: Resolved URL path
89
    """
90

91
def reverse_lazy(viewname: str, urlconf: str = None, args: tuple = None, kwargs: dict = None, current_app: str = None):
92
    """
93
    Lazy reverse lookup for use in settings and class definitions.
94
    
95
    Returns a lazy object that resolves to URL when evaluated.
96
    """
97

98
def resolve(path: str, urlconf: str = None) -> ResolverMatch:
99
    """
100
    Resolve URL path to view function and parameters.
101
    
102
    Args:
103
        path (str): URL path to resolve
104
        urlconf (str, optional): URL configuration module to use
105
    
106
    Returns:
107
        ResolverMatch: Resolution result with view, args, kwargs, and names
108
    """
109
```
110

111
### URL Pattern Classes
112

113
Core classes representing URL patterns and resolution results.
114

115
```python { .api }
116
class URLPattern:
117
    """Single URL pattern mapping route to view."""
118
    def __init__(self, pattern, callback, default_args: dict = None, name: str = None): ...
119
    
120
    def resolve(self, path: str) -> ResolverMatch: ...
121
    def __repr__(self) -> str: ...
122
    
123
    pattern: Any
124
    callback: Any
125
    default_args: dict
126
    name: str
127

128
class URLResolver:
129
    """URL resolver for handling included URL configurations."""
130
    def __init__(self, pattern, urlconf_name: str, default_kwargs: dict = None, app_name: str = None, namespace: str = None): ...
131
    
132
    def resolve(self, path: str) -> ResolverMatch: ...
133
    def reverse(self, lookup_view: str, *args, **kwargs) -> str: ...
134
    def __repr__(self) -> str: ...
135
    
136
    pattern: Any
137
    urlconf_name: str
138
    callback: Any
139
    default_kwargs: dict
140
    app_name: str
141
    namespace: str
142

143
class ResolverMatch:
144
    """Result of URL resolution containing view and parameters."""
145
    def __init__(self, func, args: tuple, kwargs: dict, url_name: str = None, app_names: list = None, namespaces: list = None, route: str = None): ...
146
    
147
    func: Any  # Resolved view function or class
148
    args: tuple  # Positional arguments from URL
149
    kwargs: dict  # Keyword arguments from URL
150
    url_name: str  # Name of matched URL pattern
151
    view_name: str  # Full dotted name of view
152
    app_names: list  # Application namespaces
153
    namespaces: list  # All namespaces
154
    app_name: str  # Current application namespace
155
    namespace: str  # Current namespace
156
    route: str  # Matched route pattern
157
```
158

159
### URL Configuration Management
160

161
Functions for managing URL configuration and caching.
162

163
```python { .api }
164
def get_resolver(urlconf: str = None):
165
    """
166
    Get URL resolver for the given configuration.
167
    
168
    Args:
169
        urlconf (str, optional): URL configuration module path
170
    
171
    Returns:
172
        URLResolver: Main URL resolver instance
173
    """
174

175
def get_ns_resolver(ns_pattern: str, resolver, converters: dict):
176
    """Get namespace resolver for the given pattern."""
177

178
def get_callable(lookup_view):
179
    """
180
    Convert string view name to callable view function.
181
    
182
    Args:
183
        lookup_view: String path or callable view
184
    
185
    Returns:
186
        callable: View function or class
187
    """
188

189
def get_mod_func(callback: str) -> tuple:
190
    """
191
    Split callback string into module and function names.
192
    
193
    Args:
194
        callback (str): Dotted path to callback
195
    
196
    Returns:
197
        tuple: (module_name, function_name)
198
    """
199

200
def clear_url_caches() -> None:
201
    """Clear all URL resolver caches."""
202

203
def set_script_prefix(prefix: str) -> None:
204
    """Set script prefix for URL generation."""
205

206
def get_script_prefix() -> str:
207
    """Get current script prefix."""
208

209
def clear_script_prefix() -> None:
210
    """Clear script prefix."""
211

212
def set_urlconf(urlconf_name: str) -> None:
213
    """Set URL configuration for current thread."""
214

215
def get_urlconf(default: str = None) -> str:
216
    """Get URL configuration for current thread."""
217
```
218

219
### URL Validation and Utilities
220

221
Utility functions for URL validation and processing.
222

223
```python { .api }
224
def is_valid_path(path: str, urlconf: str = None) -> bool:
225
    """
226
    Check if URL path is valid (can be resolved).
227
    
228
    Args:
229
        path (str): URL path to validate
230
        urlconf (str, optional): URL configuration to use
231
    
232
    Returns:
233
        bool: True if path can be resolved
234
    """
235

236
def translate_url(url: str, lang_code: str) -> str:
237
    """
238
    Translate URL to given language code.
239
    
240
    Args:
241
        url (str): URL to translate
242
        lang_code (str): Target language code
243
    
244
    Returns:
245
        str: Translated URL
246
    """
247
```
248

249
### URL Converters
250

251
Path converters for extracting typed parameters from URLs.
252

253
```python { .api }
254
def register_converter(converter_class: type, type_name: str) -> None:
255
    """
256
    Register custom URL parameter converter.
257
    
258
    Args:
259
        converter_class (type): Converter class with to_python and to_url methods
260
        type_name (str): Name to use in URL patterns
261
    """
262

263
class IntConverter:
264
    """Converter for integer URL parameters."""
265
    regex: str = '[0-9]+'
266
    
267
    def to_python(self, value: str) -> int: ...
268
    def to_url(self, value: int) -> str: ...
269

270
class StringConverter:
271
    """Converter for string URL parameters."""
272
    regex: str = '[^/]+'
273
    
274
    def to_python(self, value: str) -> str: ...
275
    def to_url(self, value: str) -> str: ...
276

277
class UUIDConverter:
278
    """Converter for UUID URL parameters."""
279
    regex: str = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
280
    
281
    def to_python(self, value: str): ...
282
    def to_url(self, value) -> str: ...
283

284
class SlugConverter:
285
    """Converter for slug URL parameters."""
286
    regex: str = '[-a-zA-Z0-9_]+'
287
    
288
    def to_python(self, value: str) -> str: ...
289
    def to_url(self, value: str) -> str: ...
290

291
class PathConverter:
292
    """Converter for path URL parameters (including slashes)."""
293
    regex: str = '.+'
294
    
295
    def to_python(self, value: str) -> str: ...
296
    def to_url(self, value: str) -> str: ...
297
```
298

299
### URL Exceptions
300

301
Exception classes for URL resolution and reverse lookup errors.
302

303
```python { .api }
304
class Resolver404(Exception):
305
    """
306
    Raised when URL resolution fails.
307
    
308
    Indicates that no URL pattern matched the requested path.
309
    """
310
    pass
311

312
class NoReverseMatch(Exception):
313
    """
314
    Raised when reverse URL lookup fails.
315
    
316
    Indicates that no URL pattern matches the given view name and parameters.
317
    """
318
    pass
319
```
320

321
### URL Pattern Matching
322

323
Internal classes for URL pattern compilation and matching.
324

325
```python { .api }
326
class LocalePrefixPattern:
327
    """Pattern for matching locale prefixes in internationalized URLs."""
328
    def __init__(self, prefix_default_language: bool = True): ...
329
    
330
    def match(self, path: str) -> tuple: ...
331
    def check(self) -> list: ...
332
    def describe(self) -> str: ...
333
    
334
    converters: dict
335

336
class RoutePattern:
337
    """Pattern for path-style URL routing with parameter extraction."""
338
    def __init__(self, route: str, name: str = None, is_endpoint: bool = False): ...
339
    
340
    def match(self, path: str) -> tuple: ...
341
    def check(self) -> list: ...
342
    def describe(self) -> str: ...
343
    
344
    regex: Any
345
    converters: dict
346

347
class RegexPattern:
348
    """Pattern for regex-style URL routing with group capture."""
349
    def __init__(self, regex: str, name: str = None, is_endpoint: bool = False): ...
350
    
351
    def match(self, path: str) -> tuple: ...
352
    def check(self) -> list: ...
353
    def describe(self) -> str: ...
354
    
355
    regex: Any
356
```
357

358
### Internationalization Support
359

360
URL internationalization utilities for multi-language sites.
361

362
```python { .api }
363
def i18n_patterns(*urls, prefix_default_language: bool = True):
364
    """
365
    Add language prefix to URL patterns for internationalization.
366
    
367
    Args:
368
        urls: URL patterns to internationalize
369
        prefix_default_language (bool): Whether to prefix default language
370
    
371
    Returns:
372
        list: Internationalized URL patterns
373
    """
374

375
def is_language_prefix_patterns_used(urlconf: str = None) -> bool:
376
    """Check if language prefix patterns are used in URL configuration."""
377
```
378

379
### URL Types
380

381
Type aliases for URL pattern collections.
382

383
```python { .api }
384
_AnyURL = URLPattern | URLResolver  # Union type for URL patterns and resolvers
385
```