generated from realAscot/template-python
253 lines
7.3 KiB
Markdown
253 lines
7.3 KiB
Markdown
|
# Python Bootstrap-Template mit `.venv`- und `.env` Support
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
Dieses Template nutzt PEP 8, Type Hints, Docstrings und einen vordefinierten Workspace für sauberen Python-Code.
|
|||
|
|
Außerdem bietet es ein portables Start-Template für Python-Anwendungen mit folgenden Features:
|
|||
|
|
|
|||
|
|
- Automatische Erstellung einer virtuellen Umgebung (`.venv`)
|
|||
|
|
- Automatische Installation von Abhängigkeiten aus `requirements.txt`
|
|||
|
|
- Automatischer Neustart in der virtuellen Umgebung
|
|||
|
|
- Unterstützung von Umgebungsvariablen über eine `.env`-Datei
|
|||
|
|
- Sauberer Einstiegspunkt über `run.py`
|
|||
|
|
- Keine systemweiten Python-Pakete notwendig
|
|||
|
|
- Logging-Utils bereits integriert
|
|||
|
|
|
|||
|
|
Das Template ist durchdacht, pragmatisch und stark auf Entwicklerkomfort ausgelegt.
|
|||
|
|
Es bietet eine sehr gute Grundlage für Projekte aller Art – insbesondere CLI-Tools, kleine Services und lokale Anwendungen. Die automatische Einrichtung der virtuellen Umgebung hebt es funktional deutlich von Standard-Vorlagen ab.
|
|||
|
|
|
|||
|
|
**Was dieses template __nicht__ ist:**
|
|||
|
|
|
|||
|
|
- [ ] [pep-518](https://peps.python.org/pep-0518/)-konform 🚫
|
|||
|
|
|
|||
|
|
> ⚠️ Dieses Template verfolgt kein komplexes Build-System.
|
|||
|
|
Es ist dafür gedacht, dir in Sekunden eine saubere, gekapselte Python-Umgebung bereitzustellen – perfekt zum schnellen Testen, Debuggen oder Projektstart.
|
|||
|
|
Einfach deinen Code in main.py werfen, bei Bedarf requirements.txt anpassen, run.py starten – fertig. Kein Setup-Wahnsinn, kein Overhead.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🔜 Inhalt der Readme
|
|||
|
|
|
|||
|
|
- [Python Bootstrap-Template mit `.venv`- und `.env` Support](#python-bootstrap-template-mit-venv--und-env-support)
|
|||
|
|
- [🔜 Inhalt der Readme](#-inhalt-der-readme)
|
|||
|
|
- [🔧 Projektstruktur](#-projektstruktur)
|
|||
|
|
- [🚀 Erste Schritte](#-erste-schritte)
|
|||
|
|
- [Beim ersten Start passiert:](#beim-ersten-start-passiert)
|
|||
|
|
- [📦 Abhängigkeiten](#-abhängigkeiten)
|
|||
|
|
- [⚙️ .env-Datei (optional)](#️-env-datei-optional)
|
|||
|
|
- [📜 Beispielausgabe](#-beispielausgabe)
|
|||
|
|
- [🪵 Logging](#-logging)
|
|||
|
|
- [🔧 Konfiguration (in `.env`)](#-konfiguration-in-env)
|
|||
|
|
- [📥 Beispielausgabe](#-beispielausgabe-1)
|
|||
|
|
- [📌 Logik im Code](#-logik-im-code)
|
|||
|
|
- [📁 Logrotation](#-logrotation)
|
|||
|
|
- [🛠 Hinweise](#-hinweise)
|
|||
|
|
- [🧪 Getestet mit](#-getestet-mit)
|
|||
|
|
- [🛠 Einsatz von `Linter` (`pylint`)](#-einsatz-von-linter-pylint)
|
|||
|
|
- [📁 Lizenz](#-lizenz)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🔧 Projektstruktur
|
|||
|
|
|
|||
|
|
```plaintext
|
|||
|
|
|
|||
|
|
📁 template-root/
|
|||
|
|
├── 📁 .vscode/ # Projekteinstellungen VS-Code
|
|||
|
|
│ ├── 📄 settings.json # Einstellungen
|
|||
|
|
│ └── 📄 extensions.json # Erweiterungen
|
|||
|
|
├── 📄 .env # Projektkonfiguration (optional, nicht im git)
|
|||
|
|
├── 📄 .env.example # Vorlage der .env
|
|||
|
|
├── 📄 requirements.txt # Abhängigkeiten (z.B. python-dotenv)
|
|||
|
|
├── 📄 README.md # diese Datei
|
|||
|
|
├── 📄 CHANGELOG.md #
|
|||
|
|
├── 📄 VERSION # Versionsinfo zum Paket
|
|||
|
|
├── 📄 run.py # Einstiegspunkt für die Anwendung
|
|||
|
|
├── 📁 media/
|
|||
|
|
│ └── 📄 logo.png # Logo für GitHub
|
|||
|
|
└── 📁 app/
|
|||
|
|
├── 📄 __init__.py #
|
|||
|
|
├── 📄 main.py # Hauptlogik der Anwendung
|
|||
|
|
└── 📄 bootstrap.py # Setup- und Relaunch-Logik
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> Release-Pakete als `.zip` sind bereits von unötigem Balast bereinigt. Die dargestellte Struktur entspricht einem `git clone`.
|
|||
|
|
|
|||
|
|
[🔝](#-inhalt-der-readme)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🚀 Erste Schritte
|
|||
|
|
|
|||
|
|
- [ ] `.env.example` in `.env` umbenennen und individuell befüllen.
|
|||
|
|
- [ ] `.vscode`-Verzeichnis löschen, wenn du eigene Einstellungen nutzt. Ich habe es versehentlich committet und aus Bequemlichkeit drin gelassen, weil es meinem Standard entspicht.
|
|||
|
|
- [ ] `requirements.txt` auf deine Bedürfnisse anpassen.
|
|||
|
|
- [ ] `media/`Verzeichnis Löschen falls vorhanden.
|
|||
|
|
|
|||
|
|
**Erster Start des Templates:**
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python run.py
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Beim ersten Start passiert:
|
|||
|
|
|
|||
|
|
1. `.venv` wird erstellt (wenn noch nicht vorhanden)
|
|||
|
|
2. `requirements.txt` wird installiert
|
|||
|
|
3. Das Skript wird automatisch innerhalb der venv neu gestartet
|
|||
|
|
4. `.env` wird geladen (falls vorhanden)
|
|||
|
|
5. **Die App startet 🚀**
|
|||
|
|
|
|||
|
|
> Es erfolgen einige Ausgaben, die alle aus der `main.py` stammen, außer du `DEBUG` in der `.env` aktiviert hast.
|
|||
|
|
|
|||
|
|
[🔝](#-inhalt-der-readme)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📦 Abhängigkeiten
|
|||
|
|
|
|||
|
|
Alle Abhängigkeiten werden aus `requirements.txt` installiert.
|
|||
|
|
**Beispiel:**
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
python-dotenv
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
[🔝](#-inhalt-der-readme)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## ⚙️ .env-Datei (optional)
|
|||
|
|
|
|||
|
|
Wenn vorhanden, wird `.env` automatisch geladen.
|
|||
|
|
**Beispiel:**
|
|||
|
|
|
|||
|
|
```dotenv
|
|||
|
|
APP_MODE=development
|
|||
|
|
LOGLEVEL=debug
|
|||
|
|
PORT=8080
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Diese Werte sind im Code über `os.getenv("APP_MODE")` verfügbar.
|
|||
|
|
|
|||
|
|
[🔝](#-inhalt-der-readme)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📜 Beispielausgabe
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
[BOOTSTRAP] Erstelle virtuelle Umgebung...
|
|||
|
|
[BOOTSTRAP] Installiere pip + requirements.txt...
|
|||
|
|
[BOOTSTRAP] Starte in virtueller Umgebung neu...
|
|||
|
|
[RUN] Lade .env aus: ./cliqrcode/.env
|
|||
|
|
[APP] Starte Anwendung im Modus: development
|
|||
|
|
[APP] Hello, world!
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
[🔝](#-inhalt-der-readme)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🪵 Logging
|
|||
|
|
|
|||
|
|
Dieses Template verwendet ein integriertes Logging-Modul mit folgenden Eigenschaften:
|
|||
|
|
|
|||
|
|
- Ausgabe in die Konsole (immer aktiv)
|
|||
|
|
- Optionale Ausgabe in eine Logdatei (`LOGFILE`)
|
|||
|
|
- Unterstützung für rotierende Logdateien
|
|||
|
|
- Loglevel konfigurierbar über `.env`
|
|||
|
|
- Plattformunabhängig (Windows, Linux, macOS)
|
|||
|
|
- Keine externen Abhängigkeiten
|
|||
|
|
|
|||
|
|
### 🔧 Konfiguration (in `.env`)
|
|||
|
|
|
|||
|
|
```dotenv
|
|||
|
|
LOGLEVEL=INFO # Möglich: DEBUG, INFO, WARNING, ERROR, CRITICAL
|
|||
|
|
LOGFILE=logs/app.log # Optionaler Pfad zur Logdatei (relativ oder absolut)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> Wenn `LOGFILE` nicht gesetzt ist, wird nur in die Konsole geloggt.
|
|||
|
|
|
|||
|
|
### 📥 Beispielausgabe
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
[2025-04-23 14:10:00] INFO app.main: Template ready.
|
|||
|
|
[2025-04-23 14:10:00] DEBUG app.main: Dies ist eine Debug-Meldung.
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 📌 Logik im Code
|
|||
|
|
|
|||
|
|
In beliebigen Modulen kannst du so einen Logger verwenden:
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
from app.logging_utils import get_logger
|
|||
|
|
|
|||
|
|
log = get_logger(__name__)
|
|||
|
|
log.info("Template ready.")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 📁 Logrotation
|
|||
|
|
|
|||
|
|
Die Logdatei wird bei 1 MB automatisch rotiert (max. 3 Backups), z. B.:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
logs/app.log
|
|||
|
|
logs/app.log.1
|
|||
|
|
logs/app.log.2
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
[🔝](#-inhalt-der-readme)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🛠 Hinweise
|
|||
|
|
|
|||
|
|
- Das Template ist portabel und benötigt keine global installierten Pakete.
|
|||
|
|
- Du kannst es für jede neue App wiederverwenden.
|
|||
|
|
- `run.py` ist der einzige Einstiegspunkt – keine direkten Aufrufe von `main.py`.
|
|||
|
|
|
|||
|
|
[🔝](#-inhalt-der-readme)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🧪 Getestet mit
|
|||
|
|
|
|||
|
|
- Python 3.11, 3.12, 3.13
|
|||
|
|
- Windows & Linux
|
|||
|
|
- VS Code, Terminal, PowerShell
|
|||
|
|
|
|||
|
|
[🔝](#-inhalt-der-readme)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🛠 Einsatz von `Linter` (`pylint`)
|
|||
|
|
|
|||
|
|
```cmd
|
|||
|
|
PS C:\Users\adams\Documents\template> .\.venv\Scripts\activate
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```cmd
|
|||
|
|
(.venv) PS C:\Users\adams\Documents\template> pylint.exe run.py
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```cmd
|
|||
|
|
************* Module run
|
|||
|
|
run.py:27:4: C0412: Imports from package app are not grouped (ungrouped-imports)
|
|||
|
|
run.py:12:0: W0611: Unused import os (unused-import)
|
|||
|
|
|
|||
|
|
-----------------------------------
|
|||
|
|
Your code has been rated at 8.33/10
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Bonus:**
|
|||
|
|
Durch den Einsatz der <.vscode/task.json> für VS-Code, kannst du in VS-Code mit `Strg + Umschalt + P` → `Tasks: Run Task` → `Linter (pylint)` oder `Typprüfung (mypy)` aufrufen.
|
|||
|
|
|
|||
|
|
[🔝](#-inhalt-der-readme)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📁 Lizenz
|
|||
|
|
|
|||
|
|
MIT – frei verwendbar in eigenen Projekten.
|