Initial commit
This commit is contained in:
commit
24f61314a1
19 files changed
+2087
No files matched your search
@@ -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"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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 }}
|
||||
@@ -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
@@ -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/
|
||||
|
||||
Vendored
+6
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"recommendations": [
|
||||
"ms-python.python",
|
||||
"charliermarsh.ruff"
|
||||
]
|
||||
}
|
||||
Vendored
+15
@@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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.
|
||||
@@ -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 |
|
||||
@@ -0,0 +1,4 @@
|
||||
# Welcome to Template documentation!
|
||||
|
||||
- [Introduction](intro.md)
|
||||
- [Reference](reference.md)
|
||||
@@ -0,0 +1,3 @@
|
||||
# Introduction
|
||||
|
||||
This is an introduction to your project.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Reference
|
||||
|
||||
::: sample.helpers
|
||||
+41
@@ -0,0 +1,41 @@
|
||||
site_name: Project Name
|
||||
site_author: Sensima / AIMsight
|
||||
copyright: Copyright © 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
|
||||
@@ -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"]
|
||||
@@ -0,0 +1,3 @@
|
||||
from importlib.metadata import version
|
||||
|
||||
__version__ = version("sample")
|
||||
@@ -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()
|
||||
@@ -0,0 +1,8 @@
|
||||
def say_hello(name: str):
|
||||
"""
|
||||
A polite function
|
||||
|
||||
|
||||
:param name: the person's name to greet
|
||||
"""
|
||||
return f"hello {name}"
|
||||
@@ -0,0 +1,5 @@
|
||||
from sample import helpers
|
||||
|
||||
|
||||
def test_hello():
|
||||
assert helpers.say_hello("Sensima") == "hello Sensima"
|
||||
Executable
+49
@@ -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()
|
||||
Reference in new issue
Block a user