diff --git a/CODING_GUIDELINES.md b/CODING_GUIDELINES.md index 7874f60..3e7fabb 100644 --- a/CODING_GUIDELINES.md +++ b/CODING_GUIDELINES.md @@ -12,12 +12,15 @@ We deviate from the [Google Python Style Guide][google-style-guide] only in the - According to subsection [_2.19 Power Features_](https://google.github.io/styleguide/pyguide.html#219-power-features), direct use of _power features_ (e.g. custom metaclasses, import hacks, reflection) should be avoided, but standard library classes that internally use these power features are accepted. Following the same spirit, we allow the use of power features in infrastructure code with similar functionality and scope as the Python standard library. +- For readability purposes, when a docstring contains more than the required summary line, we prefer indenting the first line at the same cursor position as the first opening quote, although this is not explicitly considered in the doctring conventions described in subsection [_3.8.1 Docstrings_](https://google.github.io/styleguide/pyguide.html#381-docstrings). Example: + ```python # single line docstring """A one-line summary of the module or program, terminated by a period.""" # multi-line docstring - """ A one-line summary of the module or program, terminated by a period. + """ + A one-line summary of the module or program, terminated by a period. Leave one blank line. The rest of this docstring should contain an overall description of the module or program. @@ -26,7 +29,7 @@ We deviate from the [Google Python Style Guide][google-style-guide] only in the - According to subsection [_3.19.12 Imports For Typing_](https://google.github.io/styleguide/pyguide.html#31912-imports-for-typing), symbols from `typing` and `collections.abc` modules used in type annotations _"can be imported directly to keep common annotations concise and match standard typing practices"_. Following the same spirit, we allow symbols to be imported directly from third-party or internal modules when they only contain a collection of frequently used typying definitions. -### Common questions +### Python usage recommendations - `pass` vs `...` (`Ellipsis`) @@ -141,9 +144,7 @@ and, if needed, a brief comment for future reference: ```python ... -return ( - undeclared_symbol # noqa: F821 [undefined-name] on purpose to trigger black-magic -) +return undeclared # noqa: F821 [undefined-name] on purpose to trigger black-magic ``` ## Testing diff --git a/README.md b/README.md index fe91ae6..86e7f31 100644 --- a/README.md +++ b/README.md @@ -19,10 +19,6 @@ The DaCe project aims to build new representations for programs and algorithms, - - - - [actions-badge]: https://github.com/GridTools/JaCe/workflows/CI/badge.svg [actions-link]: https://github.com/GridTools/JaCe/actions [conda-badge]: https://img.shields.io/conda/vn/conda-forge/JaCe diff --git a/noxfile.py b/noxfile.py index 2154c16..0f64884 100644 --- a/noxfile.py +++ b/noxfile.py @@ -16,28 +16,21 @@ @nox.session def lint(session: nox.Session) -> None: - """ - Run the linter. - """ + """Run the linter.""" session.install("pre-commit") session.run("pre-commit", "run", "--all-files", "--show-diff-on-failure", *session.posargs) @nox.session def tests(session: nox.Session) -> None: - """ - Run the unit and regular tests. - """ + """Run the unit and regular tests.""" session.install(".[test]") session.run("pytest", *session.posargs) @nox.session(reuse_venv=True) def docs(session: nox.Session) -> None: - """ - Build the docs. Pass "--serve" to serve. Pass "-b linkcheck" to check links. - """ - + """Build the docs. Pass "--serve" to serve. Pass "-b linkcheck" to check links.""" parser = argparse.ArgumentParser() parser.add_argument("--serve", action="store_true", help="Serve after building") parser.add_argument("-b", dest="builder", default="html", help="Build target (default: html)") @@ -72,10 +65,7 @@ def docs(session: nox.Session) -> None: @nox.session def build_api_docs(session: nox.Session) -> None: - """ - Build (regenerate) API docs. - """ - + """Build (regenerate) API docs.""" session.install("sphinx") session.chdir("docs") session.run( @@ -85,10 +75,7 @@ def build_api_docs(session: nox.Session) -> None: @nox.session def build(session: nox.Session) -> None: - """ - Build an SDist and wheel. - """ - + """Build an SDist and wheel.""" build_path = DIR.joinpath("build") if build_path.exists(): shutil.rmtree(build_path) diff --git a/src/jace/__init__.py b/src/jace/__init__.py index de111ec..11c5d2a 100644 --- a/src/jace/__init__.py +++ b/src/jace/__init__.py @@ -5,7 +5,7 @@ # # SPDX-License-Identifier: BSD-3-Clause -"""JaCe - JAX Just-In-Time compilation using DaCe.""" +"""JaCe: JAX jit using DaCe (Data Centric Parallel Programming).""" from __future__ import annotations