From 37b88f1da0968001285559734c9888260c51dc13 Mon Sep 17 00:00:00 2001 From: Eric Pinzur Date: Mon, 9 Oct 2023 05:46:06 -0500 Subject: [PATCH] fix lint --- .github/workflows/ci_python.yml | 3 +- python/docs/_scripts/builder.py | 46 ++++++++++++-------- python/docs/_scripts/renderer.py | 67 ++++++++++++++++------------- python/docs/_scripts/summarizer.py | 7 +-- python/docs/examples/bluesky.py | 16 ++++--- python/pysrc/kaskada/_timestream.py | 39 ++++++++++++----- 6 files changed, 109 insertions(+), 69 deletions(-) diff --git a/.github/workflows/ci_python.yml b/.github/workflows/ci_python.yml index 9321ebccc..b467b5fff 100644 --- a/.github/workflows/ci_python.yml +++ b/.github/workflows/ci_python.yml @@ -64,7 +64,7 @@ jobs: poetry run black --diff pysrc pytests docs - name: flake8 run: | - poetry run flake8 pysrc pytests docs + poetry run flake8 pysrc pytests - name: isort run: | poetry run isort --filter-files --diff pysrc pytests docs @@ -137,6 +137,7 @@ jobs: - name: Build docs run: | poetry env use 3.11 + source $(poetry env info --path)/bin/activate poetry install --only=dev nox -s docs-gen nox -s docs-build diff --git a/python/docs/_scripts/builder.py b/python/docs/_scripts/builder.py index f2e4055b5..e7c199457 100644 --- a/python/docs/_scripts/builder.py +++ b/python/docs/_scripts/builder.py @@ -2,16 +2,13 @@ import logging import sys - from pathlib import Path -from pydantic import ValidationError - -from quartodoc.inventory import create_inventory, convert_inventory -from quartodoc import layout, preview, blueprint, collect -from quartodoc.validation import fmt - from typing import Any, Union +from pydantic import ValidationError +from quartodoc import blueprint, collect, layout, preview +from quartodoc.inventory import convert_inventory, create_inventory +from quartodoc.validation import fmt from renderer import Renderer from summarizer import Summarizer @@ -136,7 +133,7 @@ def build(self): convert_inventory(inv, self.out_inventory) def get_package(self, item: Union[layout.Section, layout.Page]) -> str: - if item.package and f'{item.package}' != "": + if item.package and f"{item.package}" != "": return item.package else: return self.package @@ -167,7 +164,10 @@ def write_pages(self): section_path = location / self.out_index self.write_page_if_not_exists(section_path, section_text) - is_flat = section.options and section.options.children == layout.ChoicesChildren.flat + is_flat = ( + section.options + and section.options.children == layout.ChoicesChildren.flat + ) for page in section.contents: if isinstance(page, layout.Page): @@ -186,24 +186,32 @@ def write_pages(self): raise NotImplementedError(f"Unsupported section item: {type(page)}") if len(self.page_map.keys()) > 0: - _log.warning(f'Extra pages: {self.page_map.keys()}') - _log.error(f'Linking between pages may not work properly. Fix the issue and try again') + _log.warning(f"Extra pages: {self.page_map.keys()}") + _log.error( + f"Linking between pages may not work properly. Fix the issue and try again" + ) if len(self.item_map.keys()) > 0: - _log.warning(f'Extra items: {self.item_map.keys()}') - _log.error(f'Linking between pages may not work properly. Fix the issue and try again') + _log.warning(f"Extra items: {self.item_map.keys()}") + _log.error( + f"Linking between pages may not work properly. Fix the issue and try again" + ) def update_page_items(self, page: layout.Page, location: Path, is_flat: bool): for doc in page.contents: if isinstance(doc, layout.Doc): - page_path = f'{location}/index.html' if is_flat else f'{location}/{page.path}.html' + page_path = ( + f"{location}/index.html" + if is_flat + else f"{location}/{page.path}.html" + ) self.update_items(doc, page_path) else: raise NotImplementedError(f"Unsupported page item: {type(doc)}") def update_items(self, doc: layout.Doc, page_path: str): name = doc.obj.path - uri = f'{page_path}#{doc.anchor}' + uri = f"{page_path}#{doc.anchor}" # item corresponding to the specified path ---- # e.g. this might be a top-level import @@ -213,7 +221,7 @@ def update_items(self, doc: layout.Doc, page_path: str): del self.item_map[name] else: item = layout.Item(uri=uri, name=name, obj=doc.obj, dispname=None) - _log.warning(f'Missing item, adding it: {item}') + _log.warning(f"Missing item, adding it: {item}") self.items.append(item) canonical_path = doc.obj.canonical_path @@ -225,8 +233,10 @@ def update_items(self, doc: layout.Doc, page_path: str): item.uri = uri del self.item_map[canonical_path] else: - item = layout.Item(uri=uri, name=canonical_path, obj=doc.obj, dispname=name) - _log.warning(f'Missing item, adding it: {item}') + item = layout.Item( + uri=uri, name=canonical_path, obj=doc.obj, dispname=name + ) + _log.warning(f"Missing item, adding it: {item}") self.items.append(item) # recurse in 😊 diff --git a/python/docs/_scripts/renderer.py b/python/docs/_scripts/renderer.py index 2298ece9a..5d4be75af 100644 --- a/python/docs/_scripts/renderer.py +++ b/python/docs/_scripts/renderer.py @@ -1,15 +1,15 @@ from __future__ import annotations -import quartodoc.ast as qast +from typing import Optional, Union -from griffe.docstrings import dataclasses as ds +import quartodoc.ast as qast from griffe import dataclasses as dc -from tabulate import tabulate +from griffe.docstrings import dataclasses as ds from plum import dispatch -from typing import Union, Optional from quartodoc import layout - from summarizer import Summarizer +from tabulate import tabulate + try: # Name and Expression were moved to expressions in v0.28 @@ -49,7 +49,7 @@ def sanitize(val: str, allow_markdown=False): return res -class Renderer(): +class Renderer: """Render docstrings to markdown.""" summarizer = Summarizer() @@ -61,7 +61,7 @@ def _get_display_name(self, el: "dc.Alias | dc.Object"): display_name = f"**{prefix}.**[**{name}**]{{.red}}" if isinstance(el, dc.Object): - if 'staticmethod' in el.labels: + if "staticmethod" in el.labels: display_name = "***static*** " + display_name text = [display_name] @@ -78,23 +78,25 @@ def _fetch_method_parameters(self, el: dc.Function): return el.parameters - def _render_definition_list(self, title: str, items: [str], title_class: Optional[str] = None) -> str: + def _render_definition_list( + self, title: str, items: [str], title_class: Optional[str] = None + ) -> str: rows = [title] for item in items: if len(rows) == 1: - rows.append(f'~ {item}') + rows.append(f"~ {item}") else: - rows.append(f' {item}') + rows.append(f" {item}") if title_class: - rows.insert(0, f':::{{.{title_class}}}') - rows.append(':::') + rows.insert(0, f":::{{.{title_class}}}") + rows.append(":::") return "\n" + "\n".join(rows) def _render_header(self, title: str, order: Optional[int] = None) -> str: text = ["---"] - text.append(f'title: {title}') + text.append(f"title: {title}") if order: - text.append(f'order: {order}') + text.append(f"order: {order}") text.append("---") return "\n".join(text) @@ -190,7 +192,7 @@ def render(self, el: layout.Page, is_flat: bool = False): if el.summary: if el.summary.name: if is_flat: - rows.append(f'## {el.summary.name}') + rows.append(f"## {el.summary.name}") else: rows.append(self._render_header(el.summary.name)) if el.summary.desc: @@ -206,7 +208,9 @@ def render(self, el: layout.Doc): raise NotImplementedError(f"Unsupported Doc type: {type(el)}") @dispatch - def render(self, el: Union[layout.DocClass, layout.DocModule], is_flat: bool = False) -> str: + def render( + self, el: Union[layout.DocClass, layout.DocModule], is_flat: bool = False + ) -> str: title = "" if is_flat else self._render_header(el.name) sig = self.signature(el) @@ -219,7 +223,8 @@ def render(self, el: Union[layout.DocClass, layout.DocModule], is_flat: bool = F if raw_attrs and not _has_attr_section(el.obj.docstring): attr_rows = map(self.render, raw_attrs) attr_text = self._render_definition_list( - "Attributes:", attr_rows, title_class="highlight") + "Attributes:", attr_rows, title_class="highlight" + ) body_rows.extend(attr_text.split("\n")) # add classes @@ -358,15 +363,17 @@ def render(self, el: ds.DocstringSectionParameters): for param in el.value: name = sanitize(param.name) anno = self.render_annotation(param.annotation) - default = f', default: {escape(param.default)}' if param.default else "" + default = f", default: {escape(param.default)}" if param.default else "" - rows.append(f'{prefix}**{name}** ({anno}{default})') + rows.append(f"{prefix}**{name}** ({anno}{default})") rows.append("") for row in param.description.split("\n"): - rows.append(f'{follow}{row}') + rows.append(f"{follow}{row}") rows.append("") - return self._render_definition_list("Parameters:", rows, title_class="highlight") + return self._render_definition_list( + "Parameters:", rows, title_class="highlight" + ) # attributes ---- @@ -380,13 +387,15 @@ def render(self, el: ds.DocstringSectionAttributes): for attr in el.value: name = sanitize(attr.name) anno = self.render_annotation(attr.annotation) - rows.append(f'{prefix}**{name}** ({anno})') + rows.append(f"{prefix}**{name}** ({anno})") rows.append("") for row in attr.description.split("\n"): - rows.append(f'{follow}{row}') + rows.append(f"{follow}{row}") rows.append("") - return self._render_definition_list("Attributes:", rows, title_class="highlight") + return self._render_definition_list( + "Attributes:", rows, title_class="highlight" + ) # examples ---- @@ -419,7 +428,7 @@ def render(self, el: ds.DocstringSectionReturns): title = prefix name = sanitize(item.name) if name: - title += f'**{name}**' + title += f"**{name}**" return_type = self.render_annotation(item.annotation) if return_type: @@ -431,7 +440,7 @@ def render(self, el: ds.DocstringSectionReturns): if item.description: rows.append("") for row in item.description.split("\n"): - rows.append(f'{follow}{row}') + rows.append(f"{follow}{row}") rows.append("") return self._render_definition_list("Returns:", rows, title_class="highlight") @@ -446,10 +455,10 @@ def render(self, el: ds.DocstringSectionRaises): for item in el.value: # name = sanitize(item.name) anno = self.render_annotation(item.annotation) - rows.append(f'{prefix}{anno}') + rows.append(f"{prefix}{anno}") rows.append("") for row in item.description.split("\n"): - rows.append(f'{follow}{row}') + rows.append(f"{follow}{row}") rows.append("") return self._render_definition_list("Raises:", rows, title_class="highlight") @@ -465,7 +474,7 @@ def render(self, el: ds.DocstringSectionAdmonition) -> str: rows.append(f'::: {{.callout-tip title="{el.title}"}}') rows.append(el.value.description) - rows.append(':::') + rows.append(":::") return "\n".join(rows) diff --git a/python/docs/_scripts/summarizer.py b/python/docs/_scripts/summarizer.py index cf643dbd4..e1c44b179 100644 --- a/python/docs/_scripts/summarizer.py +++ b/python/docs/_scripts/summarizer.py @@ -1,13 +1,14 @@ from __future__ import annotations -from griffe.docstrings import dataclasses as ds +from typing import Optional, Union + from griffe import dataclasses as dc +from griffe.docstrings import dataclasses as ds from plum import dispatch -from typing import Union, Optional from quartodoc import layout -class Summarizer(): +class Summarizer: """Summarize docstrings to markdown.""" @staticmethod diff --git a/python/docs/examples/bluesky.py b/python/docs/examples/bluesky.py index 447b2dd8a..906a1c0aa 100644 --- a/python/docs/examples/bluesky.py +++ b/python/docs/examples/bluesky.py @@ -79,13 +79,15 @@ async def receive_at(message) -> None: # The parsing produces a hot mess of incompatible types, so we build # a dict from scratch to simplify. - posts.add_rows({ - "record": dict(new_post["record"]), - "uri": new_post["uri"], - "cid": new_post["cid"], - "author": new_post["author"], - "ts": time.time(), - }) + posts.add_rows( + { + "record": dict(new_post["record"]), + "uri": new_post["uri"], + "cid": new_post["cid"], + "author": new_post["author"], + "ts": time.time(), + } + ) # Handler for values emitted by Kaskada. async def receive_outputs(): diff --git a/python/pysrc/kaskada/_timestream.py b/python/pysrc/kaskada/_timestream.py index 9ef805648..3fed6947e 100644 --- a/python/pysrc/kaskada/_timestream.py +++ b/python/pysrc/kaskada/_timestream.py @@ -1063,7 +1063,9 @@ def least(self, rhs: Arg) -> Timestream: def preview( self, limit: int = 10, - results: Optional[Union[kaskada.results.History, kaskada.results.Snapshot]] = None, + results: Optional[ + Union[kaskada.results.History, kaskada.results.Snapshot] + ] = None, ) -> pd.DataFrame: """Preview the points in this TimeStream as a DataFrame. @@ -1075,7 +1077,9 @@ def preview( def to_pandas( self, - results: Optional[Union[kaskada.results.History, kaskada.results.Snapshot]] = None, + results: Optional[ + Union[kaskada.results.History, kaskada.results.Snapshot] + ] = None, *, row_limit: Optional[int] = None, ) -> pd.DataFrame: @@ -1086,9 +1090,10 @@ def to_pandas( row_limit: The maximum number of rows to return. Defaults to `None` for no limit. See Also: - - [](`~kaskada.Timestream.preview`): For quick peeks at the contents of a TimeStream during development. - - [](`~kaskada.Timestream.write`): For writing results to supported destinations without passing through - Pandas. + - [](`~kaskada.Timestream.preview`): For quick peeks at the contents of a TimeStream during + development. + - [](`~kaskada.Timestream.write`): For writing results to supported destinations without + passing through Pandas. - [](`~kaskada.Timestream.run_iter`): For non-blocking (iterator or async iterator) execution. """ execution = self._execute(results, row_limit=row_limit) @@ -1101,7 +1106,9 @@ def write( self, destination: kaskada.destinations.Destination, mode: Literal["once", "live"] = "once", - results: Optional[Union[kaskada.results.History, kaskada.results.Snapshot]] = None, + results: Optional[ + Union[kaskada.results.History, kaskada.results.Snapshot] + ] = None, ) -> Execution: """Execute the TimeStream writing to the given destination. @@ -1125,7 +1132,9 @@ def run_iter( kind: Literal["pandas"] = "pandas", *, mode: Literal["once", "live"] = "once", - results: Optional[Union[kaskada.results.History, kaskada.results.Snapshot]] = None, + results: Optional[ + Union[kaskada.results.History, kaskada.results.Snapshot] + ] = None, row_limit: Optional[int] = None, max_batch_size: Optional[int] = None, ) -> ResultIterator[pd.DataFrame]: @@ -1137,7 +1146,9 @@ def run_iter( kind: Literal["pyarrow"], *, mode: Literal["once", "live"] = "once", - results: Optional[Union[kaskada.results.History, kaskada.results.Snapshot]] = None, + results: Optional[ + Union[kaskada.results.History, kaskada.results.Snapshot] + ] = None, row_limit: Optional[int] = None, max_batch_size: Optional[int] = None, ) -> ResultIterator[pa.RecordBatch]: @@ -1149,7 +1160,9 @@ def run_iter( kind: Literal["row"], *, mode: Literal["once", "live"] = "once", - results: Optional[Union[kaskada.results.History, kaskada.results.Snapshot]] = None, + results: Optional[ + Union[kaskada.results.History, kaskada.results.Snapshot] + ] = None, row_limit: Optional[int] = None, max_batch_size: Optional[int] = None, ) -> ResultIterator[dict]: @@ -1160,7 +1173,9 @@ def run_iter( kind: Literal["pandas", "pyarrow", "row"] = "pandas", *, mode: Literal["once", "live"] = "once", - results: Optional[Union[kaskada.results.History, kaskada.results.Snapshot]] = None, + results: Optional[ + Union[kaskada.results.History, kaskada.results.Snapshot] + ] = None, row_limit: Optional[int] = None, max_batch_size: Optional[int] = None, ) -> Union[ @@ -1203,7 +1218,9 @@ def run_iter( def explain( self, kind: Literal["initial_dfg", "final_dfg", "final_plan"] = "final_plan", - results: Optional[Union[kaskada.results.History, kaskada.results.Snapshot]] = None, + results: Optional[ + Union[kaskada.results.History, kaskada.results.Snapshot] + ] = None, mode: Literal["once", "live"] = "once", ) -> "graphviz.Source": """Return an explanation of this Timestream will be executed.