feat: add quality tooling around Poetry

.flake8

@@ -0,0 +1 @@
+pkg/.flake8

.gitignore

@@ -1,4 +1,118 @@
-venv/
+pkg/doc/_autosummary
+
+.envrc
+.idea
+
+# Created by https://www.gitignore.io/api/osx,linux,python,windows,pycharm,visualstudiocode
+
+### Linux ###
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### OSX ###
+*.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### PyCharm ###
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and Webstorm
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff:
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/dictionaries
+
+# Sensitive or high-churn files:
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.xml
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+
+# Gradle:
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# CMake
+cmake-build-debug/
+
+# Mongo Explorer plugin:
+.idea/**/mongoSettings.xml
+
+## File-based project format:
+*.iws
+
+## Plugin-specific files:
+
+# IntelliJ
+/out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# Ruby plugin and RubyMine
+/.rakeTasks
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+### PyCharm Patch ###
+# Comment Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-215987721
+
+# *.iml
+# modules.xml
+# .idea/misc.xml
+# *.ipr
+
+# Sonarlint plugin
+.idea/sonarlint
+
+### Python ###
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -21,12 +135,10 @@ parts/
 sdist/
 var/
 wheels/
-pip-wheel-metadata/
-share/python-wheels/
 *.egg-info/
 .installed.cfg
 *.egg
-MANIFEST
+/*.zip
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -41,27 +153,19 @@ pip-delete-this-directory.txt
 # Unit test / coverage reports
 htmlcov/
 .tox/
-.nox/
 .coverage
 .coverage.*
 .cache
+.pytest_cache/
 nosetests.xml
 coverage.xml
 *.cover
-*.py,cover
 .hypothesis/
-.pytest_cache/
 
 # Translations
 *.mo
 *.pot
 
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
 # Flask stuff:
 instance/
 .webassets-cache
@@ -78,26 +182,11 @@ target/
 # Jupyter Notebook
 .ipynb_checkpoints
 
-# IPython
-profile_default/
-ipython_config.py
-
 # pyenv
 .python-version
 
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
+# celery beat schedule file
+celerybeat-schedule.*
 
 # SageMath parsed files
 *.sage.py
@@ -123,12 +212,38 @@ venv.bak/
 
 # mypy
 .mypy_cache/
-.dmypy.json
-dmypy.json
 
-# Pyre type checker
-.pyre/
+### VisualStudioCode ###
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+.history
+
+### Windows ###
+# Windows thumbnail cache files
+Thumbs.db
+ehthumbs.db
+ehthumbs_vista.db
+
+# Folder config file
+Desktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# Build folder
 
-.vscode/
+*/build/*
 
-data/audio/
+# End of https://www.gitignore.io/api/osx,linux,python,windows,pycharm,visualstudiocode

.pre-commit-config.yaml

@@ -0,0 +1,93 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: trailing-whitespace
+      - id: check-added-large-files
+        name: Check for added large files
+        entry: check-added-large-files
+      - id: check-toml
+        name: Check Toml
+        entry: check-toml
+        types: [toml]
+      - id: check-yaml
+        name: Check Yaml
+        entry: check-yaml
+        types: [yaml]
+      - id: end-of-file-fixer
+        name: Fix End of Files
+        entry: end-of-file-fixer
+        types: [text]
+        stages: [commit, push, manual]
+      - id: trailing-whitespace
+        name: Trim Trailing Whitespace
+        entry: trailing-whitespace-fixer
+        types: [text]
+        stages: [commit, push, manual]
+
+  - repo: https://github.com/mwouts/jupytext
+    rev: v1.14.6
+    hooks:
+      - id: jupytext
+        name: jupytext (sync existing Notebooks)
+        entry: jupytext
+        language: python
+        args: [--sync, --pipe, black, --pre-commit]
+        pass_filenames: false
+        additional_dependencies:
+          - black==23.3.0
+
+  - repo: https://github.com/psf/black
+    rev: 23.3.0
+    hooks:
+      - id: black
+        name: black
+        entry: black
+        types: [python]
+        require_serial: true
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+        name: isort
+        entry: isort
+        require_serial: true
+        language: python
+        types_or: [cython, pyi, python]
+        args: ["--profile", "black", "--filter-files"]
+
+  - repo: https://github.com/pycqa/flake8
+    rev: "6.0.0"
+    hooks:
+      - id: flake8
+        name: flake8
+        entry: flake8
+        types: [python]
+        require_serial: true
+        exclude: "jupyter/scripts"
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.7.0
+    hooks:
+      - id: pyupgrade
+        name: pyupgrade
+        description: Automatically upgrade syntax for newer versions.
+        entry: pyupgrade
+        types: [python]
+        args: [--py39-plus]
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: 3.5.2
+    hooks:
+      - id: commitizen
+      - id: commitizen-branch
+        stages: [push]
+  - repo: https://github.com/python-poetry/poetry
+    rev: '1.5.0'
+    hooks:
+      - id: poetry-check
+      # - id: poetry-lock
+      # - id: poetry-export
+      #   files: "pyproject.toml,requirements.txt"
+      #   args: ["-f", "requirements.txt", "-o", "requirements.txt", "--without-hashes", "--only=main"]

Dockerfile

@@ -10,7 +10,7 @@ RUN pip3 install --upgrade pip
 RUN pip3 install --no-cache-dir -r /app/requirements.txt
 
 # Persistent disk space
-# see https://huggingface.co/docs/hub/spaces-storage 
+# see https://huggingface.co/docs/hub/spaces-storage
 RUN mkdir -p /data/.huggingface
 ENV HF_HOME /data/.huggingface
 
@@ -28,7 +28,7 @@ COPY . $HOME/app
 
 # Back to root to fix ownership and permissions
 USER root
-RUN chown user /data/.huggingface 
+RUN chown user /data/.huggingface
 USER user
 
 # Expose streamlit application

README.md

@@ -18,7 +18,7 @@ Code from https://docs.streamlit.io/library/get-started/create-an-app
 ## Local execution ##
 
 You need *Docker* installed.
-On MacOSX we recommand using *colima* if you do not want to use *Docker Desktop* 
+On MacOSX we recommand using *colima* if you do not want to use *Docker Desktop*
 for licensing reasons.
 
 * https://docs.docker.com/desktop/install/mac-install/
@@ -30,3 +30,160 @@ $ docker build -t persistent-docker-space .
 $ docker run -it -p 8501:8501 persistent-docker-space:latest
 
 ```
+
+# Setting-up the developpers'tooling
+
+### Install `poetry`
+
+https://python-poetry.org/
+
+#### Linux and Mac
+
+It should be straightforward with the official documentation
+
+#### Windows (PowerShell)
+
+```shell
+(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
+```
+
+The execution will probably be stored at the address: `C:\User\<myUserName>\AppData\Roaming\pypoetry\venv\Scripts` and this
+path should be included in the environment path of your machine in order to avoid typing it every time poetry is used.
+To do so you can execute the following commands:
+
+```shell
+$Env:Path += ";C:\Users\YourUserName\AppData\Roaming\Python\Scripts"
+```
+
+This will only make the change in the path temporarily. In order to do it permanently you can execute the following command
+```shell
+setx PATH "$Env:Path"
+```
+
+### Configuration of the `poetry` environment
+
+After having installed poetry in your local machine, if there is already a `poetry.lock` file on your repository, you
+can execute
+
+```shell
+poetry install
+```
+
+If it is not the case you can
+
+```shell
+poetry init
+poetry env use "whatever version of python you have in your local machine (compatible with the project)"
+poetry shell
+```
+
+### pre-commit
+
+https://pre-commit.com/
+
+If there is already a `poetry.lock` file with `pre-commit` present in it, you should activate your poetry environment
+and then install all the pre-commit hooks on your machine
+
+```shell
+poetry shell
+pre-commit install
+pre-commit install --install-hooks
+```
+
+If not, you should first add `pre-commit` to your poetry environment, and follow the steps above
+
+```shell
+poetry add --group=dev pre-commit
+```
+
+### commitizen
+
+https://www.conventionalcommits.org/en/about/
+
+https://commitizen-tools.github.io/commitizen/
+
+
+Commitizen will be installed as a pre-commit hook. In order for it to be executed before committing
+you should run the following command (after activating your poetry environment)
+
+```shell
+pre-commit install --hook-type commit-msg
+```
+
+Finally, every time you will be committing, you should be places in your poetry environment and commitizen hooks
+should be applied
+
+### testing
+
+There are two different kinds of tests that can be run when testing the scripts: unit tests or doctest
+
+These tests can be run by executing the following command:
+
+```shell
+./scripts/run-tests.sh
+```
+
+#### pytest
+
+https://docs.pytest.org/en/7.2.x/
+
+These tests should be stored in the directory `tests` at the root of the project
+
+#### xdoctest (driven by pytest)
+
+These are the tests that are put in the docstrings of the functions accordingly to the following format:
+
+```python
+    def build_greetings(name: Optional[str] = None) -> str:
+        """
+            Return a greeting message, possibly customize with a name.
+
+            >>> build_greetings()
+            'Hello, World!'
+            >>> build_greetings('Toto')
+            'Nice to meet you, Toto!'
+        """
+        return name and f"Nice to meet you, {name}!" or "Hello, World!"
+```
+
+The evaluated values would be the ones following the `>>>`
+
+### documentation
+
+https://www.sphinx-doc.org/en/master/
+
+In order to create an automatic documentation of your code you should run the bash script
+
+```shell
+./scripts/build-clean-docs.sh
+```
+
+And in order to create an interactive session (web-server hosted in your local machine), you can execute the
+following command
+
+```shell
+./scripts/interactive-rebuild-docs.sh
+```
+
+Remark: In order to execute a bash script with a Windows OS, it is recommended to use a bash terminal emulator
+
+## Hugging Face
+
+See instructions at https://huggingface.co/welcome
+
+Install `huggingface_hub` into the poetry project.
+
+```shell
+poetry add --group=dev huggingface_hub
+```
+
+On MacOS, you might probably want to install `hugginface-cli` from brew :
+```shell
+$ brew install huggingface-cli
+```
+
+In order to deploy the streamlit app you will have to export
+the poetry config as a `requirements.txt` :
+```shell
+$ poetry export -o ../requirements.txt --without-hashes --only main
+```

app.py

@@ -1,38 +1,48 @@
-import streamlit as st
-import pandas as pd
 import numpy as np
+import pandas as pd
+import streamlit as st
+
 
-st.title('Uber pickups in NYC')
+st.title("Uber pickups in NYC")
+
+DATE_COLUMN = "date/time"
+DATA_URL = (
+    "https://s3-us-west-2.amazonaws.com/"
+    "streamlit-demo-data/uber-raw-data-sep14.csv.gz"
+)
 
-DATE_COLUMN = 'date/time'
-DATA_URL = ('https://s3-us-west-2.amazonaws.com/'
-            'streamlit-demo-data/uber-raw-data-sep14.csv.gz')
 
 @st.cache_resource
 def load_data(nrows):
     data = pd.read_csv(DATA_URL, nrows=nrows)
-    lowercase = lambda x: str(x).lower()
-    data.rename(lowercase, axis='columns', inplace=True)
+
+    def lowercase():
+        lambda x: str(x).lower()
+
+    data.rename(lowercase, axis="columns", inplace=True)
     data[DATE_COLUMN] = pd.to_datetime(data[DATE_COLUMN])
     return data
 
-data_load_state = st.text('Loading data...')
+
+data_load_state = st.text("Loading data...")
 data = load_data(10000)
 data_load_state.text("Done! (using st.cache)")
 
-if st.checkbox('Show raw data'):
-    st.subheader('Raw data')
+if st.checkbox("Show raw data"):
+    st.subheader("Raw data")
     st.write(data)
 
-st.subheader('Number of pickups by hour')
-hist_values = np.histogram(data[DATE_COLUMN].dt.hour, bins=24, range=(0,24))[0]
+st.subheader("Number of pickups by hour")
+hist_values = np.histogram(data[DATE_COLUMN].dt.hour, bins=24, range=(0, 24))[
+    0
+]
 st.bar_chart(hist_values)
 
 # Some number in the range 0-23
-hour_to_filter = st.slider('hour', 0, 23, 17)
+hour_to_filter = st.slider("hour", 0, 23, 17)
 filtered_data = data[data[DATE_COLUMN].dt.hour == hour_to_filter]
 
-st.subheader('Map of all pickups at %s:00' % hour_to_filter)
+st.subheader("Map of all pickups at %s:00" % hour_to_filter)
 st.map(filtered_data)
 
 uploaded_file = st.file_uploader("Choose a file")

doc/_autosummary/athai.hello.rst

@@ -0,0 +1,30 @@
+athai.hello
+===========
+
+.. automodule:: athai.hello
+
+   
+   
+   
+
+   
+   
+   .. rubric:: Functions
+
+   .. autosummary::
+   
+      build_greetings
+      main
+   
+   
+
+   
+   
+   
+
+   
+   
+   
+
+
+

doc/_autosummary/athai.rst

@@ -0,0 +1,31 @@
+athai
+=====
+
+.. automodule:: athai
+
+   
+   
+   
+
+   
+   
+   
+
+   
+   
+   
+
+   
+   
+   
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+
+   athai.hello
+

doc/about.rst

@@ -0,0 +1,15 @@
+==================
+About this project
+==================
+
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+
+Tooling
+=======
+
+.. todo::
+    Move notes from the ReadMe here and actually provide explanations
+
+
+.. include:: ../jupyter/ReadMe.rst

doc/autosummary.rst

@@ -0,0 +1,14 @@
+..
+   DO NOT DELETE THIS FILE! It contains the all-important `.. autosummary::` directive with `:recursive:` option, without
+   which API documentation wouldn't get extracted from docstrings by the `sphinx.ext.autosummary` engine. It is hidden
+   (not declared in any toctree) to remove an unnecessary intermediate page; index.rst instead points directly to the
+   package page. DO NOT REMOVE THIS FILE!
+
+    See https://github.com/JamesALeedham/Sphinx-Autosummary-Recursion for details
+
+
+.. autosummary::
+   :toctree: _autosummary
+   :recursive:
+
+   athai

doc/conf.py

@@ -0,0 +1,52 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Template Python project"
+copyright = "2023, Polyconseil"
+author = "Anthony Truchet"
+release = "0.1"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
+    "myst_parser",
+    "sphinx_rtd_theme",
+]
+
+autodoc_typehints = "signature"
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "special-members": "__call__",
+    "undoc-members": True,
+    "exclude-members": "__weakref__",
+    "show-inheritance": True,
+    "autodoc_typehints": "signature",
+}
+
+autosummary_generate = True
+
+# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
+todo_include_todos = True
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+# html_theme = 'alabaster'
+html_theme = "sphinx_rtd_theme"
+
+html_static_path = ["_static"]

doc/howto.rst

@@ -0,0 +1,7 @@
+==========
+How to ...
+==========
+
+.. py:currentmodule:: athai.hello
+
+The main entry point of the application is the :func:`main` which actually delegates all the work to :func:`build_greetings`.

doc/index.rst

@@ -0,0 +1,25 @@
+.. Template Python project documentation master file, created by
+   sphinx-quickstart on Wed Mar 22 15:25:04 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to AI playground's documentation!
+===================================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   How to... <howto>
+
+   API reference <_autosummary/athai>
+
+   about
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/todo.rst

@@ -0,0 +1,4 @@
+TODO
+====
+
+.. todolist::

jupyter/ReadMe.rst

@@ -0,0 +1,43 @@
+About the Jupytext workflow
+===========================
+
+Introduction
+------------
+
+This directory contains the actual experiments files.
+Typically, these are Jupyter_ notebooks;
+but the ``.ipynb`` format plays especially bad with git version control.
+
+The Jupytext_ tool and workflows provide for a workaround to help with
+version-controlled collaboration by pairing the ``.ipynb`` files with
+python scripts (``.py``) or documentation files (``.rst``, ``.md``).
+
+Please refer to Jupytext_ documentation or this `JupyterCon 2020 talk`__.
+
+__ https://github.com/mwouts/jupytext_jupytercon2020/blob/master/README.md
+
+.. _Jupytext: https://jupytext.readthedocs.io/en/latest/index.html#
+.. _Jupyter: https://jupyter.org/
+
+Intended workflow
+-----------------
+
+
+Create new native Jupyter notebooks in the ``experiments/notebook``
+folder or one of its sub-folders and *do not add them to your commit*.
+They will be synchronized automatically by pre-commit hooks with
+Python scripts using the `percent format` stored in ``experiments/script``
+that are much cleaner to version-control and review.
+
+.. todo::
+    Add an option to version or publish finalized notebooks as HTML.
+
+Configuration
+-------------
+
+The configuration of the pairing is centralized in the :file:`jupytext.toml`.
+
+.. github-only
+    This RsT comments block allow the provide bellow references for GitHub
+    to display (using standard RsT instead of Sphinx) and whatever is bellow
+    will be ignored by Sphinx when including this file.

jupyter/notebooks/SOLID_Musing.ipynb

@@ -0,0 +1,112 @@
+{
+ "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "8d39ce6d",
+   "metadata": {},
+   "source": [
+    "## *Principles* ? What is the point ?"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "c10de8ce",
+   "metadata": {},
+   "source": [
+    "The SOLID principles are:\n",
+    "\n",
+    "* The **S**ingle-Responsibility Principle (*SRP*)\n",
+    "* The **O**pen-Closed Principle (*OCP*)\n",
+    "* The **L**iskov Substitution Principle (*LSP*)\n",
+    "* The **I**nterface Segregation Principle (*ISP*)\n",
+    "* The **D**ependency inversion Principle (*DIP*)\n",
+    "\n",
+    "These five principles are not a specific ordered list (do this, then that, etc) but a collection of best practices, developed through the decades. They are gathered into an acronym, as a mnemonic vehicle to be remembered, similar to others in computer science, e.g.: *DRY*: Don’t Repeat Yourself; *KISS*: Keep It Small and Simple; as pieces of accumulated wisdom. A little side note, the acronym was created years after these five principles were set together.\n",
+    "\n",
+    "\n",
+    "\n",
+    "From https://towardsdatascience.com/solid-coding-in-python-1281392a6a94"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "014fad04",
+   "metadata": {},
+   "source": [
+    "STUPID is an acronym that describes bad practices in Oriented Object Programming:\n",
+    "\n",
+    "* **S**ingleton\n",
+    "* **T**ight Coupling\n",
+    "* **U**ntestability\n",
+    "* **P**remature Optimization\n",
+    "* **I**ndescriptive Naming\n",
+    "* **D**uplication\n",
+    "\n",
+    "from https://williamdurand.fr/2013/07/30/from-stupid-to-solid-code/#:~:text=SOLID%20is%20an%20acronym%20that,Liskov%20Substitution%20Principle\n"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "30f034a5",
+   "metadata": {},
+   "source": [
+    "# Loading the package dynamically\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "98f2f3f8",
+   "metadata": {
+    "lines_to_next_cell": 2
+   },
+   "outputs": [],
+   "source": [
+    "%load_ext autoreload\n",
+    "%autoreload 1"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "14acf530",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%aimport athai.hello"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "f8be4aa9",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.16"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

jupyter/scripts/SOLID_Musing.py

@@ -0,0 +1,59 @@
+# ---
+# jupyter:
+#   jupytext:
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.14.6
+#   kernelspec:
+#     display_name: Python 3 (ipykernel)
+#     language: python
+#     name: python3
+# ---
+
+# %% [markdown]
+# ## *Principles* ? What is the point ?
+
+# %% [markdown]
+# The SOLID principles are:
+#
+# * The **S**ingle-Responsibility Principle (*SRP*)
+# * The **O**pen-Closed Principle (*OCP*)
+# * The **L**iskov Substitution Principle (*LSP*)
+# * The **I**nterface Segregation Principle (*ISP*)
+# * The **D**ependency inversion Principle (*DIP*)
+#
+# These five principles are not a specific ordered list (do this, then that, etc) but a collection of best practices, developed through the decades. They are gathered into an acronym, as a mnemonic vehicle to be remembered, similar to others in computer science, e.g.: *DRY*: Don’t Repeat Yourself; *KISS*: Keep It Small and Simple; as pieces of accumulated wisdom. A little side note, the acronym was created years after these five principles were set together.
+#
+#
+#
+# From https://towardsdatascience.com/solid-coding-in-python-1281392a6a94
+
+# %% [markdown]
+# STUPID is an acronym that describes bad practices in Oriented Object Programming:
+#
+# * **S**ingleton
+# * **T**ight Coupling
+# * **U**ntestability
+# * **P**remature Optimization
+# * **I**ndescriptive Naming
+# * **D**uplication
+#
+# from https://williamdurand.fr/2013/07/30/from-stupid-to-solid-code/#:~:text=SOLID%20is%20an%20acronym%20that,Liskov%20Substitution%20Principle
+#
+
+# %% [markdown]
+# # Loading the package dynamically
+#
+
+# %%
+# %load_ext autoreload
+# %autoreload 1
+
+
+# %%
+# %aimport athai.hello
+
+# %% [markdown]
+#

jupytext.toml

@@ -0,0 +1,2 @@
+# Pair notebooks in subfolders of 'notebooks' to scripts in subfolders of 'scripts'
+formats = "jupyter/notebooks///ipynb,jupyter/scripts///py:percent"

poetry.toml

@@ -0,0 +1,4 @@
+[installer]
+# Temporary workaround : poetry 1.4.1 became stricter with invalid weel
+# This preventing install of jupyter and furo.
+modern-installation = false

pyproject.toml

@@ -0,0 +1,69 @@
+[tool.poetry]
+name = "hugging-face-playground"
+version = "0.1.0"
+description = "An example of AI project with some (hopefully) good practices"
+authors = ["Anthony Truchet <anthony.truchet@athai.tech>"]
+readme = "README.md"
+
+packages = [
+    { include = "athai", from = "src" },
+]
+
+[tool.poetry.scripts]
+hello = "athai.hello:main"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+streamlit = "^1.24.0"
+pandas = "^2.0.2"
+numpy = "^1.25.0"
+
+[tool.poetry.group.dev.dependencies]
+pre-commit = "^3.2.0"
+commitizen = "^2.42.1"
+flake8-docstrings = "^1.7.0"
+pygments = "^2.14.0"
+huggingface-hub = "^0.15.1"
+
+[tool.poetry.group.tests.dependencies]
+pytest = "^7.2.2"
+mockito = "^1.4.0"
+coverage = "^7.2.2"
+xdoctest = "^1.1.1"
+
+[tool.poetry.group.doc.dependencies]
+sphinx = "^6.1.3"
+sphinx-autobuild = "^2021.3.14"
+sphinx-rtd-theme = "^1.2.0"
+myst-parser = "^1.0.0"
+darglint = "^1.8.1"
+
+[tool.poetry.group.jupyter.dependencies]
+jupyter = "^1.0.0"
+jupytext = "^1.14.5"
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+testpaths = ["tests", "src",]
+# Comment out next line to skip running examples section of doc-strings as tests
+addopts = "--xdoctest"
+
+[tool.coverage.run]
+branch = true
+source_pkgs = ["athai",]
+
+[tool.coverage.report]
+# fail_under = 90
+show_missing = true
+
+[tool.isort]
+profile = "black"
+force_single_line = true
+lines_after_imports = 2
+
+[tool.black]
+line-length = 79
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

requirements.txt

@@ -1,3 +1,47 @@
-streamlit
-numpy
-pandas
+altair==5.0.1 ; python_version >= "3.10" and python_version < "4.0"
+attrs==23.1.0 ; python_version >= "3.10" and python_version < "4.0"
+blinker==1.6.2 ; python_version >= "3.10" and python_version < "4.0"
+cachetools==5.3.1 ; python_version >= "3.10" and python_version < "4.0"
+certifi==2023.5.7 ; python_version >= "3.10" and python_version < "4.0"
+charset-normalizer==2.1.1 ; python_version >= "3.10" and python_version < "4.0"
+click==8.1.3 ; python_version >= "3.10" and python_version < "4.0"
+colorama==0.4.6 ; python_version >= "3.10" and python_version < "4.0" and platform_system == "Windows"
+decorator==5.1.1 ; python_version >= "3.10" and python_version < "4.0"
+gitdb==4.0.10 ; python_version >= "3.10" and python_version < "4.0"
+gitpython==3.1.31 ; python_version >= "3.10" and python_version < "4.0"
+idna==3.4 ; python_version >= "3.10" and python_version < "4.0"
+importlib-metadata==6.7.0 ; python_version >= "3.10" and python_version < "4.0"
+jinja2==3.1.2 ; python_version >= "3.10" and python_version < "4.0"
+jsonschema==4.17.3 ; python_version >= "3.10" and python_version < "4.0"
+markdown-it-py==2.2.0 ; python_version >= "3.10" and python_version < "4.0"
+markupsafe==2.1.3 ; python_version >= "3.10" and python_version < "4.0"
+mdurl==0.1.2 ; python_version >= "3.10" and python_version < "4.0"
+numpy==1.25.0 ; python_version >= "3.10" and python_version < "4.0"
+packaging==23.1 ; python_version >= "3.10" and python_version < "4.0"
+pandas==2.0.2 ; python_version >= "3.10" and python_version < "4.0"
+pillow==9.5.0 ; python_version >= "3.10" and python_version < "4.0"
+protobuf==4.23.3 ; python_version >= "3.10" and python_version < "4.0"
+pyarrow==12.0.1 ; python_version >= "3.10" and python_version < "4.0"
+pydeck==0.8.0 ; python_version >= "3.10" and python_version < "4.0"
+pygments==2.15.1 ; python_version >= "3.10" and python_version < "4.0"
+pympler==1.0.1 ; python_version >= "3.10" and python_version < "4.0"
+pyrsistent==0.19.3 ; python_version >= "3.10" and python_version < "4.0"
+python-dateutil==2.8.2 ; python_version >= "3.10" and python_version < "4.0"
+pytz-deprecation-shim==0.1.0.post0 ; python_version >= "3.10" and python_version < "4.0"
+pytz==2023.3 ; python_version >= "3.10" and python_version < "4.0"
+requests==2.31.0 ; python_version >= "3.10" and python_version < "4.0"
+rich==13.4.2 ; python_version >= "3.10" and python_version < "4.0"
+six==1.16.0 ; python_version >= "3.10" and python_version < "4.0"
+smmap==5.0.0 ; python_version >= "3.10" and python_version < "4.0"
+streamlit==1.24.0 ; python_version >= "3.10" and python_version < "4.0"
+tenacity==8.2.2 ; python_version >= "3.10" and python_version < "4.0"
+toml==0.10.2 ; python_version >= "3.10" and python_version < "4.0"
+toolz==0.12.0 ; python_version >= "3.10" and python_version < "4.0"
+tornado==6.3.2 ; python_version >= "3.10" and python_version < "4.0"
+typing-extensions==4.6.3 ; python_version >= "3.10" and python_version < "4.0"
+tzdata==2023.3 ; python_version >= "3.10" and python_version < "4.0"
+tzlocal==4.3.1 ; python_version >= "3.10" and python_version < "4.0"
+urllib3==2.0.3 ; python_version >= "3.10" and python_version < "4.0"
+validators==0.20.0 ; python_version >= "3.10" and python_version < "4.0"
+watchdog==3.0.0 ; python_version >= "3.10" and python_version < "4.0" and platform_system != "Darwin"
+zipp==3.15.0 ; python_version >= "3.10" and python_version < "4.0"

scripts/build-clean-docs.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env sh
+
+DOCS_GENERATED_API_SRC=src/athai
+DOCS_SRC=doc
+DOCS_GENERATED_API_DST=doc/_autosummary
+DOCS_DST=dist/doc
+
+rm -rf $DOCS_DST
+rm -rf $DOCS_GENERATED_API_DST
+
+poetry run sphinx-build -E -a $DOCS_SRC $DOCS_DST

scripts/interactive-rebuild-docs.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+poetry run sphinx-autobuild --open-browser doc dist/doc

scripts/run-all-precommit-checks.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+poetry run pre-commit run --all-files --hook-stage=manual

scripts/run-coverage.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+poetry run coverage run --parallel -m pytest
+poetry run coverage combine
+poetry run coverage report

scripts/run-tests.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+poetry run pytest

src/athai/hello.py

@@ -0,0 +1,27 @@
+from typing import Optional
+
+
+print(
+    f"executing the file '{__file__}'"
+    f"in module '{__name__}' and package '{__package__}'"
+)
+
+
+def build_greetings(name: Optional[str] = None) -> str:
+    """
+    Return a greeting message, possibly customize with a name.
+
+    >>> build_greetings()
+    'Hello, World!'
+    >>> build_greetings('Toto')
+    'Nice to meet you, Toto!'
+    """
+    return name and f"Nice to meet you, {name}!" or "Hello, World!"
+
+
+def main():
+    print(build_greetings())
+
+
+if __name__ == "__main__":
+    main()  # pragma: no cover

tests/athai/test_hello.py

@@ -0,0 +1,14 @@
+from athai import hello
+
+
+def test_hello_default():
+    assert hello.build_greetings() == "Hello, World!"
+
+
+def test_hello_name():
+    assert hello.build_greetings("Toto") == "Nice to meet you, Toto!"
+
+
+# Given / Arrange
+# When / Act
+# Then / Assert

tests/conftest.py

@@ -0,0 +1,11 @@
+# conftest.py
+import pytest
+
+
+@pytest.fixture
+def unstub():
+    """Ensure calls patched by mockito are cleared after each test"""
+    from mockito import unstub
+
+    yield
+    unstub()