Merge pull request #138 from venthur/ruff

switch from flake8 to ruff

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [unreleased] -- XXXXXXX
+
+* switched from flake8 to ruff
+* added missing docstrings
+
 ## [2.1.0] -- 2023-08-27
 
 * default theme: `img` have now `max-width: 100%` by default to avoid very

Makefile

@@ -33,7 +33,7 @@ mypy: $(VENV)
 
 .PHONY: lint
 lint: $(VENV)
-	$(BIN)/flake8
+	$(BIN)/ruff check .
 
 .PHONY: build
 build: $(VENV)

blag/blag.py

@@ -1,8 +1,6 @@
 #!/usr/bin/env python3
 
-"""blag's core methods.
-
-"""
+"""blag's core methods."""
 
 # remove when we don't support py38 anymore
 from __future__ import annotations
@@ -32,7 +30,7 @@
 
 
 def main(arguments: list[str] | None = None) -> None:
-    """Main entrypoint for the CLI.
+    """Run the CLI.
 
     This method parses the CLI arguments and executes the respective
     commands.
@@ -328,7 +326,7 @@ def process_markdown(
     for src, dst in convertibles:
         logger.debug(f"Processing {src}")
 
-        with open(f"{input_dir}/{src}", "r") as fh:
+        with open(f"{input_dir}/{src}") as fh:
             body = fh.read()
 
         content, meta = convert_markdown(md, body)

blag/markdown.py

@@ -94,9 +94,10 @@ def convert_markdown(
 
 
 class MarkdownLinkTreeprocessor(Treeprocessor):
-    """Converts relative links to .md files to .html"""
+    """Converts relative links to .md files to .html."""
 
     def run(self, root: Element) -> Element:
+        """Process the ElementTree."""
         for element in root.iter():
             if element.tag == "a":
                 url = element.get("href")
@@ -109,6 +110,7 @@ def run(self, root: Element) -> Element:
         return root
 
     def convert(self, url: str) -> str:
+        """Convert relative .md-links to .html-links."""
         scheme, netloc, path, query, fragment = urlsplit(url)
         logger.debug(
             f"{url}: {scheme=} {netloc=} {path=} {query=} {fragment=}"
@@ -126,6 +128,7 @@ class MarkdownLinkExtension(Extension):
     """markdown.extension that converts relative .md- to .html-links."""
 
     def extendMarkdown(self, md: Markdown) -> None:
+        """Register the MarkdownLinkTreeprocessor."""
         md.treeprocessors.register(
             MarkdownLinkTreeprocessor(md),
             "mdlink",

blag/quickstart.py

@@ -1,6 +1,4 @@
-"""Helper methods for blag's quickstart command.
-
-"""
+"""Helper methods for blag's quickstart command."""
 
 # remove when we don't support py38 anymore
 from __future__ import annotations

blag/version.py

@@ -1 +1,3 @@
+"""Version information for the blag package."""
+
 __VERSION__ = "2.1.0"

pyproject.toml

@@ -36,7 +36,7 @@ dev = [
     "wheel",
     "pytest",
     "pytest-cov",
-    "flake8",
+    "ruff",
     "mypy",
     "types-markdown",
 ]
@@ -61,6 +61,21 @@ addopts = """
     --cov-report=term-missing:skip-covered
 """
 
+[tool.ruff]
+select = [
+    "F",        # pyflakes
+    "E", "W",   # pycodestyle
+    "C90",      # mccabe
+    "I",        # isort
+    "D",        # pydocstyle
+    "UP"        # pyupgrade
+]
+line-length = 79
+target-version = "py38"
+
+[tool.ruff.pydocstyle]
+convention = "numpy"
+
 [tool.mypy]
 files = "blag,tests"
 strict = true

requirements-dev.txt

@@ -6,6 +6,6 @@ twine==4.0.2
 wheel==0.41.2
 pytest==7.4.2
 pytest-cov==4.1.0
-flake8==6.1.0
+ruff==0.0.290
 mypy==1.5.1
 types-markdown==3.4.2.10

tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for blag."""

tests/conftest.py

@@ -1,3 +1,6 @@
+"""Pytest fixtures."""
+
+
 # remove when we don't support py38 anymore
 from __future__ import annotations
 
@@ -14,6 +17,7 @@
 
 @pytest.fixture
 def environment(cleandir: str) -> Iterator[Environment]:
+    """Create a Jinja2 environment."""
     site = {
         "base_url": "site base_url",
         "title": "site title",
@@ -26,31 +30,37 @@ def environment(cleandir: str) -> Iterator[Environment]:
 
 @pytest.fixture
 def page_template(environment: Environment) -> Iterator[Template]:
+    """Create a Jinja2 page-template."""
     yield environment.get_template("page.html")
 
 
 @pytest.fixture
 def article_template(environment: Environment) -> Iterator[Template]:
+    """Create a Jinja2 article-template."""
     yield environment.get_template("article.html")
 
 
 @pytest.fixture
 def index_template(environment: Environment) -> Iterator[Template]:
+    """Create a Jinja2 index-template."""
     yield environment.get_template("index.html")
 
 
 @pytest.fixture
 def archive_template(environment: Environment) -> Iterator[Template]:
+    """Create a Jinja2 archive-template."""
     yield environment.get_template("archive.html")
 
 
 @pytest.fixture
 def tags_template(environment: Environment) -> Iterator[Template]:
+    """Create a Jinja2 tags-template."""
     yield environment.get_template("tags.html")
 
 
 @pytest.fixture
 def tag_template(environment: Environment) -> Iterator[Template]:
+    """Create a Jinja2 tag-template."""
     yield environment.get_template("tag.html")
 
 
@@ -80,6 +90,7 @@ def cleandir() -> Iterator[str]:
 
 @pytest.fixture
 def args(cleandir: Callable[[], Iterator[str]]) -> Iterator[Namespace]:
+    """Create a Namespace with default arguments."""
     args = Namespace(
         input_dir="content",
         output_dir="build",

tests/test_blag.py

@@ -1,3 +1,6 @@
+"""Test blag."""
+
+
 # remove when we don't support py38 anymore
 from __future__ import annotations
 
@@ -15,12 +18,14 @@
 
 
 def test_generate_feed(cleandir: str) -> None:
+    """Test generate_feed."""
     articles: list[tuple[str, dict[str, Any]]] = []
     blag.generate_feed(articles, "build", " ", " ", " ", " ")
     assert os.path.exists("build/atom.xml")
 
 
 def test_feed(cleandir: str) -> None:
+    """Test feed."""
     articles: list[tuple[str, dict[str, Any]]] = [
         (
             "dest1.html",
@@ -73,6 +78,7 @@ def test_feed(cleandir: str) -> None:
 
 
 def test_generate_feed_with_description(cleandir: str) -> None:
+    """Test generate_feed with description."""
     # if a description is provided, it will be used as the summary in
     # the feed, otherwise we simply use the title of the article
     articles: list[tuple[str, dict[str, Any]]] = [
@@ -98,6 +104,7 @@ def test_generate_feed_with_description(cleandir: str) -> None:
 
 
 def test_parse_args_build() -> None:
+    """Test parse_args with build."""
     # test default args
     args = blag.parse_args(["build"])
     assert args.input_dir == "content"
@@ -131,6 +138,7 @@ def test_parse_args_build() -> None:
 
 
 def test_get_config() -> None:
+    """Test get_config."""
     config = """
 [main]
 base_url = https://example.com/
@@ -180,6 +188,7 @@ def test_get_config() -> None:
 
 
 def test_environment_factory(cleandir: str) -> None:
+    """Test environment_factory."""
     globals_: dict[str, object] = {"foo": "bar", "test": "me"}
     env = blag.environment_factory("templates", globals_=globals_)
     assert env.globals["foo"] == "bar"
@@ -191,6 +200,7 @@ def test_process_markdown(
     page_template: Template,
     article_template: Template,
 ) -> None:
+    """Test process_markdown."""
     page1 = """\
 title: some page
 
@@ -240,6 +250,7 @@ def test_process_markdown(
 
 
 def test_build(args: Namespace) -> None:
+    """Test build."""
     page1 = """\
 title: some page
 
@@ -313,16 +324,19 @@ def test_build(args: Namespace) -> None:
     ],
 )
 def test_missing_template_raises(template: str, args: Namespace) -> None:
+    """Test that missing templates raise SystemExit."""
     os.remove(f"templates/{template}")
     with pytest.raises(SystemExit):
         blag.build(args)
 
 
 def test_main(cleandir: str) -> None:
+    """Test main."""
     blag.main(["build"])
 
 
 def test_cli_version(capsys: CaptureFixture[str]) -> None:
+    """Test --version."""
     with pytest.raises(SystemExit) as ex:
         blag.main(["--version"])
     # normal system exit
@@ -333,6 +347,7 @@ def test_cli_version(capsys: CaptureFixture[str]) -> None:
 
 
 def test_cli_verbose(cleandir: str, caplog: LogCaptureFixture) -> None:
+    """Test --verbose."""
     blag.main(["build"])
     assert "DEBUG" not in caplog.text
 

tests/test_devserver.py

@@ -1,3 +1,6 @@
+"""Tests for the devserver module."""
+
+
 # remove when we don't support py38 anymore
 from __future__ import annotations
 
@@ -11,6 +14,7 @@
 
 
 def test_get_last_modified(cleandir: str) -> None:
+    """Test get_last_modified."""
     # take initial time
     t1 = devserver.get_last_modified(["content"])
 
@@ -29,6 +33,7 @@ def test_get_last_modified(cleandir: str) -> None:
 
 
 def test_autoreload_builds_immediately(args: Namespace) -> None:
+    """Test autoreload builds immediately."""
     # create a dummy file that can be build
     with open("content/test.md", "w") as fh:
         fh.write("boo")
@@ -54,6 +59,7 @@ def test_autoreload_builds_immediately(args: Namespace) -> None:
     "ignore::pytest.PytestUnhandledThreadExceptionWarning"
 )
 def test_autoreload(args: Namespace) -> None:
+    """Test autoreload."""
     t = threading.Thread(
         target=devserver.autoreload,
         args=(args,),

tests/test_markdown.py

@@ -1,3 +1,6 @@
+"""Test markdown module."""
+
+
 # remove when we don't support py38 anymore
 from __future__ import annotations
 
@@ -34,6 +37,7 @@
     ],
 )
 def test_convert_markdown_links(input_: str, expected: str) -> None:
+    """Test convert_markdown."""
     md = markdown_factory()
     html, _ = convert_markdown(md, input_)
     assert expected in html
@@ -51,6 +55,7 @@ def test_convert_markdown_links(input_: str, expected: str) -> None:
     ],
 )
 def test_dont_convert_normal_links(input_: str, expected: str) -> None:
+    """Test convert_markdown doesn't convert normal links."""
     md = markdown_factory()
     html, _ = convert_markdown(md, input_)
     assert expected in html
@@ -70,17 +75,20 @@ def test_dont_convert_normal_links(input_: str, expected: str) -> None:
     ],
 )
 def test_convert_metadata(input_: str, expected: dict[str, Any]) -> None:
+    """Test convert_markdown converts metadata correctly."""
     md = markdown_factory()
     _, meta = convert_markdown(md, input_)
     assert expected == meta
 
 
 def test_markdown_factory() -> None:
+    """Test markdown_factory."""
     md = markdown_factory()
     assert isinstance(md, markdown.Markdown)
 
 
 def test_smarty() -> None:
+    """Test smarty."""
     md = markdown_factory()
 
     md1 = """
@@ -95,6 +103,7 @@ def test_smarty() -> None:
 
 
 def test_smarty_code() -> None:
+    """Test smarty doesn't touch code."""
     md = markdown_factory()
 
     md1 = """