Initial commit

This commit is contained in:
alain.berthoud committed 2026-10-22 08:45:37 +02:00
commit 24f61314a1
19 files changed
+2087

No files matched your search

+33
View File
@@ -0,0 +1,33 @@
// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/python
{
"name": "Python (uv)",
"image": "mcr.microsoft.com/devcontainers/python:3.12",
// Features to add to the dev container. More info: https://containers.dev/features.
"features": {
"ghcr.io/va-h/devcontainers-features/uv:1": {}
},
"containerEnv": {
// The uv cache and .venv are on different filesystems in the container:
// copy instead of hardlinking to avoid a warning on every install.
"UV_LINK_MODE": "copy"
},
// Use 'forwardPorts' to make a list of ports inside the container available locally.
// 8000 is used by `uv run mkdocs serve`.
"forwardPorts": [8000],
"postCreateCommand": "uv sync",
// Configure tool-specific properties.
"customizations": {
"vscode": {
"extensions": [
"ms-python.python",
"charliermarsh.ruff"
]
}
}
}
+24
View File
@@ -0,0 +1,24 @@
name: Build Documentation and publish 📦 to the documentation server
on:
push:
branches: [main]
jobs:
build:
name: Build documentation 📦
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v6
- name: Build documentation
run: uv run --locked --only-group docs mkdocs build --strict
- name: rsync deployments
uses: burnett01/rsync-deployments@7.0.1
with:
switches: -avr --delete
path: site/*
remote_path: ${{ gitea.event.repository.name }}
remote_host: ${{ vars.DOCS_HOST }}
remote_port: ${{ vars.DOCS_PORT }}
remote_user: ${{ vars.DOCS_USER }}
remote_key: ${{ secrets.DEPLOY_DOCS_KEY }}
+18
View File
@@ -0,0 +1,18 @@
name: Lint and test
on: [push, pull_request]
jobs:
test:
name: Lint and test 🧪
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v6
- name: Install the project
run: uv sync --locked
- name: Lint
run: uv run ruff check
- name: Check formatting
run: uv run ruff format --check
- name: Run tests
run: uv run pytest
+159
View File
@@ -0,0 +1,159 @@
# ---> Python
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
# C extensions
*.so
# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec
# Installer logs
pip-log.txt
pip-delete-this-directory.txt
# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/
# Translations
*.mo
*.pot
# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal
# Flask stuff:
instance/
.webassets-cache
# Scrapy stuff:
.scrapy
# PyBuilder
.pybuilder/
target/
# Jupyter Notebook
.ipynb_checkpoints
# IPython
profile_default/
ipython_config.py
# pyenv
# For a library or package, you might want to ignore these files since the code is
# intended to run in multiple environments; otherwise, check them in:
# .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
# poetry
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
# This is especially recommended for binary packages to ensure reproducibility, and is more
# commonly ignored for libraries.
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
#poetry.lock
# pdm
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
#pdm.lock
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
# in version control.
# https://pdm.fming.dev/#use-with-ide
.pdm.toml
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/
# Celery stuff
celerybeat-schedule
celerybeat.pid
# SageMath parsed files
*.sage.py
# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/
# Spyder project settings
.spyderproject
.spyproject
# Rope project settings
.ropeproject
# mkdocs documentation
/site
# mypy
.mypy_cache/
.dmypy.json
dmypy.json
# Pyre type checker
.pyre/
# pytype static type analyzer
.pytype/
# Cython debug symbols
cython_debug/
# PyCharm
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
# and can be added to the global gitignore or merged into this file. For a more nuclear
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
#.idea/
+6
View File
@@ -0,0 +1,6 @@
{
"recommendations": [
"ms-python.python",
"charliermarsh.ruff"
]
}
+15
View File
@@ -0,0 +1,15 @@
{
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
"python.testing.pytestArgs": [
"tests"
],
"python.testing.unittestEnabled": false,
"python.testing.pytestEnabled": true,
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.organizeImports": "explicit"
}
}
}
+5
View File
@@ -0,0 +1,5 @@
Copyright (c) 2026 AIMsight / Sensima Inspection. All rights reserved.
This software and its source code are proprietary and confidential.
Unauthorized copying, distribution or use, via any medium, is strictly
prohibited without the prior written permission of the copyright holder.
+154
View File
@@ -0,0 +1,154 @@
# template
Template repository for a Python project. It uses:
- [uv](https://docs.astral.sh/uv/) to manage Python, the virtual environment and dependencies
- `pyproject.toml` for the package metadata (built with [hatchling](https://hatch.pypa.io/))
- [pytest](https://docs.pytest.org/) for the tests
- [ruff](https://docs.astral.sh/ruff/) for linting and formatting
- [MkDocs](https://www.mkdocs.org/) with [Material](https://squidfunk.github.io/mkdocs-material/) and [mkdocstrings](https://mkdocstrings.github.io/) for the documentation
## Layout
```
├── pyproject.toml # package metadata, dependencies and tool configuration
├── mkdocs.yml # documentation configuration
├── src/sample/ # the package (rename it, see below)
├── tests/ # pytest tests
├── docs/ # documentation pages (Markdown)
└── tools/ # standalone scripts with their own inline dependencies
```
## Bootstrap the project
### 1. Install uv
```sh
# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
You do not need to install Python yourself: uv downloads a matching interpreter
if none is available.
### 2. Create the environment
```sh
uv sync
```
This creates `.venv/`, installs the package in editable mode with its runtime
dependencies, plus the `dev` (pytest, ruff) and `docs` (MkDocs) dependency groups. It
also writes `uv.lock`; commit it so everyone gets the same versions.
There is no need to activate the environment: prefix commands with `uv run`.
### 3. Everyday commands
| Task | Command |
|---------------------------------|--------------------------|
| Run the tests | `uv run pytest` |
| Lint (and auto-fix) | `uv run ruff check --fix`|
| Format the code | `uv run ruff format` |
| Run the package entry point | `uv run sample Alice` |
| Serve the docs with live reload | `uv run mkdocs serve` |
| Build the docs into `site/` | `uv run mkdocs build` |
| Build a wheel and sdist | `uv build` |
| Add a runtime dependency | `uv add requests` |
| Add a dev-only dependency | `uv add --dev mypy` |
| Upgrade the locked versions | `uv lock --upgrade` |
| Bump the version (patch/minor/major) | `uv version --bump minor` |
| Remove all generated files | `git clean -fdX` |
`git clean -fdX` deletes everything listed in `.gitignore`, including `.venv`;
run `uv sync` afterwards to recreate it.
## Starting a new project from this template
1. Rename the `src/sample/` folder to your package name.
2. In `pyproject.toml`, update `name`, `version`, `description`, `authors`, the
`[project.scripts]` entry and the path under
`[tool.hatch.build.targets.wheel]`.
3. In `src/<package>/__init__.py`, change the name passed to `version()`.
4. In `mkdocs.yml`, set `site_name`, and in `docs/reference.md` point the
`::: sample.helpers` directives at your modules.
5. Fix the imports in `tests/`, then run `uv sync` and `uv run pytest`.
6. Check the year in `LICENSE`. The template is proprietary (all rights
reserved); for an open-source project, replace `LICENSE` and set the
matching SPDX identifier in the `license` field of `pyproject.toml`.
The version is defined only in `pyproject.toml`; the package reads it back at
runtime with `importlib.metadata`, so `sample.__version__` always matches.
The package lives under `src/` so that tests run against the installed package,
not against the folder on disk: a file missing from the wheel fails the tests
instead of going unnoticed.
The `Private :: Do Not Upload` classifier makes PyPI reject the package if it is
ever published there by mistake.
## Tools
`tools/` holds standalone scripts that are not part of the package. Each one
declares its own Python version and dependencies in an inline metadata header
([PEP 723](https://peps.python.org/pep-0723/)):
```python
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = [
# "pandas",
# "rich",
# ]
# ///
```
uv reads that header and runs the script in its own cached environment, so the
dependencies never touch the project's `.venv`:
```sh
uv run tools/csv_summary.py data.csv
# or, thanks to the shebang (Linux / macOS):
./tools/csv_summary.py data.csv
```
To create a new tool, run `uv init --script tools/my_tool.py` and add its
dependencies with `uv add --script tools/my_tool.py <package>`.
## Documentation
Pages live in `docs/` as Markdown. API reference is generated from the
docstrings with mkdocstrings (`::: module.path` in a page). Docstrings use the
Sphinx `:param:` style; change `docstring_style` in `mkdocs.yml` to `google` or
`numpy` if you prefer.
## Dev container
`.devcontainer/` defines a VS Code dev container with Python 3.12 and uv. On
creation it runs `uv sync`, and it installs the Python and Ruff extensions.
`.vscode/settings.json` points VS Code at `.venv` and formats on save with ruff.
## Continuous integration
Two Gitea workflows live in `.gitea/workflows/`:
- `tests.yaml` runs on every push and pull request: `uv sync --locked` (fails if
`uv.lock` is out of date with `pyproject.toml`), `ruff check`,
`ruff format --check` and `pytest`.
- `build_docs.yaml` runs on pushes to `main`: it builds the site and publishes it
to the documentation server with rsync, into a folder named after the
repository.
The documentation server is configured outside the repository, at the
organisation (or repository) level under *Settings → Actions*:
| Kind | Name | Example |
|----------|-------------------|--------------------|
| Variable | `DOCS_HOST` | `10.0.1.184` |
| Variable | `DOCS_PORT` | `32760` |
| Variable | `DOCS_USER` | `data` |
| Secret | `DEPLOY_DOCS_KEY` | SSH private key |
+4
View File
@@ -0,0 +1,4 @@
# Welcome to Template documentation!
- [Introduction](intro.md)
- [Reference](reference.md)
+3
View File
@@ -0,0 +1,3 @@
# Introduction
This is an introduction to your project.
+3
View File
@@ -0,0 +1,3 @@
# Reference
::: sample.helpers
+41
View File
@@ -0,0 +1,41 @@
site_name: Project Name
site_author: Sensima / AIMsight
copyright: Copyright &copy; 2025 Sensima / AIMsight
theme:
name: material
features:
- navigation.sections
- content.code.copy
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
toggle:
icon: material/brightness-7
name: Switch to dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
toggle:
icon: material/brightness-4
name: Switch to light mode
nav:
- Home: index.md
- Introduction: intro.md
- Reference: reference.md
plugins:
- search
- mkdocstrings:
handlers:
python:
paths: [src]
options:
docstring_style: sphinx
show_source: true
show_root_heading: true
markdown_extensions:
- admonition
- pymdownx.highlight
- pymdownx.superfences
+55
View File
@@ -0,0 +1,55 @@
[project]
name = "sample"
version = "0.1.1"
description = "Template project libraries"
readme = "README.md"
requires-python = ">=3.10"
authors = [
{ name = "Olivier Chabloz", email = "olivier.chabloz@sensima.ch" },
{ name = "Marc Lany", email = "marc.lany@sensima.ch" },
]
keywords = ["aimsight", "sensima"]
license = "LicenseRef-Proprietary"
license-files = ["LICENSE"]
classifiers = [
"Private :: Do Not Upload",
]
dependencies = [
"numpy",
"pandas",
]
[project.scripts]
sample = "sample.__main__:main"
[dependency-groups]
dev = [
"pytest",
"ruff",
]
docs = [
"mkdocs<2", # MkDocs 2.0 drops the plugin system that mkdocstrings needs
"mkdocs-material",
"mkdocstrings[python]",
]
[tool.uv]
# `uv sync` installs both groups so a fresh clone can test and build docs.
default-groups = ["dev", "docs"]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.hatch.build.targets.wheel]
packages = ["src/sample"]
[tool.pytest.ini_options]
testpaths = ["tests"]
[tool.ruff]
line-length = 100
[tool.ruff.lint]
# pycodestyle, pyflakes, isort, pyupgrade, bugbear, simplify
select = ["E", "W", "F", "I", "UP", "B", "SIM"]
+3
View File
@@ -0,0 +1,3 @@
from importlib.metadata import version
__version__ = version("sample")
+12
View File
@@ -0,0 +1,12 @@
import sys
from sample import helpers
def main():
name = sys.argv[1] if len(sys.argv) > 1 else "world"
print(helpers.say_hello(name))
if __name__ == "__main__":
main()
+8
View File
@@ -0,0 +1,8 @@
def say_hello(name: str):
"""
A polite function
:param name: the person's name to greet
"""
return f"hello {name}"
+5
View File
@@ -0,0 +1,5 @@
from sample import helpers
def test_hello():
assert helpers.say_hello("Sensima") == "hello Sensima"
+49
View File
@@ -0,0 +1,49 @@
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = [
# "pandas",
# "rich",
# ]
# ///
"""
Sample standalone tool: print a summary of a CSV file.
The block above is inline script metadata (PEP 723). uv reads it and runs the
script in its own throwaway environment, so the tool's dependencies stay out
of the project's environment.
Usage:
uv run tools/csv_summary.py data.csv
./tools/csv_summary.py data.csv (after chmod +x)
"""
import argparse
import pandas as pd
from rich.console import Console
from rich.table import Table
def main():
parser = argparse.ArgumentParser(description=__doc__.strip().splitlines()[0])
parser.add_argument("csv_file", help="path to the CSV file to summarise")
args = parser.parse_args()
df = pd.read_csv(args.csv_file)
table = Table(title=f"{args.csv_file} ({len(df)} rows)")
table.add_column("column")
table.add_column("dtype")
table.add_column("non-null", justify="right")
table.add_column("mean", justify="right")
for name in df.columns:
col = df[name]
mean = f"{col.mean():.4g}" if pd.api.types.is_numeric_dtype(col) else "-"
table.add_row(str(name), str(col.dtype), str(col.count()), mean)
Console().print(table)
if __name__ == "__main__":
main()
Generated
+1490
View File
File diff suppressed because it is too large. Load diff