__init__.py (29310B)
1 """ 2 sphinxcontrib.httpdomain 3 ~~~~~~~~~~~~~~~~~~~~~~~~ 4 5 Domains for documenting HTTP APIs and WebSocket connections. 6 7 :copyright: Copyright 2011 by Hong Minhee 8 :license: BSD, see LICENSE for details. 9 10 """ 11 12 import re 13 import os 14 15 from docutils import nodes 16 17 from pygments.lexer import RegexLexer, bygroups 18 from pygments.lexers import get_lexer_by_name 19 from pygments.token import Literal, Text, Operator, Keyword, Name, Number 20 from pygments.util import ClassNotFound 21 22 from sphinx import addnodes 23 from sphinx.roles import XRefRole 24 from sphinx.domains import Domain, ObjType, Index 25 from sphinx.directives import ObjectDescription, directives 26 from sphinx.util import logging 27 from sphinx.util.nodes import make_refnode 28 from sphinx.util.docfields import GroupedField, TypedField 29 from sphinx.util.docutils import Reporter, LoggingReporter 30 from sphinx.locale import get_translation 31 from ._path_signature import render_path_signature 32 from .websocket import WebSocketDomain 33 _ = get_translation('httpdomain') 34 35 logger = logging.getLogger(__name__) 36 37 38 class DummyDocument(object): 39 """Used where the signature requires a docutils.node.Document but only its reporter 40 is being used. 41 42 Up until the current Sphinx 2.3.1 calls to env.get_doctree() (which would get 43 us said docutils.node.Document) result in pickle.load() calls which are expensive 44 enough to dominate the runtime entirely when the number of endpoints and references 45 is large enough. 46 """ 47 48 def __init__(self, reporter): 49 self.reporter = reporter 50 51 52 class DocRef(object): 53 """Represents a reference to an abstract specification.""" 54 55 def __init__(self, base_url, anchor, section): 56 self.base_url = base_url 57 self.anchor = anchor 58 self.section = section 59 60 def __repr__(self): 61 """Returns the URL onto related specification section for the related 62 object.""" 63 return '{0}#{1}{2}'.format(self.base_url, self.anchor, self.section) 64 65 66 class RFC2616Ref(DocRef): 67 """Represents a reference to RFC2616. 68 In 2014, RFC2616 was replaced by multiple RFCs (7230-7237).""" 69 70 def __init__(self, section): 71 url = 'https://www.w3.org/Protocols/rfc2616/rfc2616-sec{0:d}.html' 72 url = url.format(int(section)) 73 super(RFC2616Ref, self).__init__(url, 'sec', section) 74 75 76 class IETFRef(DocRef): 77 """Represents a reference to the specific IETF RFC.""" 78 79 def __init__(self, rfc, section): 80 url = 'https://www.rfc-editor.org/info/rfc{0:d}'.format(rfc) 81 super(IETFRef, self).__init__(url, 'section-', section) 82 83 84 class EventSourceRef(DocRef): 85 86 def __init__(self, section): 87 url = 'https://html.spec.whatwg.org/multipage/server-sent-events.html' 88 super(EventSourceRef, self).__init__(url, section, '') 89 90 91 class CORSRef(DocRef): 92 """Represents a reference to W3 Cross-Origin Resource Sharing recommendation.""" 93 94 def __init__(self, name, type): 95 url = 'https://www.w3.org/TR/cors/' 96 super(CORSRef, self).__init__(url, name, '-' + type) 97 98 99 #: Mapping from lowercase HTTP method name to :class:`DocRef` object which 100 #: maintains the URL which points to the section of the RFC which defines that 101 #: HTTP method. 102 METHOD_REFS = { 103 'patch': IETFRef(5789, 2), 104 'options': IETFRef(7231, '4.3.7'), 105 'get': IETFRef(7231, '4.3.1'), 106 'head': IETFRef(7231, '4.3.2'), 107 'post': IETFRef(7231, '4.3.3'), 108 'put': IETFRef(7231, '4.3.4'), 109 'delete': IETFRef(7231, '4.3.5'), 110 'trace': IETFRef(7231, '4.3.8'), 111 'connect': IETFRef(7231, '4.3.6'), 112 'copy': IETFRef(2518, 8.8), 113 'query': IETFRef(10008, 2), 114 'any': '' 115 } 116 117 118 #: Mapping from HTTP header name to :class:`DocRef` object which 119 #: maintains the URL which points to the related section of the RFC. 120 HEADER_REFS = { 121 'Accept': IETFRef(7231, '5.3.2'), 122 'Accept-Charset': IETFRef(7231, '5.3.3'), 123 'Accept-Encoding': IETFRef(7231, '5.3.4'), 124 'Accept-Language': IETFRef(7231, '5.3.5'), 125 'Accept-Query': IETFRef(10008, 3), 126 'Accept-Ranges': IETFRef(7233, 2.3), 127 'Age': IETFRef(7234, 5.1), 128 'Allow': IETFRef(7231, '7.4.1'), 129 'Authorization': IETFRef(7235, 4.2), 130 'Cache-Control': IETFRef(7234, 5.2), 131 'Connection': IETFRef(7230, 6.1), 132 'Content-Encoding': IETFRef(7231, '3.1.2.2'), 133 'Content-Language': IETFRef(7231, '3.1.3.2'), 134 'Content-Length': IETFRef(7230, '3.3.2'), 135 'Content-Location': IETFRef(7231, '3.1.4.2'), 136 'Content-MD5': RFC2616Ref(14.15), # removed 137 'Content-Range': IETFRef(7233, 4.2), 138 'Content-Type': IETFRef(7231, '3.1.1.5'), 139 'Cookie': IETFRef(2109, '4.3.4'), # also RFC6265 section 5.4 140 'Date': IETFRef(7231, '7.1.1.2'), 141 'Destination': IETFRef(2518, 9.3), 142 'ETag': IETFRef(7232, 2.3), 143 'Expect': IETFRef(7231, '5.1.1'), 144 'Expires': IETFRef(7234, 5.3), 145 'From': IETFRef(7231, '5.5.2'), 146 'Host': IETFRef(7230, 5.4), 147 'If-Match': IETFRef(7232, 3.1), 148 'If-Modified-Since': IETFRef(7232, 3.3), 149 'If-None-Match': IETFRef(7232, 3.2), 150 'If-Range': IETFRef(7233, 3.2), 151 'If-Unmodified-Since': IETFRef(7232, 3.4), 152 'Last-Event-ID': EventSourceRef('last-event-id'), 153 'Last-Modified': IETFRef(7232, 2.2), 154 'Link': IETFRef(5988, '5'), 155 'Location': IETFRef(7231, '7.1.2'), 156 'Max-Forwards': IETFRef(7231, '5.1.2'), 157 'Pragma': IETFRef(7234, 5.4), 158 'Proxy-Authenticate': IETFRef(7235, 4.3), 159 'Proxy-Authorization': IETFRef(7235, 4.4), 160 'Range': IETFRef(7233, 3.1), 161 'Referer': IETFRef(7231, '5.5.2'), 162 'Retry-After': IETFRef(7231, '7.1.3'), 163 'Server': IETFRef(7231, '7.4.2'), 164 'Set-Cookie': IETFRef(2109, '4.2.2'), 165 'TE': IETFRef(7230, 4.3), 166 'Trailer': IETFRef(7230, 4.4), 167 'Transfer-Encoding': IETFRef(7230, '3.3.1'), 168 'Upgrade': IETFRef(7230, 6.7), 169 'User-Agent': IETFRef(7231, '5.5.3'), 170 'Vary': IETFRef(7231, '7.1.4'), 171 'Via': IETFRef(7230, '5.7.1'), 172 'Warning': IETFRef(7234, 5.5), 173 'WWW-Authenticate': IETFRef(7235, 4.1), 174 'Access-Control-Allow-Origin': CORSRef('access-control-allow-origin', 175 'response-header'), 176 'Access-Control-Allow-Credentials': CORSRef('access-control-allow-credentials', 177 'response-header'), 178 'Access-Control-Expose-Headers': CORSRef('access-control-expose-headers', 179 'response-header'), 180 'Access-Control-Max-Age': CORSRef('access-control-max-age', 181 'response-header'), 182 'Access-Control-Allow-Methods': CORSRef('access-control-allow-methods', 183 'response-header'), 184 'Access-Control-Allow-Headers': CORSRef('access-control-allow-headers', 185 'response-header'), 186 'Origin': CORSRef('origin', 'request-header'), 187 'Access-Control-Request-Method': CORSRef('access-control-request-method', 188 'response-header'), 189 'Access-Control-Request-Headers': CORSRef('access-control-request-headers', 190 'response-header'), 191 } 192 193 194 HTTP_STATUS_CODES = { 195 100: 'Continue', 196 101: 'Switching Protocols', 197 102: 'Processing', 198 200: 'OK', 199 201: 'Created', 200 202: 'Accepted', 201 203: 'Non Authoritative Information', 202 204: 'No Content', 203 205: 'Reset Content', 204 206: 'Partial Content', 205 207: 'Multi Status', 206 226: 'IM Used', # see RFC 3229 207 300: 'Multiple Choices', 208 301: 'Moved Permanently', 209 302: 'Found', 210 303: 'See Other', 211 304: 'Not Modified', 212 305: 'Use Proxy', 213 307: 'Temporary Redirect', 214 308: 'Permanent Redirect', 215 400: 'Bad Request', 216 401: 'Unauthorized', 217 402: 'Payment Required', # unused 218 403: 'Forbidden', 219 404: 'Not Found', 220 405: 'Method Not Allowed', 221 406: 'Not Acceptable', 222 407: 'Proxy Authentication Required', 223 408: 'Request Timeout', 224 409: 'Conflict', 225 410: 'Gone', 226 411: 'Length Required', 227 412: 'Precondition Failed', 228 413: 'Request Entity Too Large', 229 414: 'URI Too Long', 230 415: 'Unsupported Media Type', 231 416: 'Requested Range Not Satisfiable', 232 417: 'Expectation Failed', 233 418: "I'm a teapot", # see RFC 2324 234 422: 'Unprocessable Entity', 235 423: 'Locked', 236 424: 'Failed Dependency', 237 425: 'Too Early', # RFC 8470 238 426: 'Upgrade Required', 239 429: 'Too Many Requests', 240 449: 'Retry With', # proprietary MS extension 241 451: 'Unavailable For Legal Reasons', 242 500: 'Internal Server Error', 243 501: 'Not Implemented', 244 502: 'Bad Gateway', 245 503: 'Service Unavailable', 246 504: 'Gateway Timeout', 247 505: 'HTTP Version Not Supported', 248 507: 'Insufficient Storage', 249 510: 'Not Extended' 250 } 251 252 WEBDAV_STATUS_CODES = [207, 422, 423, 424, 507] 253 254 def sort_by_method(entries): 255 def cmp(item): 256 order = ['HEAD', 'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 257 'OPTIONS', 'TRACE', 'CONNECT', 'COPY', 'ANY'] 258 method = item[0].split(' ', 1)[0] 259 if method in order: 260 return order.index(method) 261 return 100 262 return sorted(entries, key=cmp) 263 264 265 def http_resource_anchor(method, path): 266 path = re.sub(r'[{}]', '', re.sub(r'[<>:/]', '-', path)) 267 return method.lower() + '-' + path 268 269 270 class HTTPResource(ObjectDescription): 271 272 doc_field_types = [ 273 TypedField('parameter', label=_('Parameters'), 274 names=('param', 'parameter', 'arg', 'argument'), 275 typenames=('paramtype', 'type')), 276 TypedField('jsonparameter', label=_('JSON Parameters'), 277 names=('jsonparameter', 'jsonparam', 'json'), 278 typenames=('jsonparamtype', 'jsontype')), 279 TypedField('requestjsonobject', label=_('Request JSON Object'), 280 names=('reqjsonobj', 'reqjson', '>jsonobj', '>json'), 281 typenames=('reqjsonobj', '>jsonobj')), 282 TypedField('requestjsonarray', label=_('Request JSON Array of Objects'), 283 names=('reqjsonarr', '>jsonarr'), 284 typenames=('reqjsonarrtype', '>jsonarrtype')), 285 TypedField('responsejsonobject', label=_('Response JSON Object'), 286 names=('resjsonobj', 'resjson', '<jsonobj', '<json'), 287 typenames=('resjsonobj', '<jsonobj')), 288 TypedField('responsejsonarray', label=_('Response JSON Array of Objects'), 289 names=('resjsonarr', '<jsonarr'), 290 typenames=('resjsonarrtype', '<jsonarrtype')), 291 TypedField('queryparameter', label=_('Query Parameters'), 292 names=('queryparameter', 'queryparam', 'qparam', 'query'), 293 typenames=('queryparamtype', 'querytype', 'qtype')), 294 GroupedField('formparameter', label=_('Form Parameters'), 295 names=('formparameter', 'formparam', 'fparam', 'form')), 296 GroupedField('requestheader', label=_('Request Headers'), 297 rolename='header', 298 names=('>header', 'reqheader', 'requestheader')), 299 GroupedField('responseheader', label=_('Response Headers'), 300 rolename='header', 301 names=('<header', 'resheader', 'responseheader')), 302 GroupedField('statuscode', label=_('Status Codes'), 303 rolename='statuscode', 304 names=('statuscode', 'status', 'code')) 305 ] 306 307 option_spec = { 308 'deprecated': directives.flag, 309 'noindex': directives.flag, 310 'addtoc': directives.flag, 311 'synopsis': lambda x: x, 312 } 313 314 method = NotImplemented 315 noindex = False 316 317 def run(self): 318 # ObjectDescription.run() skips add_target_and_index() entirely when 319 # the noindex option is set, which would drop the per-page anchor 320 # along with the global registration. Anchors are per-document ids 321 # and cannot collide across pages, so pop the option before running 322 # the base class and gate only the registration in 323 # add_target_and_index(). 324 self.noindex = 'noindex' in self.options 325 self.options.pop('noindex', None) 326 nodes = super().run() 327 if self.noindex: 328 for node in nodes: 329 if isinstance(node, addnodes.desc): 330 node['noindex'] = node['no-index'] = True 331 return nodes 332 333 def handle_signature(self, sig, signode): 334 method = self.method.upper() + ' ' 335 signode += addnodes.desc_name(method, method) 336 path = render_path_signature(sig, signode) 337 fullname = self.method.upper() + ' ' + path 338 signode['method'] = self.method 339 signode['path'] = sig 340 signode['fullname'] = fullname 341 return (fullname, self.method, sig) 342 343 def needs_arglist(self): 344 return False 345 346 def add_target_and_index(self, name_cls, sig, signode): 347 signode['ids'].append(http_resource_anchor(*name_cls[1:])) 348 if not self.noindex: 349 self.env.domaindata['http'][self.method][sig] = ( 350 self.env.docname, 351 self.options.get('synopsis', ''), 352 'deprecated' in self.options) 353 354 def get_index_text(self, modname, name): 355 return '' 356 357 def _object_hierarchy_parts(self, sig_node): 358 if 'addtoc' in self.options: 359 if 'fullname' not in sig_node: 360 return () 361 path = sig_node.get('path') 362 method = sig_node.get('method') 363 if not path or not sig_node: 364 return () 365 return tuple(path.split('/')) + (method, sig_node['fullname']) 366 return () 367 368 def _toc_entry_name(self, sig_node): 369 if 'addtoc' in self.options: 370 if not sig_node.get('_toc_parts'): 371 return '' 372 373 return sig_node['_toc_parts'][-1] 374 return '' 375 376 377 class HTTPOptions(HTTPResource): 378 379 method = 'options' 380 381 382 class HTTPHead(HTTPResource): 383 384 method = 'head' 385 386 387 class HTTPPatch(HTTPResource): 388 389 method = 'patch' 390 391 392 class HTTPPost(HTTPResource): 393 394 method = 'post' 395 396 397 class HTTPGet(HTTPResource): 398 399 method = 'get' 400 401 402 class HTTPPut(HTTPResource): 403 404 method = 'put' 405 406 407 class HTTPDelete(HTTPResource): 408 409 method = 'delete' 410 411 412 class HTTPTrace(HTTPResource): 413 414 method = 'trace' 415 416 417 class HTTPConnect(HTTPResource): 418 419 method = 'connect' 420 421 422 class HTTPCopy(HTTPResource): 423 424 method = 'copy' 425 426 427 class HTTPAny(HTTPResource): 428 429 method = 'any' 430 431 432 class HTTPXRefRole(XRefRole): 433 434 def __init__(self, method, **kwargs): 435 XRefRole.__init__(self, **kwargs) 436 self.method = method 437 438 def process_link(self, env, refnode, has_explicit_title, title, target): 439 if not has_explicit_title: 440 title = self.method.upper() + ' ' + title 441 return title, target 442 443 def result_nodes(self, document, env, node, is_ref): 444 return [node], [] 445 446 447 class HTTPXRefMethodRole(XRefRole): 448 449 def result_nodes(self, document, env, node, is_ref): 450 method = node[0][0].lower() 451 rawsource = node[0].rawsource 452 config = env.domains['http'].env.config 453 if method not in METHOD_REFS: 454 if not config['http_strict_mode']: 455 return [nodes.emphasis(method, method)], [] 456 reporter = document.reporter 457 msg = reporter.error('%s is not valid HTTP method' % method, 458 line=node.line) 459 prb = nodes.problematic(method, method) 460 return [prb], [msg] 461 url = str(METHOD_REFS[method]) 462 if not url: 463 return [nodes.emphasis(method, method)], [] 464 node = nodes.reference(rawsource, method.upper(), refuri=url) 465 return [node], [] 466 467 468 class HTTPXRefStatusRole(XRefRole): 469 470 def result_nodes(self, document, env, node, is_ref): 471 def get_code_status(text): 472 if text.isdigit(): 473 code = int(text) 474 return code, HTTP_STATUS_CODES.get(code) 475 else: 476 try: 477 code, status = re.split(r'\s', text.strip(), 1) 478 code = int(code) 479 except ValueError: 480 return None, None 481 known_status = HTTP_STATUS_CODES.get(code) 482 if known_status is None: 483 return code, None 484 elif known_status.lower() != status.lower(): 485 return code, None 486 else: 487 return code, status 488 489 def report_unknown_code(): 490 if not config['http_strict_mode']: 491 return [nodes.emphasis(text, text)], [] 492 reporter = document.reporter 493 msg = reporter.error('%d is unknown HTTP status code' % code, 494 line=node.line) 495 prb = nodes.problematic(text, text) 496 return [prb], [msg] 497 498 def report_invalid_code(): 499 if not config['http_strict_mode']: 500 return [nodes.emphasis(text, text)], [] 501 reporter = document.reporter 502 msg = reporter.error( 503 'HTTP status code must be an integer (e.g. `200`) or ' 504 'start with an integer (e.g. `200 OK`); %r is invalid' % 505 text, 506 line=node.line 507 ) 508 prb = nodes.problematic(text, text) 509 return [prb], [msg] 510 511 text = node[0][0] 512 rawsource = node[0].rawsource 513 config = env.domains['http'].env.config 514 515 code, status = get_code_status(text) 516 if code is None: 517 return report_invalid_code() 518 elif status is None: 519 return report_unknown_code() 520 elif code == 449: 521 url = 'https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-wdv/83ecf19f-e0f8-4706-aae5-ba618f52f100' 522 elif code in HTTP_STATUS_CODES or code in WEBDAV_STATUS_CODES: 523 url = f"https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/{code}" 524 else: 525 url = '' 526 node = nodes.reference(rawsource, '%d %s' % (code, status), refuri=url) 527 return [node], [] 528 529 530 class HTTPXRefHeaderRole(XRefRole): 531 532 def result_nodes(self, document, env, node, is_ref): 533 header = node[0][0] 534 rawsource = node[0].rawsource 535 if header not in HEADER_REFS: 536 _header = '-'.join(map(lambda i: i.title(), header.split('-'))) 537 if _header not in HEADER_REFS: 538 return [nodes.emphasis(header, header)], [] 539 url = str(HEADER_REFS[header]) 540 node = nodes.reference(rawsource, header, refuri=url) 541 return [node], [] 542 543 544 class HTTPIndex(Index): 545 546 name = 'routingtable' 547 localname = _('HTTP Routing Table') 548 shortname = 'routing table' 549 550 def __init__(self, *args, **kwargs): 551 super(HTTPIndex, self).__init__(*args, **kwargs) 552 553 self.ignore = [ 554 [l for l in x.split('/') if l] 555 for x in self.domain.env.config['http_index_ignore_prefixes']] 556 self.ignore.sort(reverse=True) 557 558 # During HTML generation these values pick from class, 559 # not from instance so we have a little hack the system 560 cls = self.__class__ 561 cls.shortname = self.domain.env.config['http_index_shortname'] 562 cls.localname = self.domain.env.config['http_index_localname'] 563 564 def grouping_prefix(self, path): 565 letters = [x for x in path.split('/') if x] 566 for prefix in self.ignore: 567 if letters[:len(prefix)] == prefix: 568 return '/' + '/'.join(letters[:len(prefix) + 1]) 569 return '/%s' % (letters[0] if letters else '',) 570 571 def generate(self, docnames=None): 572 content = {} 573 items = ((method, path, info) 574 for method, routes in self.domain.routes.items() 575 for path, info in routes.items()) 576 items = sorted(items, key=lambda item: item[1]) 577 for method, path, info in items: 578 entries = content.setdefault(self.grouping_prefix(path), []) 579 entries.append([ 580 method.upper() + ' ' + path, 0, info[0], 581 http_resource_anchor(method, path), 582 '', _('Deprecated') if info[2] else '', info[1] 583 ]) 584 items = sorted( 585 (path, sort_by_method(entries)) 586 for path, entries in content.items() 587 ) 588 return (items, True) 589 590 591 class HTTPDomain(Domain): 592 """HTTP domain.""" 593 594 name = 'http' 595 label = 'HTTP' 596 597 object_types = { 598 'options': ObjType('options', 'options'), 599 'head': ObjType('head', 'head'), 600 'post': ObjType('post', 'post'), 601 'get': ObjType('get', 'get'), 602 'put': ObjType('put', 'put'), 603 'patch': ObjType('patch', 'patch'), 604 'delete': ObjType('delete', 'delete'), 605 'trace': ObjType('trace', 'trace'), 606 'connect': ObjType('connect', 'connect'), 607 'copy': ObjType('copy', 'copy'), 608 'any': ObjType('any', 'any') 609 } 610 611 directives = { 612 'options': HTTPOptions, 613 'head': HTTPHead, 614 'post': HTTPPost, 615 'get': HTTPGet, 616 'put': HTTPPut, 617 'patch': HTTPPatch, 618 'delete': HTTPDelete, 619 'trace': HTTPTrace, 620 'connect': HTTPConnect, 621 'copy': HTTPCopy, 622 'any': HTTPAny 623 } 624 625 roles = { 626 'options': HTTPXRefRole('options'), 627 'head': HTTPXRefRole('head'), 628 'post': HTTPXRefRole('post'), 629 'get': HTTPXRefRole('get'), 630 'put': HTTPXRefRole('put'), 631 'patch': HTTPXRefRole('patch'), 632 'delete': HTTPXRefRole('delete'), 633 'trace': HTTPXRefRole('trace'), 634 'connect': HTTPXRefRole('connect'), 635 'copy': HTTPXRefRole('copy'), 636 'any': HTTPXRefRole('any'), 637 'statuscode': HTTPXRefStatusRole(), 638 'method': HTTPXRefMethodRole(), 639 'header': HTTPXRefHeaderRole() 640 } 641 642 initial_data = { 643 'options': {}, # path: (docname, synopsis) 644 'head': {}, 645 'post': {}, 646 'get': {}, 647 'put': {}, 648 'patch': {}, 649 'delete': {}, 650 'trace': {}, 651 'connect': {}, 652 'copy': {}, 653 'any': {} 654 } 655 656 # GNUnet: no HTTP routing table index page (local change, see README). 657 indices = [] 658 659 @property 660 def routes(self): 661 return dict((key, self.data[key]) for key in self.object_types) 662 663 def clear_doc(self, docname): 664 for typ, routes in self.routes.items(): 665 for path, info in list(routes.items()): 666 if info[0] == docname: 667 del routes[path] 668 669 def resolve_xref(self, env, fromdocname, builder, typ, target, 670 node, contnode): 671 try: 672 info = self.data[str(typ)][target] 673 except KeyError: 674 text = contnode.rawsource 675 role = self.roles.get(typ) 676 if role is None: 677 return None 678 679 reporter = LoggingReporter(env.doc2path(fromdocname), 680 report_level=Reporter.WARNING_LEVEL, 681 halt_level=Reporter.SEVERE_LEVEL) 682 doctree = DummyDocument(reporter) 683 resnode = role.result_nodes(doctree, env, node, None)[0][0] 684 if isinstance(resnode, addnodes.pending_xref): 685 text = node[0][0] 686 reporter = doctree.reporter 687 reporter.warning('Cannot resolve reference to %r' % text, 688 line=node.line) 689 return None 690 return resnode 691 else: 692 anchor = http_resource_anchor(typ, target) 693 title = typ.upper() + ' ' + target 694 return make_refnode(builder, fromdocname, info[0], anchor, 695 contnode, title) 696 697 def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode): 698 """Resolve the pending_xref *node* with the given *target*. 699 700 The reference comes from an "any" or similar role, which means that Sphinx 701 don't know the type. 702 703 For now sphinxcontrib-httpdomain doesn't resolve any xref nodes. 704 705 :return: 706 list of tuples ``('domain:role', newnode)``, where ``'domain:role'`` 707 is the name of a role that could have created the same reference, 708 """ 709 return [] 710 711 def get_objects(self): 712 for method, routes in self.routes.items(): 713 for path, info in routes.items(): 714 anchor = http_resource_anchor(method, path) 715 yield (path, path, method, info[0], anchor, 1) 716 717 def merge_domaindata(self, docnames, otherdata): 718 """Merge domaindata from the workers/chunks when they return. 719 720 Called once per parallelization chunk. 721 Only used when sphinx is run in parallel mode. 722 723 :param docnames: a Set of the docnames that are part of the current chunk to merge 724 :param otherdata: the partial data calculated by the current chunk 725 """ 726 for typ in self.object_types: 727 self_data = self.data[typ] 728 other_data = otherdata[typ] 729 for entry_point_name, entry_point_data in other_data.items(): 730 if entry_point_name in self_data and entry_point_data != self_data[entry_point_name]: 731 logger.warning('duplicate HTTP %s method definition %s in %s, ' 732 'other instance is in %s' % 733 (typ, entry_point_name, 734 self.env.doc2path(other_data[entry_point_name][0]), 735 self.env.doc2path(self_data[entry_point_name][0]))) 736 else: 737 self_data[entry_point_name] = entry_point_data 738 739 class HTTPLexer(RegexLexer): 740 """Lexer for HTTP sessions.""" 741 742 name = 'HTTP' 743 aliases = ['http'] 744 745 flags = re.DOTALL 746 747 def header_callback(self, match): 748 if match.group(1).lower() == 'content-type': 749 content_type = match.group(5).strip() 750 if ';' in content_type: 751 content_type = content_type[:content_type.find(';')].strip() 752 self.content_type = content_type 753 yield match.start(1), Name.Attribute, match.group(1) 754 yield match.start(2), Text, match.group(2) 755 yield match.start(3), Operator, match.group(3) 756 yield match.start(4), Text, match.group(4) 757 yield match.start(5), Literal, match.group(5) 758 yield match.start(6), Text, match.group(6) 759 760 def continuous_header_callback(self, match): 761 yield match.start(1), Text, match.group(1) 762 yield match.start(2), Literal, match.group(2) 763 yield match.start(3), Text, match.group(3) 764 765 def content_callback(self, match): 766 content_type = getattr(self, 'content_type', None) 767 content = match.group() 768 offset = match.start() 769 if content_type: 770 from pygments.lexers import get_lexer_for_mimetype 771 try: 772 lexer = get_lexer_for_mimetype(content_type) 773 except ClassNotFound: 774 pass 775 else: 776 for idx, token, value in lexer.get_tokens_unprocessed(content): 777 yield offset + idx, token, value 778 return 779 yield offset, Text, content 780 781 tokens = { 782 'root': [ 783 (r'(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE|COPY)( +)([^ ]+)( +)' 784 r'(HTTPS?)(/)(1\.[01])(\r?\n|$)', 785 bygroups(Name.Function, Text, Name.Namespace, Text, 786 Keyword.Reserved, Operator, Number, Text), 787 'headers'), 788 (r'(HTTPS?)(/)(1\.[01])( +)(\d{3})( +)([^\r\n]+)(\r?\n|$)', 789 bygroups(Keyword.Reserved, Operator, Number, Text, Number, 790 Text, Name.Exception, Text), 791 'headers'), 792 ], 793 'headers': [ 794 (r'([^\s:]+)( *)(:)( *)([^\r\n]+)(\r?\n|$)', header_callback), 795 (r'([\t ]+)([^\r\n]+)(\r?\n|$)', continuous_header_callback), 796 (r'\r?\n', Text, 'content') 797 ], 798 'content': [ 799 (r'.+', content_callback) 800 ] 801 } 802 803 804 def register_routingtable_as_label(app, document): 805 labels = app.env.domaindata['std']['labels'] 806 labels['routingtable'] = 'http-routingtable', '', _('HTTP Routing Table') 807 anonlabels = app.env.domaindata['std']['anonlabels'] 808 anonlabels['routingtable'] = 'http-routingtable', '' 809 810 811 def setup(app): 812 app.add_domain(HTTPDomain) 813 app.add_domain(WebSocketDomain) 814 app.connect('doctree-read', register_routingtable_as_label) 815 816 package_dir = os.path.abspath(os.path.dirname(__file__)) 817 locale_dir = os.path.join(package_dir, 'locale') 818 app.add_message_catalog('httpdomain', locale_dir) 819 820 try: 821 get_lexer_by_name('http') 822 except ClassNotFound: 823 app.add_lexer('http', HTTPLexer()) 824 app.add_config_value('http_index_ignore_prefixes', [], None) 825 app.add_config_value('http_index_shortname', 'routing table', True) 826 app.add_config_value('http_index_localname', _('HTTP Routing Table'), True) 827 app.add_config_value('http_strict_mode', True, None) 828 app.add_config_value('http_headers_ignore_prefixes', ['X-'], None) 829 return {"parallel_read_safe": True, 830 "parallel_write_safe": True}