sphinxcontrib-httpexample 2.0__py3-none-any.whl

sphinxcontrib/httpexample/__init__.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+from importlib import metadata
+from sphinxcontrib.httpexample.directives import HTTPExample
+from sphinxcontrib.httpexample.directives import HTTPExampleBlock
+from sphinxcontrib.httpexample.directives import register_builder
+from sphinxcontrib.httpexample.lexers import HTTPResponseLexer
+from sphinxcontrib.httpexample.parsers import HTTPRequest
+import os
+import shutil
+
+
+CSS_FILE = "sphinxcontrib-httpexample.css"
+JS_FILE = "sphinxcontrib-httpexample.js"
+
+
+def copy_assets(app, exception):
+    if app.builder.name != "html" or exception:
+        return
+
+    # CSS
+    src = os.path.join(os.path.dirname(__file__), "static", CSS_FILE)
+    dst = os.path.join(app.builder.outdir, "_static", CSS_FILE)
+    shutil.copyfile(src, dst)
+
+    # JS
+    src = os.path.join(os.path.dirname(__file__), "static", JS_FILE)
+    dst = os.path.join(app.builder.outdir, "_static", JS_FILE)
+    shutil.copyfile(src, dst)
+
+
+def setup(app):
+    app.connect("build-finished", copy_assets)
+    app.add_directive_to_domain("http", "example", HTTPExample)
+    app.add_directive_to_domain("http", "example-block", HTTPExampleBlock)
+    app.add_js_file(JS_FILE)
+    app.add_css_file(CSS_FILE)
+    app.add_config_value("httpexample_scheme", "http", "html")
+    app.add_lexer("http-response", HTTPResponseLexer)
+    dist = metadata.distribution("sphinxcontrib-httpexample")
+    return {"version": dist.version}

sphinxcontrib/httpexample/builders.py

@@ -0,0 +1,277 @@
+# -*- coding: utf-8 -*-
+from ast import unparse
+from io import StringIO
+from shlex import quote as shlex_quote
+from sphinxcontrib.httpexample.utils import is_json
+from sphinxcontrib.httpexample.utils import maybe_str
+from urllib.parse import parse_qs
+from urllib.parse import urlparse
+import ast
+import json
+import re
+import string
+
+
+_find_unsafe = re.compile(
+    r"[^\w@%+=:,./-" + string.ascii_letters + string.digits + "]",
+).search
+
+
+def shlex_double_quote(s):
+    """Return a shell-escaped version of the string *s*."""
+    if not s:
+        return '""'
+    if _find_unsafe(s) is None:
+        return s
+
+    # use double quotes, and put double quotes into single quotes
+    # the string $"b is then quoted as "$"'"'"b"
+    return re.sub(r'^""|""$', "", ('"' + s.replace('"', '"\'"\'"') + '"'))
+
+
+EXCLUDE_HEADERS = [
+    "Authorization",
+    "Host",
+]
+EXCLUDE_HEADERS_HTTP = EXCLUDE_HEADERS + []
+EXCLUDE_HEADERS_REQUESTS = EXCLUDE_HEADERS + []
+
+
+def build_curl_command(request):
+    parts = ["curl", "-i"]
+
+    # Method
+    parts.append("-X {}".format(request.command))
+
+    # URL
+    parts.append(shlex_quote(request.url()))
+
+    # Authorization (prepare)
+    method, token = request.auth()
+
+    # Headers
+    for header in sorted(request.headers):
+        if header in EXCLUDE_HEADERS:
+            continue
+        header_line = shlex_double_quote(
+            "{}: {}".format(header, request.headers[header]),
+        )
+        parts.append("-H {}".format(header_line))
+
+    if method != "Basic" and "Authorization" in request.headers:
+        header = "Authorization"
+        header_line = shlex_double_quote(
+            "{}: {}".format(header, request.headers[header]),
+        )
+        parts.append("-H {}".format(header_line))
+
+    # JSON
+    data = maybe_str(request.data())
+    if data:
+        if is_json(request.headers.get("Content-Type", "")):
+            data = json.dumps(data)
+        parts.append("--data-raw '{}'".format(data))
+
+    # Authorization
+    if method == "Basic":
+        parts.append("--user {}".format(token))
+
+    return " ".join(parts)
+
+
+def build_wget_command(request):
+    parts = ["wget", "-S", "-O-"]
+
+    # Method
+    if request.command not in ["GET", "POST"]:
+        parts.append("--method={}".format(request.command))
+
+    # URL
+    parts.append(shlex_quote(request.url()))
+
+    # Authorization (prepare)
+    method, token = request.auth()
+
+    # Headers
+    for header in sorted(request.headers):
+        if header in EXCLUDE_HEADERS:
+            continue
+        header_line = shlex_double_quote(
+            "{}: {}".format(header, request.headers[header]),
+        )
+        parts.append("--header={}".format(header_line))
+
+    if method != "Basic" and "Authorization" in request.headers:
+        header = "Authorization"
+        header_line = shlex_double_quote(
+            "{}: {}".format(header, request.headers[header])
+        )
+        parts.append("--header={}".format(header_line))
+
+    # JSON or raw data
+    data = maybe_str(request.data())
+    if data:
+        if is_json(request.headers.get("Content-Type", "")):
+            data = json.dumps(data)
+        if request.command == "POST":
+            parts.append("--post-data='{}'".format(data))
+        elif request.command != "POST":
+            parts.append("--body-data='{}'".format(data))
+
+    # Authorization
+    if method == "Basic":
+        user, password = token.split(":")
+        parts.append("--auth-no-challenge")
+        parts.append("--user={}".format(user))
+        parts.append("--password={}".format(password))
+
+    return " ".join(parts)
+
+
+def build_httpie_command(request):
+    parts = ["http"]
+    redir_input = ""
+
+    # Method
+    if request.command != "GET":
+        parts.append(request.command)
+
+    # URL
+    parts.append(shlex_quote(request.url()))
+
+    # Authorization (prepare)
+    method, token = request.auth()
+
+    # Headers
+    for header in sorted(request.headers):
+        if header in EXCLUDE_HEADERS_HTTP:
+            continue
+        parts.append(
+            "{}:{}".format(
+                header,
+                shlex_double_quote(request.headers[header]),
+            )
+        )
+
+    if method != "Basic" and "Authorization" in request.headers:
+        header = "Authorization"
+        parts.append(
+            "{}:{}".format(
+                header,
+                shlex_double_quote(request.headers[header]),
+            )
+        )
+
+    # JSON or raw data
+    data = maybe_str(request.data())
+    if data:
+
+        if is_json(request.headers.get("Content-Type", "")):
+            # We need to explicitly set the separators to get consistent
+            # whitespace handling across Python 2 and 3. See
+            # https://bugs.python.org/issue16333 for details.
+            redir_input = shlex_quote(
+                json.dumps(data, indent=2, sort_keys=True, separators=(",", ": "))
+            )
+        else:
+            redir_input = shlex_quote(data)
+
+    # Authorization
+    if method == "Basic":
+        parts.append("-a {}".format(token))
+
+    cmd = " ".join(parts)
+
+    if not redir_input:
+        return cmd
+
+    else:
+        return "echo {} | {}".format(redir_input, cmd)
+
+
+def flatten_parsed_qs(data):
+    """Flatten single value lists in parse_qs results."""
+    for key, value in data.items():
+        if isinstance(value, list) and len(value) == 1:
+            data[key] = value[0]
+    return data
+
+
+def build_requests_command(request):
+    # Method
+    tree = ast.parse("requests.{}()".format(request.command.lower()))
+    call = tree.body[0].value
+    call.keywords = []
+
+    # URL
+    call.args.append(ast.Constant(request.url()))
+
+    # Authorization (prepare)
+    method, token = request.auth()
+
+    # Headers
+    header_keys = []
+    header_values = []
+    for header in sorted(request.headers):
+        if header in EXCLUDE_HEADERS_REQUESTS:
+            continue
+        header_keys.append(ast.Constant(header))
+        header_values.append(ast.Constant(request.headers[header]))
+    if method != "Basic" and "Authorization" in request.headers:
+        header_keys.append(ast.Constant("Authorization"))
+        header_values.append(ast.Constant(request.headers["Authorization"]))
+    if header_keys and header_values:
+        call.keywords.append(
+            ast.keyword("headers", ast.Dict(header_keys, header_values))
+        )
+
+    # JSON or raw data
+    data = maybe_str(request.data())
+
+    # Form data
+    content_type = request.headers.get("Content-Type")
+    if content_type == "application/x-www-form-urlencoded":
+        if not isinstance(data, dict):
+            data = flatten_parsed_qs(parse_qs(data))
+
+    def astify_json_obj(obj):
+        obj = maybe_str(obj)
+        if isinstance(obj, str):
+            return ast.Constant(obj)
+        elif isinstance(obj, bool):
+            return ast.Name(str(obj), ast.Load())
+        elif isinstance(obj, int):
+            return ast.Name(str(obj), ast.Load())
+        elif isinstance(obj, float):
+            return ast.Name(str(obj), ast.Load())
+        elif isinstance(obj, list):
+            json_values = []
+            for v in obj:
+                json_values.append(astify_json_obj(v))
+            return ast.List(json_values, ast.Load())
+        elif isinstance(obj, dict):
+            json_values = []
+            json_keys = []
+            for k, v in obj.items():
+                json_keys.append(ast.Constant(maybe_str(k)))
+                json_values.append(astify_json_obj(v))
+            return ast.Dict(json_keys, json_values)
+        else:
+            raise Exception("Cannot astify {0:s}".format(str(obj)))
+
+    if data:
+        if is_json(request.headers.get("Content-Type", "")):
+            call.keywords.append(ast.keyword("json", astify_json_obj(data)))
+        else:
+            call.keywords.append(ast.keyword("data", ast.Constant(data)))
+
+    # Authorization
+    if method == "Basic":
+        token = maybe_str(token)
+        call.keywords.append(
+            ast.keyword(
+                "auth", ast.Tuple(tuple(map(ast.Constant, token.split(":"))), None)
+            )
+        )
+
+    return unparse(tree).strip()

sphinxcontrib/httpexample/directives.py

@@ -0,0 +1,239 @@
+# -*- coding: utf-8 -*-
+from docutils import nodes
+from docutils.parsers.rst import directives
+from docutils.statemachine import StringList
+from sphinx.directives.code import CodeBlock
+from sphinxcontrib.httpexample import builders
+from sphinxcontrib.httpexample import parsers
+from sphinxcontrib.httpexample import utils
+import os
+import re
+
+
+AVAILABLE_BUILDERS = {
+    "curl": (builders.build_curl_command, "shell"),
+    "wget": (builders.build_wget_command, "shell"),
+    "httpie": (builders.build_httpie_command, "shell"),
+    "python-requests": (builders.build_requests_command, "python"),
+    "requests": (builders.build_requests_command, "python"),
+}
+
+AVAILABLE_FIELDS = ["query"]
+
+
+def choose_builders(arguments):
+    return [
+        directives.choice(argument, AVAILABLE_BUILDERS)
+        for argument in (arguments or [])
+    ]
+
+
+def register_builder(name, builder, language, label):
+    AVAILABLE_BUILDERS[name] = (builder, language, label)
+
+
+class HTTPExample(CodeBlock):
+
+    required_arguments = 0
+    optional_arguments = len(AVAILABLE_BUILDERS)
+
+    option_spec = utils.merge_dicts(
+        CodeBlock.option_spec,
+        {
+            "request": directives.unchanged,
+            "response": directives.unchanged,
+        },
+    )
+
+    @staticmethod
+    def process_content(content):
+        if content:
+            raw = ("\r\n".join(content)).encode("utf-8")
+            request = parsers.parse_request(raw)
+            params, _ = request.extract_fields("query")
+            params = [(p[1], p[2]) for p in params]
+            new_path = utils.add_url_params(request.path, params)
+            content[0] = " ".join([request.command, new_path, request.request_version])
+
+        # split the request and optional response in the content.
+        # The separator is two empty lines followed by a line starting with
+        # 'HTTP/' or 'HTTP '
+        request_content = StringList()
+        request_content_no_fields = StringList()
+        response_content = None
+        emptylines_count = 0
+        in_response = False
+        is_field = r":({}) (.+): (.+)".format("|".join(AVAILABLE_FIELDS))
+        for i, line in enumerate(content):
+            source = content.source(i)
+            if in_response:
+                response_content.append(line, source)
+            else:
+                if emptylines_count >= 2 and (
+                    line.startswith("HTTP/") or line.startswith("HTTP ")
+                ):
+                    in_response = True
+                    response_content = StringList()
+                    response_content.append(line, source)
+                elif line == "":
+                    emptylines_count += 1
+                else:
+                    request_content.extend(StringList([""] * emptylines_count, source))
+                    request_content.append(line, source)
+
+                    if not re.match(is_field, line):
+                        request_content_no_fields.extend(
+                            StringList([""] * emptylines_count, source)
+                        )
+                        request_content_no_fields.append(line, source)
+
+                    emptylines_count = 0
+
+        return (request_content, request_content_no_fields, response_content)
+
+    def run(self):
+        if self.content:
+            processed = self.process_content(StringList(self.content))
+            have_request = bool(processed[1])
+            have_response = bool(processed[2])
+        else:
+            have_request = "request" in self.options
+            have_response = "response" in self.options
+
+        # Wrap and render main directive as 'http-example-http'
+        klass = "http-example-http"
+        container = nodes.container("", classes=[klass])
+        container.append(nodes.caption("", "http"))
+        block = HTTPExampleBlock(
+            "http:example-block",
+            ["http"],
+            self.options,
+            self.content,
+            self.lineno,
+            self.content_offset,
+            self.block_text,
+            self.state,
+            self.state_machine,
+        )
+        container.extend(block.run())
+
+        # Init result node list
+        result = [container]
+
+        # Append builder responses
+        if have_request:
+            for argument in self.arguments:
+                builder_entry = AVAILABLE_BUILDERS.get(argument)
+                if builder_entry is not None and len(builder_entry) == 3:
+                    label = builder_entry[2]
+                else:
+                    label = argument
+                options = self.options.copy()
+                options.pop("name", None)
+                options.pop("caption", None)
+
+                block = HTTPExampleBlock(
+                    "http:example-block",
+                    [argument],
+                    options,
+                    self.content,
+                    self.lineno,
+                    self.content_offset,
+                    self.block_text,
+                    self.state,
+                    self.state_machine,
+                )
+
+                # Wrap and render main directive as 'http-example-{name}'
+                klass = "http-example-{}".format(argument)
+                container = nodes.container("", classes=[klass])
+                container.append(nodes.caption("", label))
+                container.extend(block.run())
+
+                # Append to result nodes
+                result.append(container)
+
+        # Append optional response
+        if have_response:
+            options = self.options.copy()
+            options.pop("name", None)
+            options.pop("caption", None)
+
+            block = HTTPExampleBlock(
+                "http:example-block",
+                ["response"],
+                options,
+                self.content,
+                self.lineno,
+                self.content_offset,
+                self.block_text,
+                self.state,
+                self.state_machine,
+            )
+
+            # Wrap and render main directive as 'http-example-response'
+            klass = "http-example-response"
+            container = nodes.container("", classes=[klass])
+            container.append(nodes.caption("", "response"))
+            container.extend(block.run())
+
+            # Append to result nodes
+            result.append(container)
+
+        # Final wrap
+        container_node = nodes.container("", classes=["http-example"])
+        container_node.extend(result)
+
+        return [container_node]
+
+
+class HTTPExampleBlock(CodeBlock):
+    required_arguments = 1
+
+    option_spec = utils.merge_dicts(
+        CodeBlock.option_spec,
+        {
+            "request": directives.unchanged,
+            "response": directives.unchanged,
+        },
+    )
+
+    def read_http_file(self, path):
+        cwd = os.path.dirname(self.state.document.current_source)
+        request = utils.resolve_path(path, cwd)
+        with open(request) as fp:
+            return StringList(list(map(str.rstrip, fp.readlines())), request)
+
+    def run(self):
+        if self.arguments == ["http"]:
+            if "request" in self.options:
+                self.content = self.read_http_file(self.options["request"])
+            else:
+                self.content = HTTPExample.process_content(self.content)[1]
+        elif self.arguments == ["response"]:
+            if "response" in self.options:
+                self.content = self.read_http_file(self.options["response"])
+            else:
+                self.content = HTTPExample.process_content(self.content)[2]
+            self.arguments = ["http-response"]
+        else:
+            if "request" in self.options:
+                request_content_no_fields = self.read_http_file(self.options["request"])
+            else:
+                request_content_no_fields = HTTPExample.process_content(self.content)[1]
+
+            raw = ("\r\n".join(request_content_no_fields)).encode("utf-8")
+
+            config = self.env.config
+            request = parsers.parse_request(raw, config.httpexample_scheme)
+            name = choose_builders(self.arguments)[0]
+            try:
+                builder_, language, _ = AVAILABLE_BUILDERS[name]
+            except ValueError:
+                builder_, language = AVAILABLE_BUILDERS[name]
+            self.arguments = [language]
+
+            command = builder_(request)
+            self.content = StringList([command], request_content_no_fields.source(0))
+
+        return super(HTTPExampleBlock, self).run()

sphinxcontrib/httpexample/lexers.py

@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""A custom Pygments lexer for HTTP responses."""
+
+from pygments.lexer import bygroups
+from pygments.lexer import Lexer
+from pygments.lexer import RegexLexer
+from pygments.lexers import get_lexer_for_mimetype
+from pygments.lexers import TextLexer
+from pygments.token import Name
+from pygments.token import String
+from pygments.token import Text
+from pygments.token import Token
+import re
+
+
+class HTTPHeaderLexer(RegexLexer):
+    """A simple lexer for HTTP headers."""
+
+    name = "HTTPHeader"
+    tokens = {
+        "root": [
+            (
+                r"^([a-zA-Z][a-zA-Z0-9-]*)(:\s*)(.*)",
+                bygroups(Name.Attribute, Text, String),
+            ),
+            (r".+", Text),
+        ]
+    }
+
+
+class HTTPResponseLexer(Lexer):
+    """
+    A custom Pygments lexer that delegates the body parsing to another lexer
+    based on the Content-Type header.
+    """
+
+    name = "HTTPResponse"
+    aliases = ["http-response"]
+
+    def get_tokens_unprocessed(self, text, **options):
+        # 1. Split headers and body
+        parts = re.split(r"(\r?\n\r?\n)", text, maxsplit=1)
+        header_part = parts[0]
+
+        # 2. Handle the Status Line to avoid Token.Error
+        # Supports: "HTTP 200 OK", "HTTP/1.1 200 OK", "HTTP/2 200"
+        lines = header_part.splitlines(keepends=True)
+        if lines:
+            status_line = lines[0]
+            if status_line.startswith("HTTP"):
+                yield 0, Token.Keyword.Reserved, status_line.rstrip()
+                if status_line.endswith("\n") or status_line.endswith("\r\n"):
+                    yield len(status_line.rstrip()), Token.Text, status_line[
+                        len(status_line.rstrip()) :
+                    ]
+                header_remainder = "".join(lines[1:])
+            else:
+                header_remainder = header_part
+        else:
+            header_remainder = ""
+
+        # 3. Parse remaining headers
+        h_lexer = HTTPHeaderLexer()
+        current_offset = len(lines[0]) if lines and lines[0].startswith("HTTP") else 0
+        for line in header_remainder.splitlines(keepends=True):
+            for pos, token, value in h_lexer.get_tokens_unprocessed(line):
+                yield current_offset + pos, token, value
+            current_offset += len(line)
+
+        if len(parts) < 3:
+            return
+
+        # 4. Yield the separator
+        separator = parts[1]
+        body_part = parts[2]
+        yield len(header_part), Token.Text, separator
+
+        # 5. Delegate body parsing
+        ct_match = re.search(
+            r"^Content-Type:\s*([^;\n\r\s]+)", header_part, re.I | re.M
+        )
+        mime = ct_match.group(1).strip() if ct_match else "text/plain"
+        try:
+            body_lexer = get_lexer_for_mimetype(mime)
+        except Exception:
+            body_lexer = TextLexer()
+
+        body_offset = len(header_part) + len(separator)
+        for pos, token, value in body_lexer.get_tokens_unprocessed(
+            body_part, **options
+        ):
+            yield body_offset + pos, token, value

sphinxcontrib/httpexample/parsers.py

@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+from io import BytesIO
+from sphinxcontrib.httpexample.utils import add_url_params
+from sphinxcontrib.httpexample.utils import capitalize_keys
+from sphinxcontrib.httpexample.utils import is_json
+from sphinxcontrib.httpexample.utils import ordered
+import base64
+import json
+import re
+
+
+try:
+    from http.server import BaseHTTPRequestHandler
+except ImportError:
+    from BaseHTTPServer import BaseHTTPRequestHandler
+
+
+AVAILABLE_FIELDS = ["query"]
+
+
+class HTTPRequest(BaseHTTPRequestHandler):
+    # http://stackoverflow.com/a/5955949
+
+    scheme = "http"
+
+    # noinspection PyMissingConstructor
+    def __init__(self, request_bytes, scheme):
+        assert isinstance(request_bytes, bytes)
+
+        self.scheme = scheme
+        self.rfile = BytesIO(request_bytes)
+        self.raw_requestline = self.rfile.readline()
+        self.error_code = self.error_message = None
+        self.parse_request()
+
+        if self.error_message:
+            raise Exception(self.error_message)
+
+        # Replace headers with simple dict to coup differences in Py2 and Py3
+        self.headers = capitalize_keys(dict(getattr(self, "headers", {})))
+
+    def send_error(self, code, message=None, explain=None):
+        self.error_code = code
+        self.error_message = message
+
+    def extract_fields(self, field=None, available_fields=None):
+        if available_fields is None:
+            available_fields = AVAILABLE_FIELDS
+
+        if (field is not None) and field not in available_fields:
+            msg = "Unexpected field '{}'. Expected one of {}."
+            msg = msg.format(field, ", ".join(available_fields))
+            raise ValueError(msg)
+
+        if field is None:
+            field = "|".join(available_fields)
+        is_field = r":({}) (.+): (.+)".format(field)
+
+        fields = []
+        remaining_request = []
+        cursor = self.rfile.tell()
+        for i, line in enumerate(self.rfile.readlines()):
+            line = line.decode("utf-8")
+            try:
+                field, key, val = re.match(is_field, line).groups()
+            except AttributeError:
+                remaining_request.append(line)
+                continue
+            fields.append((field.strip(), key.strip(), val.strip()))
+
+        remaining_request = BytesIO(
+            "\n".join(remaining_request).encode("utf-8").strip()
+        )
+        remaining_request.seek(0)
+        self.rfile.seek(cursor)
+
+        return (fields, remaining_request)
+
+    def auth(self):
+        try:
+            method, token = self.headers.get("Authorization").split()
+        except (AttributeError, KeyError, ValueError):
+            return None, None
+        if not isinstance(token, bytes):
+            token = token.encode("utf-8")
+        if method == "Basic":
+            return method, base64.b64decode(token).decode("utf-8")
+        else:
+            return method, token
+
+    def url(self):
+        base_url = "{}://{}{}".format(
+            self.scheme, self.headers.get("Host", "nohost"), self.path
+        )
+
+        params, _ = self.extract_fields("query")
+        params = [(p[1], p[2]) for p in params]
+
+        if params:
+            new_url = add_url_params(base_url, params)
+        else:
+            new_url = base_url
+
+        return new_url
+
+    def data(self):
+        _, payload_bytes = self.extract_fields(None)
+        payload_bytes = payload_bytes.read()
+        if payload_bytes:
+            if is_json(self.headers.get("Content-Type", "")):
+                assert isinstance(payload_bytes, bytes)
+                payload_str = payload_bytes.decode("utf-8")
+                return ordered(json.loads(payload_str))
+            else:
+                return payload_bytes
+
+
+def parse_request(request_bytes, scheme="http"):
+    return HTTPRequest(request_bytes, scheme)

sphinxcontrib/httpexample/static/sphinxcontrib-httpexample.css

@@ -0,0 +1,30 @@
+.http-example .caption,
+.section ul .http-example .caption {
+    display: inline-block;
+    cursor: pointer;
+    padding: 0.5em 1em;
+    margin: 0;
+}
+.http-example .caption.selected {
+    font-weight: bold;
+    background-color: transparent;
+    border: 1px solid #e1e4e5;
+    border-bottom: 1px solid white;
+}
+.http-example div[class^='highlight'] {
+    margin-top: -1px;
+}
+.http-example div[class^='highlight'] pre {
+    white-space: break-spaces;
+}
+.http-example div.highlight-bash pre {
+    white-space: pre-wrap;
+}
+.http-example-http div[class^='highlight'] pre,
+.http-example-httpie div[class^='highlight'] pre,
+.http-example-plone-client div[class^='highlight'] pre,
+.http-example-python-requests div[class^='highlight'] pre,
+.http-example-wget div[class^='highlight'] pre,
+.http-example-response div[class^='highlight'] pre {
+    white-space: pre;
+}

sphinxcontrib/httpexample/static/sphinxcontrib-httpexample.js

@@ -0,0 +1,99 @@
+document.addEventListener("DOMContentLoaded", function() {
+  // Select all elements with the class 'http-example container'
+  var containers = document.querySelectorAll('.http-example.container');
+  containers.forEach(function(container) {
+
+    // Get all child elements
+    var blocks = Array.from(container.children);
+
+    // Find caption elements or derive them from elements with the 'caption-text' class
+    var captions = container.querySelectorAll('.caption');
+    if (captions.length === 0) {
+      captions = container.querySelectorAll('.caption-text');
+      captions.forEach(function(caption) {
+        caption.classList.add('caption');
+      });
+    } else {
+      captions = Array.from(captions);
+    }
+
+    // Process each caption element
+    captions.forEach(function(caption, index) {
+      var orphan, block = !!caption.parentElement.id ? caption.parentElement : caption.parentElement.parentElement;
+      block.setAttribute('role', 'tabpanel');
+      block.setAttribute('tabindex', '0');
+      block.setAttribute('aria-labelledby', block.id + '-label');
+
+      caption.id = block.id + '-label';
+      caption.setAttribute('role', 'tab');
+      caption.setAttribute('tabindex', '0');
+      caption.setAttribute('aria-label', caption.textContent.trim());
+      caption.setAttribute('aria-controls', block.id);
+
+      // Click event for captions
+      caption.addEventListener('click', function() {
+        captions.forEach(function(otherCaption) {
+          if (caption === otherCaption) {
+            // Select the clicked caption
+            caption.setAttribute('aria-selected', 'true');
+            caption.classList.add('selected');
+            otherCaption.setAttribute('tabindex', '0');
+          } else {
+          // Deselect other captions
+            otherCaption.setAttribute('aria-selected', 'false');
+            otherCaption.setAttribute('tabindex', '-1');
+            otherCaption.classList.remove('selected');
+          }
+        });
+
+        // Hide other blocks and show the selected one
+        blocks.forEach(function(otherBlock) {
+          if (otherBlock !== block) {
+            otherBlock.style.display = 'none';
+            otherBlock.setAttribute('hidden', 'hidden');
+          }
+        });
+        block.style.display = '';
+        block.removeAttribute('hidden');
+      });
+
+      // Keydown event for accessibility
+      caption.addEventListener('keydown', function(event) {
+        if (event.code === 'Space' || event.code === 'Enter') {
+          caption.click();
+        } else if (event.code === 'ArrowRight') {
+          // Move focus to the next tab
+          var nextIndex = (index + 1) % captions.length;
+          captions[nextIndex].focus();
+          captions[nextIndex].click();
+        } else if (event.code === 'ArrowLeft') {
+          // Move focus to the previous tab
+          var prevIndex = (index - 1 + captions.length) % captions.length;
+          captions[prevIndex].focus();
+          captions[prevIndex].click();
+        }
+      });
+
+      if (caption.classList.contains("caption-text")) {
+        orphan = caption.parentElement;
+        container.appendChild(caption);
+        orphan.remove();
+      } else {
+        container.appendChild(caption);
+      }
+    });
+
+    // Set ARIA role for the container
+    container.setAttribute('role', 'tablist');
+
+    // Append blocks back to the container
+    blocks.forEach(function(block) {
+      container.appendChild(block);
+    });
+
+    // Automatically click the first caption to set the initial state
+    if (captions.length > 0) {
+      captions[0].click();
+    }
+  });
+});

sphinxcontrib/httpexample/utils.py

@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+from collections import OrderedDict
+from importlib import resources
+from urllib.parse import parse_qsl
+from urllib.parse import ParseResult
+from urllib.parse import unquote
+from urllib.parse import urlencode
+from urllib.parse import urlparse
+import os
+
+
+def merge_dicts(a, b):
+    c = a.copy()
+    c.update(b)
+    return c
+
+
+def resolve_path(spec, cwd=""):
+    if os.path.isfile(os.path.normpath(os.path.join(cwd, spec))):
+        return os.path.normpath(os.path.join(cwd, spec))
+    elif spec.count(":"):
+        package, resource = spec.split(":", 1)
+        resource_path = resources.files(package) / resource
+        if resource_path.exists():
+            return str(resource_path)
+    else:
+        return spec
+
+
+def maybe_str(v):
+    """Convert any strings to local 'str' instances"""
+    if isinstance(v, str) and isinstance(v, bytes):
+        return v  # Python 2 encoded
+    elif str(type(v)) == "<type 'unicode'>":
+        return v.encode("utf-8")  # Python 2 unicode
+    elif isinstance(v, bytes):
+        return v.decode("utf-8")  # Python 3 encoded
+    elif isinstance(v, str):
+        return v  # Python 3 unicode
+    else:
+        return v  # not a string
+
+
+def ordered(dict_):
+    if isinstance(dict_, dict):
+        # http://stackoverflow.com/a/22721724
+        results = OrderedDict()
+        for k, v in sorted(dict_.items()):
+            results[k] = ordered(v)
+    else:
+        results = dict_
+    return results
+
+
+def capitalize(s):
+    return "-".join(map(str.capitalize, s.split("-")))
+
+
+def capitalize_keys(d):
+    return dict([(capitalize(k), v) for k, v in d.items()])
+
+
+def is_json(content_type):
+    """Checks if the given content type should be treated as JSON.
+
+    The primary use cases to be recognized as JSON are
+
+    - `application/json` mimetype
+    - `+json` structured syntax suffix
+    """
+    parts = {part.strip() for part in content_type.lower().strip().split(";")}
+    if "application/json" in parts:
+        return True
+
+    for p in parts:
+        if p.endswith("+json"):
+            return True
+
+    return False
+
+
+def add_url_params(url, params):
+    """Add GET query parameters to provided URL.
+
+    https://stackoverflow.com/a/25580545/1262843
+
+    Args:
+        url (str): target URL
+        params (list of tuples): query parameters to be added
+
+    Returns:
+        new_url (str): updated URL
+    """
+    url = unquote(url)
+    parsed_url = urlparse(url)
+    new_params = parse_qsl(parsed_url.query) + params
+    new_params_encoded = urlencode(new_params, doseq=True)
+    new_url = ParseResult(
+        parsed_url.scheme,
+        parsed_url.netloc,
+        parsed_url.path,
+        parsed_url.params,
+        new_params_encoded,
+        parsed_url.fragment,
+    ).geturl()
+
+    return new_url

sphinxcontrib_httpexample-2.0.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: sphinxcontrib-httpexample
+Version: 2.0
+Summary: Adds example directive for sphinx-contrib httpdomain
+Project-URL: Repository, https://github.com/collective/sphinxcontrib-httpexample
+Author-email: Asko Soukka <asko.soukka@iki.fi>
+License: GPL-2.0-only
+Keywords: documentation,extension,http,rest,sphinx
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: docutils
+Requires-Dist: importlib-metadata
+Requires-Dist: importlib-resources
+Requires-Dist: sphinx
+Requires-Dist: sphinxcontrib-httpdomain
+Provides-Extra: sphinx747
+Requires-Dist: sphinx==7.4.7; (python_version >= '3.10') and extra == 'sphinx747'
+Provides-Extra: sphinx802
+Requires-Dist: sphinx==8.0.2; (python_version >= '3.10') and extra == 'sphinx802'
+Provides-Extra: sphinx813
+Requires-Dist: babel; extra == 'sphinx813'
+Requires-Dist: sphinx==8.1.3; (python_version >= '3.10') and extra == 'sphinx813'
+Provides-Extra: sphinx823
+Requires-Dist: sphinx==8.2.3; (python_version >= '3.11') and extra == 'sphinx823'
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# sphinxcontrib-httpexample
+
+<img alt="GitHub Actions" src="https://github.com/collective/sphinxcontrib-httpexample/actions/workflows/build.yml/badge.svg?branch=master" href="https://github.com/collective/sphinxcontrib-httpexample/actions">
+<img alt="Coverage" src="https://coveralls.io/repos/github/collective/sphinxcontrib-httpexample/badge.svg?branch=master" href="https://coveralls.io/github/collective/sphinxcontrib-httpexample?branch=master">
+<img alt="PyPI package" src="https://badge.fury.io/py/sphinxcontrib-httpexample.svg" href="https://pypi.org/project/sphinxcontrib-httpexample/">
+<img alt="Documentation" src="https://readthedocs.org/projects/sphinxcontrib-httpexample/badge/?version=latest" href="https://sphinxcontrib-httpexample.readthedocs.io/en/latest/">
+
+sphinxcontrib-httpexample is a Sphinx domain extension for describing RESTful HTTP APIs in detail.
+It enhances [`sphinxcontrib-httpdomain`](https://github.com/sphinx-contrib/httpdomain) with a simple call example directive.
+The directive provided by this extension generates RESTful HTTP API call examples for different HTTP clients from a single HTTP request example.
+
+The audience for this extension are developers and technical writers documenting their RESTful HTTP APIs.
+This extension was originally developed for documenting [`plone.restapi`](https://6.docs.plone.org/plone.restapi/docs/source/index.html).
+
+
+## Features
+
+-   Directive for generating various RESTful HTTP API call examples from a single HTTP request.
+-   Supported HTTP clients:
+
+    -   [curl](https://curl.haxx.se/)
+    -   [wget](https://www.gnu.org/software/wget/)
+    -   [httpie](https://httpie.io/)
+    -   [requests](https://requests.readthedocs.io/en/stable/)
+
+-   Custom builders, such as the [`@plone/client`](https://www.npmjs.com/package/@plone/client) package, an agnostic library that provides easy access to the Plone REST API from a client written in TypeScript.
+    See https://sphinxcontrib-httpexample.readthedocs.io/en/latest/custom.html for examples.
+
+
+## Examples
+
+This extension has been used in documentation for the following projects and probably other similar projects as well.
+
+-   https://6.docs.plone.org/plone.restapi/docs/source/index.html
+-   https://sphinxcontrib-httpexample.readthedocs.io/en/latest/
+-   https://guillotina.readthedocs.io/en/latest/
+
+
+## Documentation
+
+Full documentation for end users can be found in the `docs` folder.
+It's also available online at https://sphinxcontrib-httpexample.readthedocs.io/en/latest/.
+
+
+## Installation
+
+Add `sphinxcontrib-httpexample` and `sphincontrib-httpdomain` to your project requirements.
+
+Then configure your Sphinx configuration file `conf.py` with `sphinxcontrib.httpdomain` and `sphinxcontrib.httpexample` as follows.
+
+```python
+extensions = [
+    "sphinxcontrib.httpdomain",
+    "sphinxcontrib.httpexample",
+]
+```
+
+
+## Contribute
+
+To contribute to `sphinxcontrib-httpexample`, first set up your environment.
+
+
+### Set up development environment
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
+Carefully read the console output for further instruction.
+
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Initialize a Python virtual environment.
+
+```shell
+uv venv
+```
+
+Install `sphinxcontrib-httpexample`.
+
+```shell
+uv sync
+```
+
+
+### Build documentation
+
+Rebuild Sphinx documentation on changes, with live reload in the browser.
+
+```shell
+make livehtml
+```
+
+To stop the preview, type `CTRL-C`.
+
+
+### Run tests
+
+```shell
+make test
+```
+
+
+## License
+
+The project is licensed under the GPLv2.

sphinxcontrib_httpexample-2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+sphinxcontrib/httpexample/__init__.py,sha256=h7PxhqRDKIZkMrenlot9TKnhRc4jUd0sqGGm5fhx74g,1404
+sphinxcontrib/httpexample/builders.py,sha256=JJD9n4tA9qVBkLA20EZVbF08R3uu0Q1feWB8DWXFhcw,8088
+sphinxcontrib/httpexample/directives.py,sha256=Uy5rcnafU2j2Ynk-HHbS078HwzV7MhLyRtyWVQT7RrM,8434
+sphinxcontrib/httpexample/lexers.py,sha256=-OYFJiluVjB5JCunghvLr8yCexsJxwrxLrQLBa64DfM,3045
+sphinxcontrib/httpexample/parsers.py,sha256=mJkfAebpnpVvVsKxmd6Qs4Uk8jTrS2gBYLmWn-kgIUs,3788
+sphinxcontrib/httpexample/utils.py,sha256=sk4jMhr2OJ1ZAf35t7jFZ4kYdUh9B5VTyFXuSZ-6Vt0,2771
+sphinxcontrib/httpexample/static/sphinxcontrib-httpexample.css,sha256=_gughUpi98ryQU_Nq3IKDInDLdb20fL_xVvRmDXhaZE,858
+sphinxcontrib/httpexample/static/sphinxcontrib-httpexample.js,sha256=7pz_9jiaS_LKsiDKrb5nsJbdBa4lf3VALyifUhpgzw0,3594
+sphinxcontrib_httpexample-2.0.dist-info/METADATA,sha256=V58sp7gjTcAz8yf_fjg2Ex0F6jizgyfWdbwukAdWd24,5071
+sphinxcontrib_httpexample-2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+sphinxcontrib_httpexample-2.0.dist-info/RECORD,,

sphinxcontrib_httpexample-2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any