[![Contributors][contributors-shield]][contributors-url] [![Forks][forks-shield]][forks-url] [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] [![MIT License][license-shield]][license-url]

Python Biella Group: Bear

Base Environment for Any Reasonable project

· Riporta un bug · Richiedi una feature o un miglioramento

Elenco dei contenuti

Il progetto
Il progetto
Costruito con
Roadmap
Utilizzo
Come mantenerlo
Documentazione tecnica
Contribuire
Licenza
Problemi riscontrati
Contatti
References

Il progetto

Questo progetto è un template base per ogni Progetto Python che utilizziamo in tutte le repository di Python Biella Group per creare strumenti, librerie e progetti.

Lo abbiamo chiamato: Bear come acronimo di: Base Environment for Any Reasonable project e anche perchè bear (l'orso) è il simbolo della città di Biella in Italia (Piemonte).

Requisiti

Per questo progetto sono necessari i seguenti requisiti che devono essere installati:

Python: >=3.10 <=3.12
Poetry: >= 1.8.1

Raccomandiamo di installare Poetry utilizzando Pyenv, seguendo la guida ufficiale sul sito.

Costruito con

Il progetto è basato sullo stack tecnologico moderno di Python come:

cookiecutter: per la gestione del template
poetry: per la gestione delle dipendenze
ruff: per il linting e il controllo del codice
mypy: per lo static type checking
black: per la formattazione del codice (anche se può farlo ruff)
bandit: per i controlli di sicurezza del codice (anche se può farlo ruff)
pre-commit: per la gestione dei test e dei controlli pre-commit.
pydantic: per il type checking evoluto
pydantic-settings: per la gestione delle configurazioni

Suggeriamo di utilizzare VSCode come IDE per questo progetto in quanto puoi trovare una serie di configurazioni pronte per:

debugging
testing
settings
extensions
sviluppo nei containers

Puoi trovare un'estensiva documentazione aggiuntiva creata con mkdocs disponibile sul nostro sito

Roadmap

[x] Aggiornare cookiecutter in modo che possa funzionare anche su windows con powershell
[ ] Aggiornare l'implementazione di mkdocs sul pacchetto Base con gli esempi di codice Python
[ ] Pubblicare l'esempio della documentazione di mkdocs su github page
[ ] Aggiungere l'implementazione e i comandi di sphynx in modo da scegliere tra mkdocs e sphynx durante l'installazione
[x] Aggiungere e migliorare pre-commit
[ ] Migliore implementazione di detect-secrets
[ ] Aggiungere un sistema per controllare l'update delle dipendenze, vulnerabilità e problemi di sicurezza
[x] Miglioramento del README e nuova sezione su come contribuire
[x] Aggiornare il docker dell'applicazione con Poetry
[x] Aggiornare il devcontainer
[ ] Esempio di pipeline con gitlab
[ ] Esempio di pipeline con github
[x] Possibilità di fare la build del pacchetto con Poetry
[ ] Test incrociati su diverse versioni di Python utilizzando tox

Guarda le open issues per la lista di feature e miglioramenti proposti (oltre ai problemi degli altri utenti).

(torna all'inizio)

Utilizzo

Puoi utilizzare questa repository come template per creare i tuoi progetti Python con cookiecutter

Come prima cosa ricordati di installare cookiecutter come dipendenza nella tua versione locale di Python utilizzando pip.

pip install cookiecutter

Puoi utilizzare i seguenti comandi per scaricare e configurare il progetto in locale (funziona sia su Windows che sistemi Posix)

# Se usi https
cookiecutter https://github.com/PythonBiellaGroup/Bear.git

# Se usi ssh
cookiecutter git@github.com:PythonBiellaGroup/Bear.git

Una volta lanciato il comando segui la guida nel terminale per riempire i campi e configurare il progetto.

Puoi anche creare un alias per questo comando nel tuo terminale, rendendo più facile il download:

# Se stai utilizzando https
alias pbg-project="cookiecutter https://github.com/PythonBiellaGroup/Bear.git --overwrite-if-exists"

# Se hai configurato ssh
alias pbg-project="cookiecutter git@github.com:PythonBiellaGroup/Bear.git --overwrite-if-exists"

Una volta configurato l'alias e riaperto il terminale puoi usare semplicemente il comando: pbg-project per scaricare il template e creare il nuovo progetto.

(Torna all'inizio)

Come mantenerlo

Sfortunatamente non c'è un modo automatico per aggiornare il template cookiecutter, quindi è necessario fare gli aggiornamenti manualmente.

Clona la repository (oppure fai un fork e successivamente una pull request)
Lancia l'installazione delle dipendenze utilizzando poetry
1. poetry install
Modifica quello che è necessario
Se vuoi testare il template interno puoi lanciare il comando: make bake-test per testare la generazione del progetto con cookiecutter, dopo di che:
1. Modifica il template nella nuova finestra di vscode che si aprirà
2. Quando hai finito le modifiche ricordati di copiare (a mano) i cambiamenti nella repository originale all'interno del template
Infine apri una pull request oppure fai un push nella repository (meglio prima in develop) se hai i permessi.

Ricordati di seguire il Gitlflow workflow e di usare la branch develop per sviluppare invece di main.

Prima di pubblicare una nuova versione su main o di fare una pull request cerca di testare che tutto funzioni bene.

(Torna all'inizio)

Documentazione tecnica

Utilizziamo mkdocs per creare la documentazione di questo progetto

per lanciare la documentazione in locale usa il comando:

mkdocs serve

Se vuoi prepare la build degli artefatti prima di rilasciare su github pages puoi lanciare:

mkdocs build

Per altre informazioni su mkdocs rimandiamo alla repository del nostro sito realizzata interamente in mkdocs e un buon esempio di come si può configurare website

(Torna all'inizio)

Contribuire

Puoi contribuire a questo progetto aprendo delle issue su github o facendo delle pull request per aggiungere nuove funzionalità o correggere alcuni bugs.

Per favore segui le linee guide Contributing guidelines per contribuire al progetto.

(Torna all'inizio)

Licenza

Questa repository utilizza la licenza MIT. Guarda il file: LICENSE per ulteriori dettagli.

Se utilizzi questa repository per il tuo lavoro per favore citaci oppure scrivi solamente un messaggio sui nostri canali di comunicazione per ringraziarci e darci un feedback sulla tua esperienza :)

(Torna all'inizio)

Problemi riscontrati

Su mac se vuoi utilizzare devcontainer con vscode probabilmente dovrai aspettare parecchio la prima volta. Questo è causato da amd64 docker base image che stiamo utilizzando come baseline e perchè il mac la deve virtualizzare utilizzando Rosetta.

(Torna all'inizio)