diff --git a/WORKSPACE b/WORKSPACE index da43e0fba4498..5491a0e009224 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -20,6 +20,7 @@ load("@apple_rules_lint//lint:setup.bzl", "lint_setup") # Add your linters here. lint_setup({ "java-spotbugs": "//java:spotbugs-config", + "py-black": "//py:black-config", "rust-rustfmt": "//rust:enable-rustfmt", }) diff --git a/py/BUILD.bazel b/py/BUILD.bazel index 2698244fb9671..ba7f8e0863c5c 100644 --- a/py/BUILD.bazel +++ b/py/BUILD.bazel @@ -2,13 +2,17 @@ load("@bazel_skylib//rules:select_file.bzl", "select_file") load("@py_dev_requirements//:requirements.bzl", "requirement") load("@rules_pkg//pkg:mappings.bzl", "pkg_files", "strip_prefix") load("@rules_pkg//pkg:pkg.bzl", "pkg_tar") -load("@rules_python//python:defs.bzl", "py_binary", "py_library") load("@rules_python//python:packaging.bzl", "py_package", "py_wheel") load("@rules_python//python:pip.bzl", "compile_pip_requirements") load("//common:defs.bzl", "copy_file") -load("//py:defs.bzl", "generate_devtools", "py_test_suite") +load("//py:defs.bzl", "black_config", "generate_devtools", "py_binary", "py_import", "py_library", "py_test_suite") load("//py/private:browsers.bzl", "BROWSERS") -load("//py/private:import.bzl", "py_import") + +black_config( + name = "black-config", + line_length = 120, + visibility = ["//visibility:public"], +) alias( name = "twine", @@ -23,6 +27,9 @@ genrule( ], outs = ["pypi_upload_complete.txt"], cmd = "(twine upload $(location :selenium-wheel) $(location :selenium-sdist) && touch $@)", + tags = [ + "manual", + ], tools = [":twine"], ) diff --git a/py/defs.bzl b/py/defs.bzl index 8f8b4ff94b5ac..9afb6a2ac37d6 100644 --- a/py/defs.bzl +++ b/py/defs.bzl @@ -1,9 +1,14 @@ load("//py/private:generate_devtools.bzl", _generate_devtools = "generate_devtools") load("//py/private:import.bzl", _py_import = "py_import") load("//py/private:pytest.bzl", _pytest_test = "pytest_test") +load("//py/private:py_with_lint_macro.bzl", _py_binary = "py_binary", _py_library = "py_library") load("//py/private:suite.bzl", _py_test_suite = "py_test_suite") +load("//py/private:black_config.bzl", _black_config = "black_config") +black_config = _black_config generate_devtools = _generate_devtools pytest_test = _pytest_test +py_binary = _py_binary +py_library = _py_library py_import = _py_import py_test_suite = _py_test_suite diff --git a/py/docs/source/conf.py b/py/docs/source/conf.py index 433869b30a80f..0776c9c33995f 100644 --- a/py/docs/source/conf.py +++ b/py/docs/source/conf.py @@ -29,101 +29,109 @@ # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +# needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.imgmath', 'sphinx.ext.viewcode'] +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.doctest", + "sphinx.ext.todo", + "sphinx.ext.coverage", + "sphinx.ext.imgmath", + "sphinx.ext.viewcode", +] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] # The suffix of source filenames. -source_suffix = '.rst' +source_suffix = ".rst" # The encoding of source files. -#source_encoding = 'utf-8-sig' +# source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'index' +master_doc = "index" # General information about the project. -project = 'Selenium' -copyright = '2009-2023 Software Freedom Conservancy' +project = "Selenium" +copyright = "2009-2023 Software Freedom Conservancy" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '4.19' +version = "4.19" # The full version, including alpha/beta/rc tags. -release = '4.19.0.dev202403101143' +release = "4.19.0.dev202403101143" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -#language = None +# language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: -#today = '' +# today = '' # Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' +# today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = [] # The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None +# default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +# add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). -#add_module_names = True +# add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False +# show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = "sphinx" # A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +# modindex_common_prefix = [] # -- Options for HTML output --------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +html_theme = "default" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +# html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +# html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +# html_title = None # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +# html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = None +# html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -#html_favicon = None +# html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -132,27 +140,27 @@ # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' +# html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +# html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. -#html_additional_pages = {} +# html_additional_pages = {} # If false, no module index is generated. -#html_domain_indices = True +# html_domain_indices = True # If false, no index is generated. -#html_use_index = True +# html_use_index = True # If true, the index is split into individual pages for each letter. -#html_split_index = False +# html_split_index = False # If true, links to the reST sources are added to the pages. html_show_sourcelink = True @@ -161,57 +169,62 @@ html_show_sphinx = False # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True +# html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. -#html_use_opensearch = '' +# html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None +# html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'Seleniumdoc' +htmlhelp_basename = "Seleniumdoc" # -- Options for LaTeX output -------------------------------------------------- # The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' +# latex_paper_size = 'letter' # The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' +# latex_font_size = '10pt' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'Selenium.tex', 'Selenium Documentation', - 'plightbo, simon.m.stewart, hbchai, jrhuggins, et al.', 'manual'), + ( + "index", + "Selenium.tex", + "Selenium Documentation", + "plightbo, simon.m.stewart, hbchai, jrhuggins, et al.", + "manual", + ), ] # The name of an image file (relative to this directory) to place at the top of # the title page. -#latex_logo = None +# latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. -#latex_use_parts = False +# latex_use_parts = False # If true, show page references after internal links. -#latex_show_pagerefs = False +# latex_show_pagerefs = False # If true, show URL addresses after external links. -#latex_show_urls = False +# latex_show_urls = False # Additional stuff for the LaTeX preamble. -#latex_preamble = '' +# latex_preamble = '' # Documents to append as an appendix to all manuals. -#latex_appendices = [] +# latex_appendices = [] # If false, no module index is generated. -#latex_domain_indices = True +# latex_domain_indices = True # -- Options for manual page output -------------------------------------------- @@ -219,64 +232,63 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'selenium', 'Selenium Documentation', - ['plightbo, simon.m.stewart, hbchai, jrhuggins, et al.'], 1) + ("index", "selenium", "Selenium Documentation", ["plightbo, simon.m.stewart, hbchai, jrhuggins, et al."], 1) ] # -- Options for Epub output --------------------------------------------------- # Bibliographic Dublin Core info. -epub_title = 'Selenium' -epub_author = 'The Selenium Project' -epub_publisher = 'The Selenium Project' -epub_copyright = '2009-2023 Software Freedom Conservancy' +epub_title = "Selenium" +epub_author = "The Selenium Project" +epub_publisher = "The Selenium Project" +epub_copyright = "2009-2023 Software Freedom Conservancy" # The language of the text. It defaults to the language option # or en if the language is not set. -#epub_language = '' +# epub_language = '' # The scheme of the identifier. Typical schemes are ISBN or URL. -#epub_scheme = '' +# epub_scheme = '' # The unique identifier of the text. This can be a ISBN number # or the project homepage. -#epub_identifier = '' +# epub_identifier = '' # A unique identification for the text. -#epub_uid = '' +# epub_uid = '' # HTML files that should be inserted before the pages created by sphinx. # The format is a list of tuples containing the path and title. -#epub_pre_files = [] +# epub_pre_files = [] # HTML files that should be inserted after the pages created by sphinx. # The format is a list of tuples containing the path and title. -#epub_post_files = [] +# epub_post_files = [] # A list of files that should not be packed into the epub file. -#epub_exclude_files = [] +# epub_exclude_files = [] # The depth of the table of contents in toc.ncx. -#epub_tocdepth = 3 +# epub_tocdepth = 3 # Allow duplicate toc entries. -#epub_tocdup = True +# epub_tocdup = True # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} +intersphinx_mapping = {"http://docs.python.org/": None} # 'members' includes anything that has a docstring, 'undoc-members' includes # functions without docstrings. -autodoc_default_flags = ['members', 'undoc-members'] +autodoc_default_flags = ["members", "undoc-members"] # configuration for keeping the methods that can be invoked on said classes autodoc_default_options = { - 'members': True, - 'member-order': 'bysource', - 'undoc-members': True, - 'inherited-members': True, + "members": True, + "member-order": "bysource", + "undoc-members": True, + "inherited-members": True, } # Include __init__ comments diff --git a/py/generate.py b/py/generate.py index 5d6ea7cb4b0ef..fc42af7a842f3 100644 --- a/py/generate.py +++ b/py/generate.py @@ -41,19 +41,21 @@ 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 @@ -61,9 +63,11 @@ from dataclasses import dataclass import enum import typing -'''.format(SHARED_HEADER) +""".format( + SHARED_HEADER +) -current_version = '' +current_version = "" UTIL_PY = """ import typing @@ -88,56 +92,57 @@ 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): - ''' + """ 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': + 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 @@ -146,64 +151,67 @@ 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 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: typing.Optional[str] type: typing.Optional[str] @@ -216,59 +224,57 @@ class CdpProperty: @property def py_name(self): - ''' 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) 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( - typing.cast(str, self.type)) + ann = CdpPrimitiveType.get_annotation(typing.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: @@ -281,31 +287,32 @@ 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 @@ -313,7 +320,8 @@ def generate_from_json(self, dict_): @dataclass class CdpType: - ''' A top-level CDP type. ''' + """A top-level CDP type.""" + id: str description: typing.Optional[str] type: str @@ -323,19 +331,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: @@ -343,126 +351,142 @@ 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 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 = 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 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'''\ + 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. @@ -483,75 +507,75 @@ 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( - typing.cast(str, self.type)) + py_type = CdpPrimitiveType.get_annotation(typing.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_): - ''' + """ 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) @@ -559,27 +583,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 @@ -590,42 +615,42 @@ class CdpCommand: @property def py_name(self): - ''' 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), [typing.cast(CdpParameter, CdpParameter.from_json(p)) for p in parameters], [typing.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 @@ -634,70 +659,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: @@ -709,7 +731,8 @@ def get_refs(self): @dataclass class CdpEvent: - ''' A CDP event object. ''' + """A CDP event object.""" + name: str description: typing.Optional[str] deprecated: bool @@ -719,59 +742,60 @@ 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), - [typing.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), + [typing.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: @@ -783,7 +807,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: typing.Optional[str] experimental: bool @@ -794,56 +819,55 @@ class CdpDomain: @property def module(self): - ''' 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 = typing.Union[CdpEvent, CdpCommand, CdpType] item_iter: typing.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): - ''' + """ 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() @@ -854,47 +878,50 @@ 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 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 @@ -903,68 +930,71 @@ 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 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) - version = schema['version'] - assert (version['major'], version['minor']) == ('1', '3') + 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 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: - 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(): @@ -972,13 +1002,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, @@ -987,45 +1017,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 @@ -1033,12 +1062,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) diff --git a/py/private/BUILD.bazel b/py/private/BUILD.bazel index 43611ccd9eb74..89d7a1ef81cfb 100644 --- a/py/private/BUILD.bazel +++ b/py/private/BUILD.bazel @@ -1,10 +1,29 @@ +load("@py_dev_requirements//:requirements.bzl", "requirement") load("@rules_python//python:defs.bzl", "py_binary") +package(default_visibility = ["//visibility:public"]) + py_binary( name = "untar", srcs = [ "untar.py", ], legacy_create_init = False, - visibility = ["//visibility:public"], +) + +alias( + name = "black", + actual = ":black-bin", +) + +py_binary( + name = "black-bin", + srcs = [ + # If the source is called `black` you can't then import black into black + "black-bin.py", + ], + legacy_create_init = False, + deps = [ + requirement("black"), + ], ) diff --git a/py/private/black-bin.py b/py/private/black-bin.py new file mode 100644 index 0000000000000..f58292842985b --- /dev/null +++ b/py/private/black-bin.py @@ -0,0 +1,25 @@ +# Licensed to the Software Freedom Conservancy (SFC) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The SFC licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +import re +import sys + +from black import patched_main + +if __name__ == "__main__": + sys.argv[0] = re.sub(r"(-script\.pyw|\.exe)?$", "", sys.argv[0]) + sys.exit(patched_main()) diff --git a/py/private/black_config.bzl b/py/private/black_config.bzl new file mode 100644 index 0000000000000..0f77723258a92 --- /dev/null +++ b/py/private/black_config.bzl @@ -0,0 +1,31 @@ +BlackConfigInfo = provider( + fields = { + "black": "binary: The binary to execute for black", + "line_length": "`int`: Maximum line length", + "python_version": "`array of strings`: The versions of Python to target", + }, +) + +def black_config_impl(ctx): + return [ + BlackConfigInfo( + black = ctx.attr.black, + line_length = ctx.attr.line_length, + python_version = ctx.attr.python_version, + ), + ] + +black_config = rule( + black_config_impl, + attrs = { + "black": attr.label( + cfg = "exec", + default = "//py/private:black", + executable = True, + ), + "line_length": attr.int( + default = 88, + ), + "python_version": attr.string_list(), + }, +) diff --git a/py/private/black_test.bzl b/py/private/black_test.bzl new file mode 100644 index 0000000000000..755327111aef4 --- /dev/null +++ b/py/private/black_test.bzl @@ -0,0 +1,63 @@ +load(":black_config.bzl", "BlackConfigInfo") + +def black_test_impl(ctx): + config = ctx.attr.config[BlackConfigInfo] + + all_inputs = [] + black = config.black[DefaultInfo].files_to_run.executable + all_inputs.append(black) + + args = ctx.actions.args() + + for version in config.python_version: + args.add_all(["-t", version]) + + args.add_all(["--line-length", config.line_length]) + + args.add("--check") + + args.add_all(ctx.files.srcs) + all_inputs.extend(ctx.files.srcs) + + # Run on a single core + args.add_all(["--workers", "1"]) + + if config.python_version: + args.add_all(["--target-version", config.python_version]) + + args.use_param_file("@%s", use_always = True) + args_file = ctx.actions.declare_file("%s-black-params" % ctx.label.name) + ctx.actions.write(args_file, args) + all_inputs.append(args_file) + + output = ctx.actions.declare_file("%s-black-test" % ctx.label.name) + ctx.actions.write( + output = output, + content = """#!/usr/bin/env bash +%s $(< %s) """ % (black.short_path, args_file.short_path), + is_executable = True, + ) + + return [DefaultInfo( + executable = output, + files = depset(), + runfiles = ctx.runfiles(files = all_inputs).merge( + config.black[DefaultInfo].default_runfiles, + ), + )] + +black_test = rule( + black_test_impl, + attrs = { + "srcs": attr.label_list( + allow_files = [".py"], + ), + "config": attr.label( + mandatory = True, + providers = [ + [BlackConfigInfo], + ], + ), + }, + test = True, +) diff --git a/py/private/py_with_lint_macro.bzl b/py/private/py_with_lint_macro.bzl new file mode 100644 index 0000000000000..5561bc5cb7e8a --- /dev/null +++ b/py/private/py_with_lint_macro.bzl @@ -0,0 +1,34 @@ +load("@apple_rules_lint//lint:defs.bzl", "get_lint_config") +load("@rules_python//python:defs.bzl", _py_binary = "py_binary", _py_library = "py_library", _py_test = "py_test") +load(":black_test.bzl", "black_test") + +def create_lint_tests(name, **kwargs): + config = get_lint_config("py-black", kwargs.get("tags", [])) + if config: + black_test( + name = "%s-black" % name, + srcs = kwargs.get("srcs", []), + config = config, + tags = kwargs.get("tags", []) + [ + "lint", + "black", + "py-black", + ], + ) + +def _add_lint_tests(actual, name, **kwargs): + actual( + name = name, + **kwargs + ) + + create_lint_tests(name, **kwargs) + +def py_binary(name, **kwargs): + _add_lint_tests(_py_binary, name, **kwargs) + +def py_library(name, **kwargs): + _add_lint_tests(_py_library, name, **kwargs) + +def py_test(name, **kwargs): + _add_lint_tests(_py_test, name, **kwargs) diff --git a/py/private/pytest.bzl b/py/private/pytest.bzl index c3280124fb7cc..1a0d50abcd79d 100644 --- a/py/private/pytest.bzl +++ b/py/private/pytest.bzl @@ -1,4 +1,5 @@ load("@rules_python//python:defs.bzl", "PyInfo", "py_test") +load(":py_with_lint_macro.bzl", "create_lint_tests") def _stringify(paths): return repr(paths) @@ -59,6 +60,11 @@ _pytest_runner = rule( def pytest_test(name, srcs, deps = None, args = None, data = None, python_version = None, **kwargs): runner_target = "%s-runner.py" % name + create_lint_tests( + name = name, + srcs = srcs, + ) + _pytest_runner( name = runner_target, testonly = True, diff --git a/py/private/untar.py b/py/private/untar.py index 6fcaf04c2e26e..8cead171688ca 100644 --- a/py/private/untar.py +++ b/py/private/untar.py @@ -19,7 +19,7 @@ import sys import tarfile -if __name__ == '__main__': +if __name__ == "__main__": outdir = sys.argv[2] if not os.path.exists(outdir): os.makedirs(outdir) diff --git a/py/requirements.txt b/py/requirements.txt index 41231696e0a13..79038b5387bd4 100644 --- a/py/requirements.txt +++ b/py/requirements.txt @@ -1,5 +1,6 @@ async-generator==1.10 attrs==23.1.0 +black==24.2.0 certifi==2023.7.22 cffi==1.16.0 cryptography==42.0.4 diff --git a/py/requirements_lock.txt b/py/requirements_lock.txt index 2d4f373a13f0c..9075fedcd9e75 100644 --- a/py/requirements_lock.txt +++ b/py/requirements_lock.txt @@ -18,6 +18,30 @@ attrs==23.1.0 \ # -r py/requirements.txt # outcome # trio +black==24.2.0 \ + --hash=sha256:057c3dc602eaa6fdc451069bd027a1b2635028b575a6c3acfd63193ced20d9c8 \ + --hash=sha256:08654d0797e65f2423f850fc8e16a0ce50925f9337fb4a4a176a7aa4026e63f8 \ + --hash=sha256:163baf4ef40e6897a2a9b83890e59141cc8c2a98f2dda5080dc15c00ee1e62cd \ + --hash=sha256:1e08fb9a15c914b81dd734ddd7fb10513016e5ce7e6704bdd5e1251ceee51ac9 \ + --hash=sha256:4dd76e9468d5536abd40ffbc7a247f83b2324f0c050556d9c371c2b9a9a95e31 \ + --hash=sha256:4f9de21bafcba9683853f6c96c2d515e364aee631b178eaa5145fc1c61a3cc92 \ + --hash=sha256:61a0391772490ddfb8a693c067df1ef5227257e72b0e4108482b8d41b5aee13f \ + --hash=sha256:6981eae48b3b33399c8757036c7f5d48a535b962a7c2310d19361edeef64ce29 \ + --hash=sha256:7e53a8c630f71db01b28cd9602a1ada68c937cbf2c333e6ed041390d6968faf4 \ + --hash=sha256:810d445ae6069ce64030c78ff6127cd9cd178a9ac3361435708b907d8a04c693 \ + --hash=sha256:93601c2deb321b4bad8f95df408e3fb3943d85012dddb6121336b8e24a0d1218 \ + --hash=sha256:992e451b04667116680cb88f63449267c13e1ad134f30087dec8527242e9862a \ + --hash=sha256:9db528bccb9e8e20c08e716b3b09c6bdd64da0dd129b11e160bf082d4642ac23 \ + --hash=sha256:a0057f800de6acc4407fe75bb147b0c2b5cbb7c3ed110d3e5999cd01184d53b0 \ + --hash=sha256:ba15742a13de85e9b8f3239c8f807723991fbfae24bad92d34a2b12e81904982 \ + --hash=sha256:bce4f25c27c3435e4dace4815bcb2008b87e167e3bf4ee47ccdc5ce906eb4894 \ + --hash=sha256:ca610d29415ee1a30a3f30fab7a8f4144e9d34c89a235d81292a1edb2b55f540 \ + --hash=sha256:d533d5e3259720fdbc1b37444491b024003e012c5173f7d06825a77508085430 \ + --hash=sha256:d84f29eb3ee44859052073b7636533ec995bd0f64e2fb43aeceefc70090e752b \ + --hash=sha256:e37c99f89929af50ffaf912454b3e3b47fd64109659026b678c091a4cd450fb2 \ + --hash=sha256:e8a6ae970537e67830776488bca52000eaa37fa63b9988e8c487458d9cd5ace6 \ + --hash=sha256:faf2ee02e6612577ba0181f4347bcbcf591eb122f7841ae5ba233d12c39dcb4d + # via -r py/requirements.txt certifi==2023.7.22 \ --hash=sha256:539cc1d13202e33ca466e88b2807e29f4c13049d6d87031a3c110744495cb082 \ --hash=sha256:92d6037539857d8206b8f6ae472e8b77db8058fec5937a1ef3f54304089edbb9 @@ -172,6 +196,10 @@ charset-normalizer==3.3.2 \ --hash=sha256:fd1abc0d89e30cc4e02e4064dc67fcc51bd941eb395c502aac3ec19fab46b519 \ --hash=sha256:ff8fa367d09b717b2a17a052544193ad76cd49979c805768879cb63d9ca50561 # via requests +click==8.1.7 \ + --hash=sha256:ae74fb96c20a0277a1d615f1e4d73c8414f5a98db8b799a7931d1582f3390c28 \ + --hash=sha256:ca9853ad459e787e2192211578cc907e7594e294c7ccc834310722b41b9ca6de + # via black cryptography==42.0.4 \ --hash=sha256:01911714117642a3f1792c7f376db572aadadbafcd8d75bb527166009c9f1d1b \ --hash=sha256:0e89f7b84f421c56e7ff69f11c441ebda73b8a8e6488d322ef71746224c20fce \ @@ -359,6 +387,10 @@ multidict==6.0.2 \ --hash=sha256:feba80698173761cddd814fa22e88b0661e98cb810f9f986c54aa34d281e4937 \ --hash=sha256:feea820722e69451743a3d56ad74948b68bf456984d63c1a92e8347b7b88452d # via -r py/requirements.txt +mypy-extensions==1.0.0 \ + --hash=sha256:4392f6c0eb8a5668a69e23d168ffa70f0be9ccfd32b5cc2d26a34ae5b844552d \ + --hash=sha256:75dbf8955dc00442a438fc4d0666508a9a97b6bd41aa2f0ffe9d2f2725af0782 + # via black nh3==0.2.15 \ --hash=sha256:0d02d0ff79dfd8208ed25a39c12cbda092388fff7f1662466e27d97ad011b770 \ --hash=sha256:3277481293b868b2715907310c7be0f1b9d10491d5adf9fce11756a97e97eddf \ @@ -389,11 +421,20 @@ packaging==23.2 \ --hash=sha256:8c491190033a9af7e1d931d0b5dacc2ef47509b34dd0de67ed209b5203fc88c7 # via # -r py/requirements.txt + # black # pytest +pathspec==0.12.1 \ + --hash=sha256:a0d503e138a4c123b27490a4f7beda6a01c6f288df0e4a8b79c7eb0dc7b4cc08 \ + --hash=sha256:a482d51503a1ab33b1c67a6c3813a26953dbdc71c31dacaef9a838c4e29f5712 + # via black pkginfo==1.9.6 \ --hash=sha256:4b7a555a6d5a22169fcc9cf7bfd78d296b0361adad412a346c1226849af5e546 \ --hash=sha256:8fd5896e8718a4372f0ea9cc9d96f6417c9b986e23a4d116dda26b62cc29d046 # via twine +platformdirs==4.2.0 \ + --hash=sha256:0614df2a2f37e1a662acbd8e2b25b92ccf8632929bc6d43467e17fe89c75e068 \ + --hash=sha256:ef0cc731df711022c174543cb70a9b5bd22e5a9337c8624ef2c2ceb8ddad8768 + # via black pluggy==1.3.0 \ --hash=sha256:cf61ae8f126ac6f7c451172cf30e3e43d3ca77615509771b3a984a0730651e12 \ --hash=sha256:d89c696a773f8bd377d18e5ecda92b7a3793cbe66c87060a6fb58c7b6e1061f7 @@ -492,7 +533,9 @@ toml==0.10.2 \ tomli==2.0.1 \ --hash=sha256:939de3e7a6161af0c887ef91b7d41a53e7c5a1ca976325f429cb46ea9bc30ecc \ --hash=sha256:de526c12914f0c550d15924c62d72abc48d6fe7364aa87328337a31007fe8a4f - # via pytest + # via + # black + # pytest trio==0.22.0 \ --hash=sha256:ce68f1c5400a47b137c5a4de72c7c901bd4e7a24fbdebfe9b41de8c6c04eaacf \ --hash=sha256:f1dd0780a89bfc880c7c7994519cb53f62aacb2c25ff487001c0052bd721cdf0 @@ -513,6 +556,7 @@ typing-extensions==4.9.0 \ --hash=sha256:af72aea155e91adfc61c3ae9e0e342dbc0cba726d6cba4b6c72c1f34e47291cd # via # -r py/requirements.txt + # black # rich urllib3[socks]==2.0.7 \ --hash=sha256:c97dfde1f7bd43a71c8d2a58e369e9b2bf692d1334ea9f9cae55add7d0dd0f84 \ diff --git a/py/setup.py b/py/setup.py index 39fd531b3f5d6..91e8075e7ac50 100755 --- a/py/setup.py +++ b/py/setup.py @@ -22,63 +22,67 @@ for scheme in INSTALL_SCHEMES.values(): - scheme['data'] = scheme['purelib'] + scheme["data"] = scheme["purelib"] setup_args = { - 'cmdclass': {'install': install}, - 'name': 'selenium', - 'version': "4.19.0.dev202403101143", - 'license': 'Apache 2.0', - 'description': 'Python bindings for Selenium', - 'long_description': open(join(abspath(dirname(__file__)), "README.rst")).read(), - 'url': 'https://github.com/SeleniumHQ/selenium/', - 'project_urls': { - 'Bug Tracker': 'https://github.com/SeleniumHQ/selenium/issues', - 'Changes': 'https://github.com/SeleniumHQ/selenium/blob/trunk/py/CHANGES', - 'Documentation': 'https://www.selenium.dev/documentation/overview/', - 'Source Code': 'https://github.com/SeleniumHQ/selenium/tree/trunk/py', + "cmdclass": {"install": install}, + "name": "selenium", + "version": "4.19.0.dev202403101143", + "license": "Apache 2.0", + "description": "Python bindings for Selenium", + "long_description": open(join(abspath(dirname(__file__)), "README.rst")).read(), + "url": "https://github.com/SeleniumHQ/selenium/", + "project_urls": { + "Bug Tracker": "https://github.com/SeleniumHQ/selenium/issues", + "Changes": "https://github.com/SeleniumHQ/selenium/blob/trunk/py/CHANGES", + "Documentation": "https://www.selenium.dev/documentation/overview/", + "Source Code": "https://github.com/SeleniumHQ/selenium/tree/trunk/py", }, - 'python_requires': '~=3.8', - 'classifiers': ['Development Status :: 5 - Production/Stable', - 'Intended Audience :: Developers', - 'License :: OSI Approved :: Apache Software License', - 'Operating System :: POSIX', - 'Operating System :: Microsoft :: Windows', - 'Operating System :: MacOS :: MacOS X', - 'Topic :: Software Development :: Testing', - 'Topic :: Software Development :: Libraries', - 'Programming Language :: Python', - 'Programming Language :: Python :: 3.8', - 'Programming Language :: Python :: 3.9', - 'Programming Language :: Python :: 3.10', - 'Programming Language :: Python :: 3.11', - 'Programming Language :: Python :: 3.12'], - 'package_dir': { - 'selenium': 'selenium', - 'selenium.common': 'selenium/common', - 'selenium.webdriver': 'selenium/webdriver', + "python_requires": "~=3.8", + "classifiers": [ + "Development Status :: 5 - Production/Stable", + "Intended Audience :: Developers", + "License :: OSI Approved :: Apache Software License", + "Operating System :: POSIX", + "Operating System :: Microsoft :: Windows", + "Operating System :: MacOS :: MacOS X", + "Topic :: Software Development :: Testing", + "Topic :: Software Development :: Libraries", + "Programming Language :: Python", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + ], + "package_dir": { + "selenium": "selenium", + "selenium.common": "selenium/common", + "selenium.webdriver": "selenium/webdriver", }, - 'packages': ['selenium', - 'selenium.common', - 'selenium.webdriver', - 'selenium.webdriver.chromium', - 'selenium.webdriver.chrome', - 'selenium.webdriver.common', - 'selenium.webdriver.support', - 'selenium.webdriver.firefox', - 'selenium.webdriver.ie', - 'selenium.webdriver.edge', - 'selenium.webdriver.remote', - 'selenium.webdriver.support', ], - 'include_package_data': True, - 'install_requires': [ + "packages": [ + "selenium", + "selenium.common", + "selenium.webdriver", + "selenium.webdriver.chromium", + "selenium.webdriver.chrome", + "selenium.webdriver.common", + "selenium.webdriver.support", + "selenium.webdriver.firefox", + "selenium.webdriver.ie", + "selenium.webdriver.edge", + "selenium.webdriver.remote", + "selenium.webdriver.support", + ], + "include_package_data": True, + "install_requires": [ "typing_extensions~= 4.9", "urllib3[socks]>=1.26,<3", "trio~=0.17", "trio-websocket~=0.9", "certifi>=2021.10.8", ], - 'zip_safe': False + "zip_safe": False, } setup(**setup_args) diff --git a/scripts/format.sh b/scripts/format.sh index 0f632a340f4f9..66693d280b95a 100755 --- a/scripts/format.sh +++ b/scripts/format.sh @@ -16,6 +16,11 @@ section "Java" echo " google-java-format" >&2 find "$PWD/java" -type f -name '*.java' | xargs "$GOOGLE_JAVA_FORMAT" --replace +section "Python" +echo " black" >&2 +# Keep the flags here in sync with what we have in `//py:black-config` +bazel run //py/private:black -- --line-length 120 "$(pwd)/py" + section "Rust" echo " rustfmt" >&2 bazel run @rules_rust//:rustfmt