feat(python): Python Updates to better support docs building

.config/dictionaries/project.dic

@@ -1,4 +1,5 @@
 aarch
+armv
 bindgen
 binstall
 bkioshn
@@ -74,6 +75,7 @@ libsqlite
 libxkbcommon
 libxshmfence
 lintfix
+manylinux
 markdownlint
 mattn
 mdlint
@@ -90,6 +92,7 @@ nilnil
 nixos
 nixpkgs
 onsi
+outputjson
 penwidth
 pkeyopt
 pkgconf
@@ -99,6 +102,7 @@ pubout
 pubspec
 pymdownx
 pypackages
+pyrightconfig
 PYTHONDONTWRITEBYTECODE
 pytype
 rankdir
@@ -135,6 +139,7 @@ voteplan
 wasi
 wasip
 wasmtime
+watchmedo
 webkitallowfullscreen
 WORKDIR
 xerrors

.gitignore

@@ -26,6 +26,7 @@ Cargo.lock
 
 # Python junk
 **/*.pyc
+**/typings
 
 
 ### Linux ###

cspell.json

@@ -40,7 +40,7 @@
     "ignorePaths": [
         ".config/dictionaries",
         ".github",
-        "earthly/docs/poetry.lock",
+        "earthly/docs/uv.lock",
         "actions/*/dist",
         "cli/go.sum",
         "cli/go.mod",

docs/Earthfile

@@ -21,7 +21,7 @@ src:
     COPY --dir postgresql-ci+build/docs src/appendix/examples/built_docs/postgresql
 
 # Build the docs here.
-docs:
+build-docs:
     FROM +src
 
     DO docs-ci+BUILD

docs/src/guides/languages/python.md

@@ -55,14 +55,14 @@ builder:
 ```
 
 The first target `builder` is responsible to prepare an already configured Python environment,
-instal all needed tools and dependencies.
-Every Python project must be a [poetry](https://python-poetry.org) based project,
-so it is mandatory to have `pyproject.toml` and `poetry.lock` files in the root dir of the project.
+install all needed tools and dependencies.
+Every Python project must be a [uv](https://docs.astral.sh/uv/) based project,
+so it is mandatory to have `pyproject.toml` and `uv.lock` files in the root dir of the project.
 
-The fist step of the `builder` target is prepare a Python environment
-with poetry via `+python-base` target.
+The first step of the `builder` target is to prepare a Python environment
+with `uv` via `+python-base` target.
 Next step is to copy source code of the project and finally finalize the build
-with some poetry project setup which is done with `+BUILDER` Function.
+with some `uv` project setup which is done with `+BUILDER` Function.
 
 ### Running checks
 
@@ -74,12 +74,12 @@ with some poetry project setup which is done with `+BUILDER` Function.
 test:
     FROM +builder
 
-    RUN poetry run pytest
+    RUN uv run pytest
 ```
 
 As the final step, after proper setup of the Python project we can run tests,
 to do so
-inherit from the already discussed `+builder` target and just run `poetry run pytest`
+inherit from the already discussed `+builder` target and just run `uv run pytest`
 or with any other way which are suitable for your project setup.
 And that's it!
 

earthly/cassandra/Earthfile

@@ -12,7 +12,7 @@ scylladb-base:
     RUN apt-get update && apt-get install -y python3 pipx
 
     RUN pipx ensurepath
-    RUN pipx install poetry
+    #RUN pipx install poetry
 
 # cql-to-d2 - converts cql files into d2 diagram entity files
 cql-to-d2:

earthly/docs/Earthfile

@@ -36,8 +36,8 @@ deps:
     # Install D2
     RUN curl -fsSL https://d2lang.com/install.sh | sh -s --
 
-    # Install poetry and our python dependencies.
-    DO python-ci+BUILDER --opts=--no-root
+    # Install uv and our python dependencies.
+    DO python-ci+BUILDER 
 
     # Copy our run scripts
     COPY --dir scripts/* /scripts/

earthly/docs/Readme.md

@@ -15,7 +15,7 @@ earthly -P +check
 If a new dependency is added to `pyproject.toml` ensure to run:
 
 ```sh
-poetry lock
+uv lock
 ```
 
 in the `earthly/docs` directory to update the locked dependencies.

earthly/docs/common/macros/__init__.py

@@ -1,13 +1,13 @@
 """Doc Macros Init."""
 
-from typing import Any
+from mkdocs_macros.plugin import MacrosPlugin
 
 from .include import inc_file
 
 
-def define_env(env: Any) -> None:  # noqa: ANN401
+def define_env(env: MacrosPlugin) -> None:
     """Hooks for defining variables, macros and filters."""
 
-    @env.macro
-    def include_file(filename: str, *, start_line: int = 0, end_line: int | None = None, indent: int = 0) -> str:
+    @env.macro # pyright: ignore[reportUnknownMemberType]
+    def include_file(filename: str, *, start_line: int = 0, end_line: int | None = None, indent: int = 0) -> str:  # pyright: ignore[reportUnusedFunction]
         return inc_file(env, filename, start_line=start_line, end_line=end_line, indent=indent)

earthly/docs/common/macros/include.py

@@ -3,9 +3,11 @@
 import re
 from pathlib import Path
 
+from mkdocs_macros.plugin import MacrosPlugin
+
 
 def inc_file(
-    env: any,
+    env: MacrosPlugin,
     filename: str,
     *,
     start_line: int = 0,
@@ -24,7 +26,7 @@ def inc_file(
     indent = number of spaces to indent every line but the first.
     """
     try:
-        if filename.startswith("."):
+        if filename.startswith(".") and env.page.file.src_dir is not None:
             this_file = Path(env.page.file.src_dir) / env.page.file.src_uri
             this_dir = this_file.parent
             relative_filename = this_dir / filename

earthly/docs/dev/local.py

@@ -6,6 +6,7 @@
 import subprocess
 import sys
 import time
+import urllib.error
 import urllib.request
 import webbrowser
 from dataclasses import dataclass, field
@@ -27,7 +28,7 @@ class ImageNotFound(Exception):  # noqa: N818
     """Image Not Found."""
 
 
-def run_command(command: str) -> None:
+def run_command(command: str | list[str]) -> None:
     """Run a command and print its output.
 
     Args:
@@ -48,10 +49,13 @@ def run_command(command: str) -> None:
         universal_newlines=True,
     )
 
-    for line in iter(process.stdout.readline, ""):
-        print(line, end="")
+    if process.stdout is not None:
+        for line in iter(process.stdout.readline, ""):
+            print(line, end="")
 
-    process.stdout.close()
+        process.stdout.close()
+    else:
+        print("stdout can not be read?")
 
     rc = process.wait()
 
@@ -175,8 +179,11 @@ def print_logs(self) -> None:
         """Print Logs."""
         cmd = f"docker logs --since {self.last_log_time} {self.container_id}"
         output = subprocess.Popen(cmd, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)  # noqa: S602
-        for line in output.stdout:
-            print(line.decode().strip())
+        if output.stdout is not None:
+            for line in output.stdout:
+                print(line.decode().strip())
+        else:
+            print("stdout can not be read?")
         self.last_log_time = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())