From f9a2e172b00930c864d2b7e073072cf4c00bbf33 Mon Sep 17 00:00:00 2001 From: Delta456 Date: Mon, 17 Nov 2025 16:58:17 +0530 Subject: [PATCH 1/2] [py] use docstrings for function comments --- py/generate.py | 136 ++++++++++++++++++++++++------------------------- 1 file changed, 68 insertions(+), 68 deletions(-) diff --git a/py/generate.py b/py/generate.py index c746364a256ae..958108e2301a6 100644 --- a/py/generate.py +++ b/py/generate.py @@ -90,7 +90,7 @@ def parse_json_event(json: T_JSON_DICT) -> typing.Any: def indent(s, n): - ''' A shortcut for ``textwrap.indent`` that always uses spaces. ''' + """ A shortcut for ``textwrap.indent`` that always uses spaces. """ return tw_indent(s, n * ' ') @@ -98,13 +98,13 @@ def indent(s, n): def escape_backticks(docstr): - ''' + """ Escape backticks in a docstring by doubling them up. This is a little tricky because RST requires a non-letter character after the closing backticks, but some CDPs docs have things like "`AxNodeId`s". If we double the backticks in that string, then it won't be valid RST. The fix is to insert an apostrophe if an "s" trails the backticks. - ''' + """ def replace_one(match): if match.group(2) == 's': return f"``{match.group(1)}``'s" @@ -120,7 +120,7 @@ def replace_one(match): def inline_doc(description): - ''' Generate an inline doc, e.g. ``#: This type is a ...`` ''' + """ Generate an inline doc, e.g. ``#: This type is a ...`` """ if not description: return '' @@ -130,7 +130,7 @@ def inline_doc(description): def docstring(description): - ''' Generate a docstring from a description. ''' + """ Generate a docstring from a description. """ if not description: return '' @@ -139,7 +139,7 @@ def docstring(description): def is_builtin(name): - ''' Return True if ``name`` would shadow a builtin. ''' + """ Return True if ``name`` would shadow a builtin. """ try: getattr(builtins, name) return True @@ -148,8 +148,8 @@ def is_builtin(name): def snake_case(name): - ''' Convert a camel case name to snake case. If the name would shadow a - Python builtin, then append an underscore. ''' + """ Convert a camel case name to snake case. If the name would shadow a + Python builtin, then append an underscore. """ name = inflection.underscore(name) if is_builtin(name): name += '_' @@ -157,10 +157,10 @@ def snake_case(name): def ref_to_python(ref): - ''' + """ Convert a CDP ``$ref`` to the name of a Python type. For a dotted ref, the part before the dot is snake cased. - ''' + """ if '.' in ref: domain, subtype = ref.split('.') ref = f'{snake_case(domain)}.{subtype}' @@ -168,7 +168,7 @@ def ref_to_python(ref): class CdpPrimitiveType(Enum): - ''' All of the CDP types that map directly to a Python type. ''' + """ All of the CDP types that map directly to a Python type. """ boolean = 'bool' integer = 'int' number = 'float' @@ -177,14 +177,14 @@ class CdpPrimitiveType(Enum): @classmethod def get_annotation(cls, cdp_type): - ''' Return a type annotation for the CDP type. ''' + """ Return a type annotation for the CDP type. """ if cdp_type == 'any': return 'typing.Any' return cls[cdp_type].value @classmethod def get_constructor(cls, cdp_type, val): - ''' Return the code to construct a value for a given CDP type. ''' + """ Return the code to construct a value for a given CDP type. """ if cdp_type == 'any': return val cons = cls[cdp_type].value @@ -193,19 +193,19 @@ def get_constructor(cls, cdp_type, val): @dataclass class CdpItems: - ''' Represents the type of a repeated item. ''' + """ Represents the type of a repeated item. """ type: str ref: str @classmethod def from_json(cls, type): - ''' Generate code to instantiate an item from a JSON object. ''' + """ Generate code to instantiate an item from a JSON object. """ return cls(type.get('type'), type.get('$ref')) @dataclass class CdpProperty: - ''' A property belonging to a non-primitive CDP type. ''' + """ A property belonging to a non-primitive CDP type. """ name: str description: str | None type: str | None @@ -218,12 +218,12 @@ class CdpProperty: @property def py_name(self)->str: - ''' Get this property's Python name. ''' + """ Get this property's Python name. """ return snake_case(self.name) @property def py_annotation(self): - ''' This property's Python type annotation. ''' + """ This property's Python type annotation. """ if self.items: if self.items.ref: py_ref = ref_to_python(self.items.ref) @@ -244,7 +244,7 @@ def py_annotation(self): @classmethod def from_json(cls, property): - ''' Instantiate a CDP property from a JSON object. ''' + """ Instantiate a CDP property from a JSON object. """ return cls( property['name'], property.get('description'), @@ -258,7 +258,7 @@ def from_json(cls, property): ) def generate_decl(self): - ''' Generate the code that declares this property. ''' + """ Generate the code that declares this property. """ code = inline_doc(self.description) if code: code += '\n' @@ -268,8 +268,8 @@ def generate_decl(self): return code def generate_to_json(self, dict_, use_self=True): - ''' Generate the code that exports this property to the specified JSON - dict. ''' + """ Generate the code that exports this property to the specified JSON + dict. """ self_ref = 'self.' if use_self else '' assign = f"{dict_}['{self.name}'] = " if self.items: @@ -291,8 +291,8 @@ def generate_to_json(self, dict_, use_self=True): return code def generate_from_json(self, dict_): - ''' Generate the code that creates an instance from a JSON dict named - ``dict_``. ''' + """ Generate the code that creates an instance from a JSON dict named + ``dict_``. """ if self.items: if self.items.ref: py_ref = ref_to_python(self.items.ref) @@ -315,7 +315,7 @@ def generate_from_json(self, dict_): @dataclass class CdpType: - ''' A top-level CDP type. ''' + """ A top-level CDP type. """ id: str description: str | None type: str @@ -325,7 +325,7 @@ class CdpType: @classmethod def from_json(cls, type_): - ''' Instantiate a CDP type from a JSON object. ''' + """ Instantiate a CDP type from a JSON object. """ return cls( type_['id'], type_.get('description'), @@ -336,7 +336,7 @@ def from_json(cls, type_): ) def generate_code(self): - ''' Generate Python code for this type. ''' + """ Generate Python code for this type. """ logger.debug('Generating type %s: %s', self.id, self.type) if self.enum: return self.generate_enum_code() @@ -345,7 +345,7 @@ def generate_code(self): return self.generate_primitive_code() def generate_primitive_code(self): - ''' Generate code for a primitive type. ''' + """ Generate code for a primitive type. """ if self.items: if self.items.ref: nested_type = ref_to_python(self.items.ref) @@ -382,13 +382,13 @@ def __repr__(self): return code def generate_enum_code(self): - ''' + """ Generate an "enum" type. Enums are handled by making a python class that contains only class members. Each class member is upper snaked case, e.g. ``MyTypeClass.MY_ENUM_VALUE`` and is assigned a string value from the CDP metadata. - ''' + """ def_to_json = dedent('''\ def to_json(self): return self.value''') @@ -412,11 +412,11 @@ def from_json(cls, json): return code def generate_class_code(self): - ''' + """ Generate a class type. Top-level types that are defined as a CDP ``object`` are turned into Python dataclasses. - ''' + """ # children = set() code = dedent(f'''\ @dataclass @@ -464,7 +464,7 @@ def from_json(cls, json): return code def get_refs(self): - ''' Return all refs for this type. ''' + """ Return all refs for this type. """ refs = set() if self.enum: # Enum types don't have refs. @@ -485,10 +485,10 @@ def get_refs(self): class CdpParameter(CdpProperty): - ''' A parameter to a CDP command. ''' + """ A parameter to a CDP command. """ def generate_code(self): - ''' Generate the code for a parameter in a function call. ''' + """ Generate the code for a parameter in a function call. """ if self.items: if self.items.ref: nested_type = ref_to_python(self.items.ref) @@ -510,7 +510,7 @@ def generate_code(self): return code def generate_decl(self): - ''' Generate the declaration for this parameter. ''' + """ Generate the declaration for this parameter. """ if self.description: code = inline_doc(self.description) code += '\n' @@ -520,7 +520,7 @@ def generate_decl(self): return code def generate_doc(self): - ''' Generate the docstring for this parameter. ''' + """ Generate the docstring for this parameter. """ doc = f':param {self.py_name}:' if self.experimental: @@ -535,18 +535,18 @@ def generate_doc(self): return doc def generate_from_json(self, dict_): - ''' + """ Generate the code to instantiate this parameter from a JSON dict. - ''' + """ code = super().generate_from_json(dict_) return f'{self.py_name}={code}' class CdpReturn(CdpProperty): - ''' A return value from a CDP command. ''' + """ A return value from a CDP command. """ @property def py_annotation(self): - ''' Return the Python type annotation for this return. ''' + """ Return the Python type annotation for this return. """ if self.items: if self.items.ref: py_ref = ref_to_python(self.items.ref) @@ -565,7 +565,7 @@ def py_annotation(self): return ann def generate_doc(self): - ''' Generate the docstring for this return. ''' + """ Generate the docstring for this return. """ if self.description: doc = self.description.replace('\n', ' ') if self.optional: @@ -575,13 +575,13 @@ def generate_doc(self): return doc def generate_return(self, dict_): - ''' Generate code for returning this value. ''' + """ Generate code for returning this value. """ return super().generate_from_json(dict_) @dataclass class CdpCommand: - ''' A CDP command. ''' + """ A CDP command. """ name: str description: str experimental: bool @@ -592,12 +592,12 @@ class CdpCommand: @property def py_name(self) -> str: - ''' Get a Python name for this command. ''' + """ Get a Python name for this command. """ return snake_case(self.name) @classmethod def from_json(cls, command, domain) -> 'CdpCommand': - ''' Instantiate a CDP command from a JSON object. ''' + """ Instantiate a CDP command from a JSON object. """ parameters = command.get('parameters', []) returns = command.get('returns', []) @@ -612,7 +612,7 @@ def from_json(cls, command, domain) -> 'CdpCommand': ) def generate_code(self): - ''' Generate code for a CDP command. ''' + """ Generate code for a CDP command. """ global current_version # Generate the function header if len(self.returns) == 0: @@ -699,7 +699,7 @@ def generate_code(self): return code def get_refs(self): - ''' Get all refs for this command. ''' + """ Get all refs for this command. """ refs = set() for type_ in itertools.chain(self.parameters, self.returns): if type_.items and type_.items.ref: @@ -711,7 +711,7 @@ def get_refs(self): @dataclass class CdpEvent: - ''' A CDP event object. ''' + """ A CDP event object. """ name: str description: str | None deprecated: bool @@ -721,12 +721,12 @@ class CdpEvent: @property def py_name(self): - ''' Return the Python class name for this event. ''' + """ Return the Python class name for this event. """ return inflection.camelize(self.name, uppercase_first_letter=True) @classmethod def from_json(cls, json: dict, domain: str): - ''' Create a new CDP event instance from a JSON dict. ''' + """ Create a new CDP event instance from a JSON dict. """ return cls( json['name'], json.get('description'), @@ -738,7 +738,7 @@ def from_json(cls, json: dict, domain: str): ) def generate_code(self): - ''' Generate code for a CDP event. ''' + """ Generate code for a CDP event. """ global current_version code = dedent(f'''\ @event_class('{self.domain}.{self.name}') @@ -773,7 +773,7 @@ def from_json(cls, json: T_JSON_DICT) -> {self.py_name}: return code def get_refs(self): - ''' Get all refs for this event. ''' + """ Get all refs for this event. """ refs = set() for param in self.parameters: if param.items and param.items.ref: @@ -785,7 +785,7 @@ def get_refs(self): @dataclass class CdpDomain: - ''' A CDP domain contains metadata, types, commands, and events. ''' + """ A CDP domain contains metadata, types, commands, and events. """ domain: str description: str | None experimental: bool @@ -796,12 +796,12 @@ class CdpDomain: @property def module(self) -> str: - ''' The name of the Python module for this CDP domain. ''' + """ The name of the Python module for this CDP domain. """ return snake_case(self.domain) @classmethod def from_json(cls, domain: dict): - ''' Instantiate a CDP domain from a JSON object. ''' + """ Instantiate a CDP domain from a JSON object. """ types = domain.get('types', []) commands = domain.get('commands', []) events = domain.get('events', []) @@ -819,7 +819,7 @@ def from_json(cls, domain: dict): ) def generate_code(self): - ''' Generate the Python module code for a given CDP domain. ''' + """ Generate the Python module code for a given CDP domain. """ exp = ' (experimental)' if self.experimental else '' code = MODULE_HEADER.format(self.domain, exp) import_code = self.generate_imports() @@ -838,14 +838,14 @@ def generate_code(self): return code def generate_imports(self): - ''' + """ Determine which modules this module depends on and emit the code to import those modules. Notice that CDP defines a ``dependencies`` field for each domain, but these dependencies are a subset of the modules that we actually need to import to make our Python code work correctly and type safe. So we ignore the CDP's declared dependencies and compute them ourselves. - ''' + """ refs = set() for type_ in self.types: refs |= type_.get_refs() @@ -866,9 +866,9 @@ def generate_imports(self): return code def generate_sphinx(self): - ''' + """ Generate a Sphinx document for this domain. - ''' + """ docs = self.domain + '\n' docs += '=' * len(self.domain) + '\n\n' if self.description: @@ -930,12 +930,12 @@ def generate_sphinx(self): def parse(json_path, output_path): - ''' + """ Parse JSON protocol description and return domain objects. :param Path json_path: path to a JSON CDP schema :param Path output_path: a directory path to create the modules in :returns: a list of CDP domain objects - ''' + """ global current_version with open(json_path, encoding="utf-8") as json_file: schema = json.load(json_file) @@ -949,12 +949,12 @@ def parse(json_path, output_path): def generate_init(init_path, domains): - ''' + """ Generate an ``__init__.py`` that exports the specified modules. :param Path init_path: a file path to create the init file in :param list[tuple] modules: a list of modules each represented as tuples of (name, list_of_exported_symbols) - ''' + """ with open(init_path, "w", encoding="utf-8") as init_file: init_file.write(INIT_HEADER) for domain in domains: @@ -963,9 +963,9 @@ def generate_init(init_path, domains): def generate_docs(docs_path, domains): - ''' + """ Generate Sphinx documents for each domain. - ''' + """ logger.info('Generating Sphinx documents') # Remove generated documents @@ -980,7 +980,7 @@ def generate_docs(docs_path, domains): def main(browser_protocol_path, js_protocol_path, output_path): - ''' Main entry point. ''' + """ Main entry point. """ output_path = Path(output_path).resolve() json_paths = [ browser_protocol_path, From 5eaf6028d2ac5b8ef46ea747ec229c9e6d2e17d9 Mon Sep 17 00:00:00 2001 From: Corey Goldberg <1113081+cgoldberg@users.noreply.github.com> Date: Mon, 17 Nov 2025 08:47:20 -0500 Subject: [PATCH 2/2] [py] Convert the rest of the single quotes --- py/generate.py | 614 ++++++++++++++++++++++++------------------------- 1 file changed, 306 insertions(+), 308 deletions(-) diff --git a/py/generate.py b/py/generate.py index 958108e2301a6..f1b35bd274883 100644 --- a/py/generate.py +++ b/py/generate.py @@ -42,19 +42,19 @@ import inflection # type: ignore -log_level = getattr(logging, os.environ.get('LOG_LEVEL', 'warning').upper()) +log_level = getattr(logging, os.environ.get("LOG_LEVEL", "warning").upper()) logging.basicConfig(level=log_level) -logger = logging.getLogger('generate') +logger = logging.getLogger("generate") -SHARED_HEADER = '''# DO NOT EDIT THIS FILE! +SHARED_HEADER = """# DO NOT EDIT THIS FILE! # # This file is generated from the CDP specification. If you need to make -# changes, edit the generator and regenerate all of the modules.''' +# changes, edit the generator and regenerate all of the modules.""" -INIT_HEADER = '''{} -'''.format(SHARED_HEADER) +INIT_HEADER = """{} +""".format(SHARED_HEADER) -MODULE_HEADER = '''{} +MODULE_HEADER = """{} # # CDP domain: {{}}{{}} from __future__ import annotations @@ -62,9 +62,9 @@ from dataclasses import dataclass import enum import typing -'''.format(SHARED_HEADER) +""".format(SHARED_HEADER) -current_version = '' +current_version = "" UTIL_PY = """ import typing @@ -90,11 +90,11 @@ def parse_json_event(json: T_JSON_DICT) -> typing.Any: def indent(s, n): - """ A shortcut for ``textwrap.indent`` that always uses spaces. """ - return tw_indent(s, n * ' ') + """A shortcut for ``textwrap.indent`` that always uses spaces.""" + return tw_indent(s, n * " ") -BACKTICK_RE = re.compile(r'`([^`]+)`(\w+)?') +BACKTICK_RE = re.compile(r"`([^`]+)`(\w+)?") def escape_backticks(docstr): @@ -105,41 +105,42 @@ def escape_backticks(docstr): If we double the backticks in that string, then it won't be valid RST. The fix is to insert an apostrophe if an "s" trails the backticks. """ + def replace_one(match): - if match.group(2) == 's': + if match.group(2) == "s": return f"``{match.group(1)}``'s" if match.group(2): # This case (some trailer other than "s") doesn't currently exist # in the CDP definitions, but it's here just to be safe. - return f'``{match.group(1)}`` {match.group(2)}' - return f'``{match.group(1)}``' + return f"``{match.group(1)}`` {match.group(2)}" + return f"``{match.group(1)}``" # Sometimes pipes are used where backticks should have been used. - docstr = docstr.replace('|', '`') + docstr = docstr.replace("|", "`") return BACKTICK_RE.sub(replace_one, docstr) def inline_doc(description): - """ Generate an inline doc, e.g. ``#: This type is a ...`` """ + """Generate an inline doc, e.g. ``#: This type is a ...``""" if not description: - return '' + return "" description = escape_backticks(description) - lines = [f'#: {l}' for l in description.split('\n')] - return '\n'.join(lines) + lines = [f"#: {l}" for l in description.split("\n")] + return "\n".join(lines) def docstring(description): - """ Generate a docstring from a description. """ + """Generate a docstring from a description.""" if not description: - return '' + return "" description = escape_backticks(description) return dedent("'''\n{}\n'''").format(description) def is_builtin(name): - """ Return True if ``name`` would shadow a builtin. """ + """Return True if ``name`` would shadow a builtin.""" try: getattr(builtins, name) return True @@ -148,11 +149,11 @@ def is_builtin(name): def snake_case(name): - """ Convert a camel case name to snake case. If the name would shadow a - Python builtin, then append an underscore. """ + """Convert a camel case name to snake case. If the name would shadow a + Python builtin, then append an underscore.""" name = inflection.underscore(name) if is_builtin(name): - name += '_' + name += "_" return name @@ -161,51 +162,54 @@ def ref_to_python(ref): Convert a CDP ``$ref`` to the name of a Python type. For a dotted ref, the part before the dot is snake cased. """ - if '.' in ref: - domain, subtype = ref.split('.') - ref = f'{snake_case(domain)}.{subtype}' + if "." in ref: + domain, subtype = ref.split(".") + ref = f"{snake_case(domain)}.{subtype}" return f"{ref}" class CdpPrimitiveType(Enum): - """ All of the CDP types that map directly to a Python type. """ - boolean = 'bool' - integer = 'int' - number = 'float' - object = 'dict' - string = 'str' + """All of the CDP types that map directly to a Python type.""" + + boolean = "bool" + integer = "int" + number = "float" + object = "dict" + string = "str" @classmethod def get_annotation(cls, cdp_type): - """ Return a type annotation for the CDP type. """ - if cdp_type == 'any': - return 'typing.Any' + """Return a type annotation for the CDP type.""" + if cdp_type == "any": + return "typing.Any" return cls[cdp_type].value @classmethod def get_constructor(cls, cdp_type, val): - """ Return the code to construct a value for a given CDP type. """ - if cdp_type == 'any': + """Return the code to construct a value for a given CDP type.""" + if cdp_type == "any": return val cons = cls[cdp_type].value - return f'{cons}({val})' + return f"{cons}({val})" @dataclass class CdpItems: - """ Represents the type of a repeated item. """ + """Represents the type of a repeated item.""" + type: str ref: str @classmethod def from_json(cls, type): - """ Generate code to instantiate an item from a JSON object. """ - return cls(type.get('type'), type.get('$ref')) + """Generate code to instantiate an item from a JSON object.""" + return cls(type.get("type"), type.get("$ref")) @dataclass class CdpProperty: - """ A property belonging to a non-primitive CDP type. """ + """A property belonging to a non-primitive CDP type.""" + name: str description: str | None type: str | None @@ -217,60 +221,58 @@ class CdpProperty: deprecated: bool @property - def py_name(self)->str: - """ Get this property's Python name. """ + def py_name(self) -> str: + """Get this property's Python name.""" return snake_case(self.name) @property def py_annotation(self): - """ This property's Python type annotation. """ + """This property's Python type annotation.""" if self.items: if self.items.ref: py_ref = ref_to_python(self.items.ref) ann = f"typing.List[{py_ref}]" else: - ann = 'typing.List[{}]'.format( - CdpPrimitiveType.get_annotation(self.items.type)) + ann = "typing.List[{}]".format(CdpPrimitiveType.get_annotation(self.items.type)) else: if self.ref: py_ref = ref_to_python(self.ref) ann = py_ref else: - ann = CdpPrimitiveType.get_annotation( - cast(str, self.type)) + ann = CdpPrimitiveType.get_annotation(cast(str, self.type)) if self.optional: - ann = f'typing.Optional[{ann}]' + ann = f"typing.Optional[{ann}]" return ann @classmethod def from_json(cls, property): - """ Instantiate a CDP property from a JSON object. """ + """Instantiate a CDP property from a JSON object.""" return cls( - property['name'], - property.get('description'), - property.get('type'), - property.get('$ref'), - property.get('enum'), - CdpItems.from_json(property['items']) if 'items' in property else None, - property.get('optional', False), - property.get('experimental', False), - property.get('deprecated', False), + property["name"], + property.get("description"), + property.get("type"), + property.get("$ref"), + property.get("enum"), + CdpItems.from_json(property["items"]) if "items" in property else None, + property.get("optional", False), + property.get("experimental", False), + property.get("deprecated", False), ) def generate_decl(self): - """ Generate the code that declares this property. """ + """Generate the code that declares this property.""" code = inline_doc(self.description) if code: - code += '\n' - code += f'{self.py_name}: {self.py_annotation}' + code += "\n" + code += f"{self.py_name}: {self.py_annotation}" if self.optional: - code += ' = None' + code += " = None" return code def generate_to_json(self, dict_, use_self=True): - """ Generate the code that exports this property to the specified JSON - dict. """ - self_ref = 'self.' if use_self else '' + """Generate the code that exports this property to the specified JSON + dict.""" + self_ref = "self." if use_self else "" assign = f"{dict_}['{self.name}'] = " if self.items: if self.items.ref: @@ -283,31 +285,30 @@ def generate_to_json(self, dict_, use_self=True): else: assign += f"{self_ref}{self.py_name}" if self.optional: - code = dedent(f'''\ + code = dedent(f"""\ if {self_ref}{self.py_name} is not None: - {assign}''') + {assign}""") else: code = assign return code def generate_from_json(self, dict_): - """ Generate the code that creates an instance from a JSON dict named - ``dict_``. """ + """Generate the code that creates an instance from a JSON dict named + ``dict_``.""" if self.items: if self.items.ref: py_ref = ref_to_python(self.items.ref) expr = f"[{py_ref}.from_json(i) for i in {dict_}['{self.name}']]" expr else: - cons = CdpPrimitiveType.get_constructor(self.items.type, 'i') + cons = CdpPrimitiveType.get_constructor(self.items.type, "i") expr = f"[{cons} for i in {dict_}['{self.name}']]" else: if self.ref: py_ref = ref_to_python(self.ref) expr = f"{py_ref}.from_json({dict_}['{self.name}'])" else: - expr = CdpPrimitiveType.get_constructor(self.type, - f"{dict_}['{self.name}']") + expr = CdpPrimitiveType.get_constructor(self.type, f"{dict_}['{self.name}']") if self.optional: expr = f"{expr} if '{self.name}' in {dict_} else None" return expr @@ -315,7 +316,8 @@ def generate_from_json(self, dict_): @dataclass class CdpType: - """ A top-level CDP type. """ + """A top-level CDP type.""" + id: str description: str | None type: str @@ -325,19 +327,19 @@ class CdpType: @classmethod def from_json(cls, type_): - """ Instantiate a CDP type from a JSON object. """ + """Instantiate a CDP type from a JSON object.""" return cls( - type_['id'], - type_.get('description'), - type_['type'], - CdpItems.from_json(type_['items']) if 'items' in type_ else None, - type_.get('enum'), - [CdpProperty.from_json(p) for p in type_.get('properties', [])], + type_["id"], + type_.get("description"), + type_["type"], + CdpItems.from_json(type_["items"]) if "items" in type_ else None, + type_.get("enum"), + [CdpProperty.from_json(p) for p in type_.get("properties", [])], ) def generate_code(self): - """ Generate Python code for this type. """ - logger.debug('Generating type %s: %s', self.id, self.type) + """Generate Python code for this type.""" + logger.debug("Generating type %s: %s", self.id, self.type) if self.enum: return self.generate_enum_code() if self.properties: @@ -345,39 +347,39 @@ def generate_code(self): return self.generate_primitive_code() def generate_primitive_code(self): - """ Generate code for a primitive type. """ + """Generate code for a primitive type.""" if self.items: if self.items.ref: nested_type = ref_to_python(self.items.ref) else: nested_type = CdpPrimitiveType.get_annotation(self.items.type) - py_type = f'typing.List[{nested_type}]' - superclass = 'list' + py_type = f"typing.List[{nested_type}]" + superclass = "list" else: # A primitive type cannot have a ref, so there is no branch here. py_type = CdpPrimitiveType.get_annotation(self.type) superclass = py_type - code = f'class {self.id}({superclass}):\n' + code = f"class {self.id}({superclass}):\n" doc = docstring(self.description) if doc: - code += indent(doc, 4) + '\n' + code += indent(doc, 4) + "\n" - def_to_json = dedent(f'''\ + def_to_json = dedent(f"""\ def to_json(self) -> {py_type}: - return self''') + return self""") code += indent(def_to_json, 4) - def_from_json = dedent(f'''\ + def_from_json = dedent(f"""\ @classmethod def from_json(cls, json: {py_type}) -> {self.id}: - return cls(json)''') - code += '\n\n' + indent(def_from_json, 4) + return cls(json)""") + code += "\n\n" + indent(def_from_json, 4) - def_repr = dedent(f'''\ + def_repr = dedent(f"""\ def __repr__(self): - return '{self.id}({{}})'.format(super().__repr__())''') - code += '\n\n' + indent(def_repr, 4) + return '{self.id}({{}})'.format(super().__repr__())""") + code += "\n\n" + indent(def_repr, 4) return code @@ -389,25 +391,25 @@ def generate_enum_code(self): ``MyTypeClass.MY_ENUM_VALUE`` and is assigned a string value from the CDP metadata. """ - def_to_json = dedent('''\ + def_to_json = dedent("""\ def to_json(self): - return self.value''') + return self.value""") - def_from_json = dedent('''\ + def_from_json = dedent("""\ @classmethod def from_json(cls, json): - return cls(json)''') + return cls(json)""") - code = f'class {self.id}(enum.Enum):\n' + code = f"class {self.id}(enum.Enum):\n" doc = docstring(self.description) if doc: - code += indent(doc, 4) + '\n' + code += indent(doc, 4) + "\n" for enum_member in self.enum: snake_name = snake_case(enum_member).upper() enum_code = f'{snake_name} = "{enum_member}"\n' code += indent(enum_code, 4) - code += '\n' + indent(def_to_json, 4) - code += '\n\n' + indent(def_from_json, 4) + code += "\n" + indent(def_to_json, 4) + code += "\n\n" + indent(def_from_json, 4) return code @@ -418,53 +420,53 @@ def generate_class_code(self): dataclasses. """ # children = set() - code = dedent(f'''\ + code = dedent(f"""\ @dataclass - class {self.id}:\n''') + class {self.id}:\n""") doc = docstring(self.description) if doc: - code += indent(doc, 4) + '\n' + code += indent(doc, 4) + "\n" # Emit property declarations. These are sorted so that optional # properties come after required properties, which is required to make # the dataclass constructor work. props = list(self.properties) - props.sort(key=operator.attrgetter('optional')) - code += '\n\n'.join(indent(p.generate_decl(), 4) for p in props) - code += '\n\n' + props.sort(key=operator.attrgetter("optional")) + code += "\n\n".join(indent(p.generate_decl(), 4) for p in props) + code += "\n\n" # Emit to_json() method. The properties are sorted in the same order as # above for readability. - def_to_json = dedent('''\ + def_to_json = dedent("""\ def to_json(self): json = dict() - ''') - assigns = (p.generate_to_json(dict_='json') for p in props) - def_to_json += indent('\n'.join(assigns), 4) - def_to_json += '\n' - def_to_json += indent('return json', 4) - code += indent(def_to_json, 4) + '\n\n' + """) + assigns = (p.generate_to_json(dict_="json") for p in props) + def_to_json += indent("\n".join(assigns), 4) + def_to_json += "\n" + def_to_json += indent("return json", 4) + code += indent(def_to_json, 4) + "\n\n" # Emit from_json() method. The properties are sorted in the same order # as above for readability. - def_from_json = dedent('''\ + def_from_json = dedent("""\ @classmethod def from_json(cls, json): return cls( - ''') + """) from_jsons = [] for p in props: - from_json = p.generate_from_json(dict_='json') - from_jsons.append(f'{p.py_name}={from_json},') - def_from_json += indent('\n'.join(from_jsons), 8) - def_from_json += '\n' - def_from_json += indent(')', 4) + from_json = p.generate_from_json(dict_="json") + from_jsons.append(f"{p.py_name}={from_json},") + def_from_json += indent("\n".join(from_jsons), 8) + def_from_json += "\n" + def_from_json += indent(")", 4) code += indent(def_from_json, 4) return code def get_refs(self): - """ Return all refs for this type. """ + """Return all refs for this type.""" refs = set() if self.enum: # Enum types don't have refs. @@ -485,53 +487,52 @@ def get_refs(self): class CdpParameter(CdpProperty): - """ A parameter to a CDP command. """ + """A parameter to a CDP command.""" def generate_code(self): - """ Generate the code for a parameter in a function call. """ + """Generate the code for a parameter in a function call.""" if self.items: if self.items.ref: nested_type = ref_to_python(self.items.ref) py_type = f"typing.List[{nested_type}]" else: nested_type = CdpPrimitiveType.get_annotation(self.items.type) - py_type = f'typing.List[{nested_type}]' + py_type = f"typing.List[{nested_type}]" else: if self.ref: py_type = f"{ref_to_python(self.ref)}" else: - py_type = CdpPrimitiveType.get_annotation( - cast(str, self.type)) + py_type = CdpPrimitiveType.get_annotation(cast(str, self.type)) if self.optional: - py_type = f'typing.Optional[{py_type}]' + py_type = f"typing.Optional[{py_type}]" code = f"{self.py_name}: {py_type}" if self.optional: - code += ' = None' + code += " = None" return code def generate_decl(self): - """ Generate the declaration for this parameter. """ + """Generate the declaration for this parameter.""" if self.description: code = inline_doc(self.description) - code += '\n' + code += "\n" else: - code = '' - code += f'{self.py_name}: {self.py_annotation}' + code = "" + code += f"{self.py_name}: {self.py_annotation}" return code def generate_doc(self): - """ Generate the docstring for this parameter. """ - doc = f':param {self.py_name}:' + """Generate the docstring for this parameter.""" + doc = f":param {self.py_name}:" if self.experimental: - doc += ' **(EXPERIMENTAL)**' + doc += " **(EXPERIMENTAL)**" if self.optional: - doc += ' *(Optional)*' + doc += " *(Optional)*" if self.description: - desc = self.description.replace('`', '``').replace('\n', ' ') - doc += f' {desc}' + desc = self.description.replace("`", "``").replace("\n", " ") + doc += f" {desc}" return doc def generate_from_json(self, dict_): @@ -539,21 +540,22 @@ def generate_from_json(self, dict_): Generate the code to instantiate this parameter from a JSON dict. """ code = super().generate_from_json(dict_) - return f'{self.py_name}={code}' + return f"{self.py_name}={code}" class CdpReturn(CdpProperty): - """ A return value from a CDP command. """ + """A return value from a CDP command.""" + @property def py_annotation(self): - """ Return the Python type annotation for this return. """ + """Return the Python type annotation for this return.""" if self.items: if self.items.ref: py_ref = ref_to_python(self.items.ref) ann = f"typing.List[{py_ref}]" else: py_type = CdpPrimitiveType.get_annotation(self.items.type) - ann = f'typing.List[{py_type}]' + ann = f"typing.List[{py_type}]" else: if self.ref: py_ref = ref_to_python(self.ref) @@ -561,27 +563,28 @@ def py_annotation(self): else: ann = CdpPrimitiveType.get_annotation(self.type) if self.optional: - ann = f'typing.Optional[{ann}]' + ann = f"typing.Optional[{ann}]" return ann def generate_doc(self): - """ Generate the docstring for this return. """ + """Generate the docstring for this return.""" if self.description: - doc = self.description.replace('\n', ' ') + doc = self.description.replace("\n", " ") if self.optional: - doc = f'*(Optional)* {doc}' + doc = f"*(Optional)* {doc}" else: - doc = '' + doc = "" return doc def generate_return(self, dict_): - """ Generate code for returning this value. """ + """Generate code for returning this value.""" return super().generate_from_json(dict_) @dataclass class CdpCommand: - """ A CDP command. """ + """A CDP command.""" + name: str description: str experimental: bool @@ -592,42 +595,42 @@ class CdpCommand: @property def py_name(self) -> str: - """ Get a Python name for this command. """ + """Get a Python name for this command.""" return snake_case(self.name) @classmethod - def from_json(cls, command, domain) -> 'CdpCommand': - """ Instantiate a CDP command from a JSON object. """ - parameters = command.get('parameters', []) - returns = command.get('returns', []) + def from_json(cls, command, domain) -> "CdpCommand": + """Instantiate a CDP command from a JSON object.""" + parameters = command.get("parameters", []) + returns = command.get("returns", []) return cls( - command['name'], - command.get('description'), - command.get('experimental', False), - command.get('deprecated', False), + command["name"], + command.get("description"), + command.get("experimental", False), + command.get("deprecated", False), [cast(CdpParameter, CdpParameter.from_json(p)) for p in parameters], [cast(CdpReturn, CdpReturn.from_json(r)) for r in returns], domain, ) def generate_code(self): - """ Generate code for a CDP command. """ + """Generate code for a CDP command.""" global current_version # Generate the function header if len(self.returns) == 0: - ret_type = 'None' + ret_type = "None" elif len(self.returns) == 1: ret_type = self.returns[0].py_annotation else: - nested_types = ', '.join(r.py_annotation for r in self.returns) - ret_type = f'typing.Tuple[{nested_types}]' + nested_types = ", ".join(r.py_annotation for r in self.returns) + ret_type = f"typing.Tuple[{nested_types}]" ret_type = f"typing.Generator[T_JSON_DICT,T_JSON_DICT,{ret_type}]" - code = '' + code = "" - code += f'def {self.py_name}(' - ret = f') -> {ret_type}:\n' + code += f"def {self.py_name}(" + ret = f") -> {ret_type}:\n" if self.parameters: params = [p.generate_code() for p in self.parameters] optional = False @@ -636,70 +639,67 @@ def generate_code(self): if "= None" in para: optional = True if optional and "= None" not in para: - para += ' = None' + para += " = None" clean_params.append(para) - code += '\n' - code += indent( - ',\n'.join(clean_params), 8) - code += '\n' + code += "\n" + code += indent(",\n".join(clean_params), 8) + code += "\n" code += indent(ret, 4) else: code += ret # Generate the docstring - doc = '' + doc = "" if self.description: doc = self.description if self.experimental: - doc += '\n\n**EXPERIMENTAL**' + doc += "\n\n**EXPERIMENTAL**" if self.parameters and doc: - doc += '\n\n' + doc += "\n\n" elif not self.parameters and self.returns: - doc += '\n' - doc += '\n'.join(p.generate_doc() for p in self.parameters) + doc += "\n" + doc += "\n".join(p.generate_doc() for p in self.parameters) if len(self.returns) == 1: - doc += '\n' + doc += "\n" ret_doc = self.returns[0].generate_doc() - doc += f':returns: {ret_doc}' + doc += f":returns: {ret_doc}" elif len(self.returns) > 1: - doc += '\n' - doc += ':returns: A tuple with the following items:\n\n' - ret_docs = '\n'.join(f'{i}. **{r.name}** - {r.generate_doc()}' for i, r - in enumerate(self.returns)) + doc += "\n" + doc += ":returns: A tuple with the following items:\n\n" + ret_docs = "\n".join(f"{i}. **{r.name}** - {r.generate_doc()}" for i, r in enumerate(self.returns)) doc += indent(ret_docs, 4) if doc: code += indent(docstring(doc), 4) # Generate the function body if self.parameters: - code += '\n' - code += indent('params: T_JSON_DICT = dict()', 4) - code += '\n' - assigns = (p.generate_to_json(dict_='params', use_self=False) - for p in self.parameters) - code += indent('\n'.join(assigns), 4) - code += '\n' - code += indent('cmd_dict: T_JSON_DICT = {\n', 4) + code += "\n" + code += indent("params: T_JSON_DICT = dict()", 4) + code += "\n" + assigns = (p.generate_to_json(dict_="params", use_self=False) for p in self.parameters) + code += indent("\n".join(assigns), 4) + code += "\n" + code += indent("cmd_dict: T_JSON_DICT = {\n", 4) code += indent(f"'method': '{self.domain}.{self.name}',\n", 8) if self.parameters: code += indent("'params': params,\n", 8) - code += indent('}\n', 4) - code += indent('json = yield cmd_dict', 4) + code += indent("}\n", 4) + code += indent("json = yield cmd_dict", 4) if len(self.returns) == 0: pass elif len(self.returns) == 1: - ret = self.returns[0].generate_return(dict_='json') - code += indent(f'\nreturn {ret}', 4) + ret = self.returns[0].generate_return(dict_="json") + code += indent(f"\nreturn {ret}", 4) else: - ret = '\nreturn (\n' - expr = ',\n'.join(r.generate_return(dict_='json') for r in self.returns) + ret = "\nreturn (\n" + expr = ",\n".join(r.generate_return(dict_="json") for r in self.returns) ret += indent(expr, 4) - ret += '\n)' + ret += "\n)" code += indent(ret, 4) return code def get_refs(self): - """ Get all refs for this command. """ + """Get all refs for this command.""" refs = set() for type_ in itertools.chain(self.parameters, self.returns): if type_.items and type_.items.ref: @@ -711,7 +711,8 @@ def get_refs(self): @dataclass class CdpEvent: - """ A CDP event object. """ + """A CDP event object.""" + name: str description: str | None deprecated: bool @@ -721,59 +722,56 @@ class CdpEvent: @property def py_name(self): - """ Return the Python class name for this event. """ + """Return the Python class name for this event.""" return inflection.camelize(self.name, uppercase_first_letter=True) @classmethod def from_json(cls, json: dict, domain: str): - """ Create a new CDP event instance from a JSON dict. """ + """Create a new CDP event instance from a JSON dict.""" return cls( - json['name'], - json.get('description'), - json.get('deprecated', False), - json.get('experimental', False), - [cast(CdpParameter, CdpParameter.from_json(p)) - for p in json.get('parameters', [])], - domain + json["name"], + json.get("description"), + json.get("deprecated", False), + json.get("experimental", False), + [cast(CdpParameter, CdpParameter.from_json(p)) for p in json.get("parameters", [])], + domain, ) def generate_code(self): - """ Generate code for a CDP event. """ + """Generate code for a CDP event.""" global current_version - code = dedent(f'''\ + code = dedent(f"""\ @event_class('{self.domain}.{self.name}') @dataclass - class {self.py_name}:''') + class {self.py_name}:""") - code += '\n' - desc = '' + code += "\n" + desc = "" if self.description or self.experimental: if self.experimental: - desc += '**EXPERIMENTAL**\n\n' + desc += "**EXPERIMENTAL**\n\n" if self.description: desc += self.description code += indent(docstring(desc), 4) - code += '\n' - code += indent( - '\n'.join(p.generate_decl() for p in self.parameters), 4) - code += '\n\n' - def_from_json = dedent(f'''\ + code += "\n" + code += indent("\n".join(p.generate_decl() for p in self.parameters), 4) + code += "\n\n" + def_from_json = dedent(f"""\ @classmethod def from_json(cls, json: T_JSON_DICT) -> {self.py_name}: return cls( - ''') + """) code += indent(def_from_json, 4) - from_json = ',\n'.join(p.generate_from_json(dict_='json') - for p in self.parameters) + from_json = ",\n".join(p.generate_from_json(dict_="json") for p in self.parameters) code += indent(from_json, 12) - code += '\n' - code += indent(')', 8) + code += "\n" + code += indent(")", 8) return code def get_refs(self): - """ Get all refs for this event. """ + """Get all refs for this event.""" refs = set() for param in self.parameters: if param.items and param.items.ref: @@ -785,7 +783,8 @@ def get_refs(self): @dataclass class CdpDomain: - """ A CDP domain contains metadata, types, commands, and events. """ + """A CDP domain contains metadata, types, commands, and events.""" + domain: str description: str | None experimental: bool @@ -796,45 +795,44 @@ class CdpDomain: @property def module(self) -> str: - """ The name of the Python module for this CDP domain. """ + """The name of the Python module for this CDP domain.""" return snake_case(self.domain) @classmethod def from_json(cls, domain: dict): - """ Instantiate a CDP domain from a JSON object. """ - types = domain.get('types', []) - commands = domain.get('commands', []) - events = domain.get('events', []) - domain_name = domain['domain'] + """Instantiate a CDP domain from a JSON object.""" + types = domain.get("types", []) + commands = domain.get("commands", []) + events = domain.get("events", []) + domain_name = domain["domain"] return cls( domain_name, - domain.get('description'), - domain.get('experimental', False), - domain.get('dependencies', []), + domain.get("description"), + domain.get("experimental", False), + domain.get("dependencies", []), [CdpType.from_json(type) for type in types], - [CdpCommand.from_json(command, domain_name) - for command in commands], - [CdpEvent.from_json(event, domain_name) for event in events] + [CdpCommand.from_json(command, domain_name) for command in commands], + [CdpEvent.from_json(event, domain_name) for event in events], ) def generate_code(self): - """ Generate the Python module code for a given CDP domain. """ - exp = ' (experimental)' if self.experimental else '' + """Generate the Python module code for a given CDP domain.""" + exp = " (experimental)" if self.experimental else "" code = MODULE_HEADER.format(self.domain, exp) import_code = self.generate_imports() if import_code: code += import_code - code += '\n\n' - code += '\n' + code += "\n\n" + code += "\n" item_iter_t = Union[CdpEvent, CdpCommand, CdpType] item_iter: Iterator[item_iter_t] = itertools.chain( iter(self.types), iter(self.commands), iter(self.events), ) - code += '\n\n\n'.join(item.generate_code() for item in item_iter) - code += '\n' + code += "\n\n\n".join(item.generate_code() for item in item_iter) + code += "\n" return code def generate_imports(self): @@ -856,12 +854,12 @@ def generate_imports(self): dependencies = set() for ref in refs: try: - domain, _ = ref.split('.') + domain, _ = ref.split(".") except ValueError: continue if domain != self.domain: dependencies.add(snake_case(domain)) - code = '\n'.join(f'from . import {d}' for d in sorted(dependencies)) + code = "\n".join(f"from . import {d}" for d in sorted(dependencies)) return code @@ -869,34 +867,34 @@ def generate_sphinx(self): """ Generate a Sphinx document for this domain. """ - docs = self.domain + '\n' - docs += '=' * len(self.domain) + '\n\n' + docs = self.domain + "\n" + docs += "=" * len(self.domain) + "\n\n" if self.description: - docs += f'{self.description}\n\n' + docs += f"{self.description}\n\n" if self.experimental: - docs += '*This CDP domain is experimental.*\n\n' - docs += f'.. module:: cdp.{self.module}\n\n' - docs += '* Types_\n* Commands_\n* Events_\n\n' + docs += "*This CDP domain is experimental.*\n\n" + docs += f".. module:: cdp.{self.module}\n\n" + docs += "* Types_\n* Commands_\n* Events_\n\n" - docs += 'Types\n-----\n\n' + docs += "Types\n-----\n\n" if self.types: - docs += dedent('''\ + docs += dedent("""\ Generally, you do not need to instantiate CDP types yourself. Instead, the API creates objects for you as return values from commands, and then you can use those objects as arguments to other commands. - ''') + """) else: - docs += '*There are no types in this module.*\n' + docs += "*There are no types in this module.*\n" for type in self.types: - docs += f'\n.. autoclass:: {type.id}\n' - docs += ' :members:\n' - docs += ' :undoc-members:\n' - docs += ' :exclude-members: from_json, to_json\n' + docs += f"\n.. autoclass:: {type.id}\n" + docs += " :members:\n" + docs += " :undoc-members:\n" + docs += " :exclude-members: from_json, to_json\n" - docs += '\nCommands\n--------\n\n' + docs += "\nCommands\n--------\n\n" if self.commands: - docs += dedent('''\ + docs += dedent("""\ Each command is a generator function. The return type ``Generator[x, y, z]`` indicates that the generator *yields* arguments of type ``x``, it must be resumed with @@ -905,26 +903,26 @@ def generate_sphinx(self): commands, and ``z`` is the return type you should pay attention to. For more information, see :ref:`Getting Started: Commands `. - ''') + """) else: - docs += '*There are no types in this module.*\n' - for command in sorted(self.commands, key=operator.attrgetter('py_name')): - docs += f'\n.. autofunction:: {command.py_name}\n' + docs += "*There are no types in this module.*\n" + for command in sorted(self.commands, key=operator.attrgetter("py_name")): + docs += f"\n.. autofunction:: {command.py_name}\n" - docs += '\nEvents\n------\n\n' + docs += "\nEvents\n------\n\n" if self.events: - docs += dedent('''\ + docs += dedent("""\ Generally, you do not need to instantiate CDP events yourself. Instead, the API creates events for you and then you use the event\'s attributes. - ''') + """) else: - docs += '*There are no events in this module.*\n' + docs += "*There are no events in this module.*\n" for event in self.events: - docs += f'\n.. autoclass:: {event.py_name}\n' - docs += ' :members:\n' - docs += ' :undoc-members:\n' - docs += ' :exclude-members: from_json, to_json\n' + docs += f"\n.. autoclass:: {event.py_name}\n" + docs += " :members:\n" + docs += " :undoc-members:\n" + docs += " :exclude-members: from_json, to_json\n" return docs @@ -939,11 +937,11 @@ def parse(json_path, output_path): global current_version with open(json_path, encoding="utf-8") as json_file: schema = json.load(json_file) - version = schema['version'] - assert (version['major'], version['minor']) == ('1', '3') - current_version = f'{version["major"]}.{version["minor"]}' + version = schema["version"] + assert (version["major"], version["minor"]) == ("1", "3") + current_version = f"{version['major']}.{version['minor']}" domains = [] - for domain in schema['domains']: + for domain in schema["domains"]: domains.append(CdpDomain.from_json(domain)) return domains @@ -958,15 +956,15 @@ def generate_init(init_path, domains): with open(init_path, "w", encoding="utf-8") as init_file: init_file.write(INIT_HEADER) for domain in domains: - init_file.write(f'from . import {domain.module}\n') - init_file.write('from . import util\n\n') + init_file.write(f"from . import {domain.module}\n") + init_file.write("from . import util\n\n") def generate_docs(docs_path, domains): """ Generate Sphinx documents for each domain. """ - logger.info('Generating Sphinx documents') + logger.info("Generating Sphinx documents") # Remove generated documents for subpath in docs_path.iterdir(): @@ -974,13 +972,13 @@ def generate_docs(docs_path, domains): # Generate document for each domain for domain in domains: - doc = docs_path / f'{domain.module}.rst' - with doc.open('w') as f: + doc = docs_path / f"{domain.module}.rst" + with doc.open("w") as f: f.write(domain.generate_sphinx()) def main(browser_protocol_path, js_protocol_path, output_path): - """ Main entry point. """ + """Main entry point.""" output_path = Path(output_path).resolve() json_paths = [ browser_protocol_path, @@ -989,45 +987,44 @@ def main(browser_protocol_path, js_protocol_path, output_path): # Generate util.py util_path = output_path / "util.py" - with util_path.open('w') as util_file: + with util_path.open("w") as util_file: util_file.write(UTIL_PY) # Remove generated code for subpath in output_path.iterdir(): - if subpath.is_file() and subpath.name not in ('py.typed', 'util.py'): + if subpath.is_file() and subpath.name not in ("py.typed", "util.py"): subpath.unlink() # Parse domains domains = [] for json_path in json_paths: - logger.info('Parsing JSON file %s', json_path) + logger.info("Parsing JSON file %s", json_path) domains.extend(parse(json_path, output_path)) - domains.sort(key=operator.attrgetter('domain')) + domains.sort(key=operator.attrgetter("domain")) # Patch up CDP errors. It's easier to patch that here than it is to modify # the generator code. # 1. DOM includes an erroneous $ref that refers to itself. # 2. Page includes an event with an extraneous backtick in the description. for domain in domains: - if domain.domain == 'DOM': + if domain.domain == "DOM": for cmd in domain.commands: - if cmd.name == 'resolveNode': + if cmd.name == "resolveNode": # Patch 1 - cmd.parameters[1].ref = 'BackendNodeId' - elif domain.domain == 'Page': + cmd.parameters[1].ref = "BackendNodeId" + elif domain.domain == "Page": for event in domain.events: - if event.name == 'screencastVisibilityChanged': + if event.name == "screencastVisibilityChanged": # Patch 2 - event.description = event.description.replace('`', '') + event.description = event.description.replace("`", "") for domain in domains: - logger.info('Generating module: %s → %s.py', domain.domain, - domain.module) - module_path = output_path / f'{domain.module}.py' - with module_path.open('w') as module_file: + logger.info("Generating module: %s → %s.py", domain.domain, domain.module) + module_path = output_path / f"{domain.module}.py" + with module_path.open("w") as module_file: module_file.write(domain.generate_code()) - init_path = output_path / '__init__.py' + init_path = output_path / "__init__.py" generate_init(init_path, domains) # Not generating the docs as we don't want people to directly @@ -1035,12 +1032,13 @@ def main(browser_protocol_path, js_protocol_path, output_path): # docs_path = here.parent / 'docs' / 'api' # generate_docs(docs_path, domains) - py_typed_path = output_path / 'py.typed' + py_typed_path = output_path / "py.typed" py_typed_path.touch() -if __name__ == '__main__': +if __name__ == "__main__": import sys + assert sys.version_info >= (3, 7), "To generate the CDP code requires python 3.7 or later" args = sys.argv[1:] main(*args)