Initialize repo and add simple memory tests

.github/workflows/run-memory-tests.yaml

@@ -0,0 +1,27 @@
+---
+# used for running memory checks through GitHub Actions for open observability
+name: run memory tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  run_memory_tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Setup poetry and poethepoet
+        run: |
+          python -m pip install poetry poethepoet
+      - name: Install poetry runner env
+        run: |
+          poetry install --with runner -v --no-interaction
+      - name: Run memory tests through Dagger pipeline
+        run: |
+          poetry poe run_all_tests

README.md

@@ -1,3 +1,62 @@
-# demo-python-memory-reference-accounting
+# Demonstrating Python Memory Allocator Reference Counting (and Related)
 
 Demonstrating Python memory allocator reference counting and debug.
+The goal of this repository is to help demonstrate Python memory allocation using source controlled code.
+Work for this project was originally inspired by [cytomining/CytoTable#75](https://github.com/cytomining/CytoTable/issues/75) which explores related topics.
+
+## Project outline
+
+```mermaid
+---
+title: Project Overview
+---
+flowchart LR
+
+pyproject["pyproject.toml"]
+poeworkflow["poethepoet\nworkflows"]
+dockerfile["Dockerfile"]
+subgraph test_container["test container"]
+    subgraph tests
+        test_env["Python environment\n(for tests)"]
+        test_modules["Test module(s)"]
+    end
+end
+subgraph runner
+    runner_env["Python environment\n(for runner)"]
+    runner_cli["Runner CLI\n(Python Fire)"]
+    pipeline["Container pipeline\n(through Dagger)"]
+end
+
+
+pyproject --> |defines| test_env
+pyproject --> |defines| runner_env
+
+test_env --> |runs| test_modules
+test_modules -.-> |display\nresults through| pipeline
+runner_env --> |enables| runner_cli
+runner_cli --> |runs| pipeline
+
+dockerfile -.-> |defines\ncontainer for| pipeline
+
+pipeline --> |executes| test_container
+
+pyproject --> poeworkflow
+poeworkflow -.-> |declarative\nworkflows for| runner
+```
+
+See above for a quick overview of project components and their relationship.
+[Poetry](https://python-poetry.org/docs/) is used to define Python environment dependencies within [dependency groups](https://python-poetry.org/docs/master/managing-dependencies/#dependency-groups) in a `pyproject.toml` file.
+Declarative [Poe the Poet tasks](https://poethepoet.natn.io/index.html) may also be found in the same `pyproject.toml` file to help define reproducible workflows.
+A "runner" command-line interface (CLI) is provided through [Python Fire](https://github.com/google/python-fire) to help enable the use of the container-based pipelines.
+Container-based pipelines are provided through [Dagger's Python SDK](https://docs.dagger.io/sdk/python/) to help isolate potential OS-specific distinctions for memory allocation work in Python.
+Testing workflows are designed to run "locally" within a developer's environment (for example, leveraging [pyenv](https://github.com/pyenv/pyenv), [poetry](https://python-poetry.org/docs/), and [Docker Desktop](https://www.docker.com/products/docker-desktop/)) or within [GitHub Actions images](https://github.com/actions/runner-images) (`dagger-io` installs the necessary dependencies).
+
+## Development
+
+The following are suggested steps to get started with development for this project.
+
+1. Install Python from [pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation)
+1. [Install Poetry](https://python-poetry.org/docs/#installation)
+1. [Install Poe the Poet](https://poethepoet.natn.io/installation.html)
+1. [Install Docker Desktop](https://www.docker.com/products/docker-desktop/)
+1. Run Poe the Poet workflow(s): e.g. `poetry poe run_all_tests`

pyproject.toml

@@ -9,10 +9,22 @@ packages = [{include = "pymaccounter", from="src"}]
 
 [tool.poetry.dependencies]
 python = ">=3.10,<4.0"
+
+[tool.poetry.group.runner.dependencies]
 dagger-io = "^0.9.5"
 anyio = "^4.2.0"
 fire = "^0.5.0"
-pandas = "^2.1.4"
+
+# define poethepoet convenience access
+# to test runner workflow definition
+[tool.poe.tasks.run_all_tests]
+cmd = """
+python src/pymaccounter/runner.py \
+'["test_baseline.py", \
+"test_multiply_gc.collect.py", \
+"test_multiply_gc.debug_leak.py", \
+"test_multiply_gc.callbacks.py"]'
+"""
 
 [build-system]
 requires = ["poetry-core"]

build/docker/Dockerfile → src/pymaccounter/Dockerfile

@@ -15,7 +15,7 @@ RUN pip install --no-cache-dir poetry
 COPY . .
 
 # install env from poetry
-RUN poetry install -v --no-interaction
+RUN poetry install --without runner -v --no-interaction
 
 # set an alias for running python through the poetry env
 # hadolint ignore=DL3059

src/pymaccounter/__init__.py

@@ -2,4 +2,4 @@
 __init__.py for pymaccounter
 """
 
-from .runner import run_test
+from .runner import pipeline_run_tests