feat(docs): Python guide (#99)

* add blob python example project

* add test

* fix

* add Python guide introduction

* update

* update

* fix

* fix docs build

* fix builder

* fix spell check

* add poetry.lock files as required

docs/src/guides/languages/python.md

@@ -9,4 +9,89 @@ tags:
 # :simple-python: Python
 <!-- markdownlint-enable single-h1 -->
 
-[TODO](https://github.com/input-output-hk/catalyst-ci/issues/79)
+## Introduction
+
+<!-- markdownlint-disable max-one-sentence-per-line -->
+!!! Tip
+    If you're just looking for a complete example,
+    [click here](https://github.com/input-output-hk/catalyst-ci/blob/master/examples/python/Earthfile).
+    This guide will provide detailed instructions for how the example was built.
+<!-- markdownlint-enable max-one-sentence-per-line -->
+
+This guide will get you started with using the Catalyst CI to work with Python based projects.
+
+To begin, clone the Catalyst CI repository:
+
+```bash
+git clone https://github.com/input-output-hk/catalyst-ci.git
+```
+
+Navigate to `examples/python` to find a basic Python project, with the `Earthfile` in it.
+This is the `Earthfile` we will be building in this guide.
+You can choose to either delete the file and start from scratch,
+or read the guide and follow along in the file.
+
+## Building the Earthfile
+
+<!-- markdownlint-disable max-one-sentence-per-line -->
+!!! Note
+    The below sections will walk through building our `Earthfile` step-by-step.
+    In each section, only the fragments of the `Earthfile` relative to that section are displayed.
+    This means that, as you go through each section, you should be cumulatively building the `Earthfile`.
+    If you get stuck at any point, you can always take a look at the
+    [example](https://github.com/input-output-hk/catalyst-ci/blob/master/examples/python/Earthfile).
+<!-- markdownlint-enable max-one-sentence-per-line -->
+
+### Prepare base builder
+
+```Earthfile
+VERSION 0.7
+
+builder:
+    FROM ./../../earthly/python+python-base
+
+    COPY --dir ./src .
+    DO ./../../earthly/python+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.
+
+The fist step of the `builder` target is prepare a Python environment
+with poetry 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` UDC target.
+
+### Running checks
+
+[TODO](https://github.com/input-output-hk/catalyst-ci/issues/98)
+
+### Test
+
+```Earthfile
+test:
+    FROM +builder
+
+    RUN poetry 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`
+or with any other way which are suitable for your project setup.
+And that's it!
+
+### Release and publish
+
+To prepare a release artifact and publish it to some external container registries
+please follow this [guide](./../../onboarding/index.md).
+The only things you need is too define `release` and `publish` Earthly targets
+with the proper configuration of the artifacts for your project.
+
+## Conclusion
+
+You can see the final `Earthfile` [here](https://github.com/input-output-hk/catalyst-ci/blob/master/examples/python/Earthfile)
+and any other files in the same directory.
+We have learnt how to maintain and setup Python project, as you can see it is pretty simple.

earthly/docs/Earthfile

@@ -3,7 +3,7 @@ VERSION 0.7
 # cspell: words libgcc freetype lcms openjpeg etag
 
 deps:
-    FROM python:3.12-alpine3.18
+    FROM ../python+python-base
     # Derived from official mkdocs-material docker container.
     # https://github.com/squidfunk/mkdocs-material/blob/master/Dockerfile
     # Due to docs being constructed not only from Doc source but Build artifacts,
@@ -33,7 +33,7 @@ deps:
         git       
 
     # Install poetry and our python dependencies.
-    DO ../python+POETRY_SETUP
+    DO ../python+BUILDER
 
     # Copy our run scripts
     COPY --dir scripts /scripts

earthly/python/Earthfile

@@ -1,15 +1,18 @@
 # Common Python UDCs and Builders.
 VERSION 0.7
-FROM python:3.11-bullseye
 
-# Common Poetry setup
-# Parameters:
-#   opts      : Options passed to the `poetry install` command.
-#   extra_file: An extra file to copy into the poetry path.
-POETRY_SETUP:
-    COMMAND
-    ARG opts
-    ARG extra_file
+# cspell: words libgcc
+
+python-base:
+    FROM python:3.12-alpine3.18
+
+    # Install extra packages we will need to support plugins.
+    RUN apk add --no-cache \    
+        curl \
+        libffi-dev \
+        gcc \
+        musl-dev \
+        libgcc
 
     # Poetry Installation directory.
     # Gives poetry and our poetry project a reliable location.
@@ -26,8 +29,15 @@ POETRY_SETUP:
     #   "Connection pool is full, discarding connection: pypi.org. Connection pool size: 10"
     RUN poetry config installer.max-workers 10
 
+# Common python builder setup.
+# Parameters:
+#   opts      : Options passed to the `poetry install` command.
+BUILDER:
+    COMMAND
+    ARG opts
+
     # Copy our dependencies.
-    COPY pyproject.toml poetry.lock $extra_file .
+    COPY pyproject.toml poetry.lock .
 
     # Install it all with poetry
     RUN poetry install $opts

examples/python/.gitignore

@@ -0,0 +1,2 @@
+### Python ###
+__pycache__/

examples/python/Earthfile

@@ -0,0 +1,12 @@
+VERSION 0.7
+
+builder:
+    FROM ./../../earthly/python+python-base
+
+    COPY --dir ./src .
+    DO ./../../earthly/python+BUILDER
+
+test:
+    FROM +builder
+
+    RUN poetry run pytest

examples/python/pyproject.toml

@@ -0,0 +1,13 @@
+[tool.poetry]
+name = "src"
+version = "0.1.0"
+description = "Python example project"
+authors = []
+
+[tool.poetry.dependencies]
+python = "^3.11"
+pytest = "^7.4.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

examples/python/src/sum.py

@@ -0,0 +1,2 @@
+def sum(a, b):
+    return a + b

examples/python/src/test_sum.py

@@ -0,0 +1,5 @@
+from src.sum import sum
+
+def test_sum():
+    assert sum(2, 4) == 6
+    assert sum(2, 4) != 5