Python Biella Group: Bear

Base Environment for Any Reasonable project

· Riporta un bug · Richiedi una feature o un miglioramento

Elenco dei contenuti

1. Il progetto
2. Il progetto
3. Costruito con
4. Roadmap
5. Utilizzo
6. Come mantenerlo
7. Documentazione tecnica
8. Contribuire
9. Licenza
10. Problemi riscontrati
11. Contatti
12. 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

• 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
• Aggiungere e migliorare pre-commit
• Migliore implementazione di detect-secrets
• Aggiungere un sistema per controllare l'update delle dipendenze, vulnerabilità e problemi di sicurezza
• Miglioramento del README e nuova sezione su come contribuire
• Aggiornare il docker dell'applicazione con Poetry
• Aggiornare il devcontainer
• Esempio di pipeline con gitlab
• Esempio di pipeline con github
• 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 [email protected]: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 [email protected]: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.

1. Clona la repository (oppure fai un fork e successivamente una pull request)
2. Lancia l'installazione delle dipendenze utilizzando poetry
   1. poetry install
3. Modifica quello che è necessario
4. 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
5. 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)

Contatti

Reach out the community of PythonBiellaGroup!

(Torna all'inizio)

References

Useful links and other documentation website you can check

• Our website with the documentation
• The repository for our documentation
• Hypermodern python repository
• The hypermodern python official medium article
• Modern Python repository
• Awesome Pyproject
• Python developer roadmap
• Creating a modern python development environment medium article
• Modern python interesting practices
• 4 Keys to write modern python in 2022
• cookiecutter-poetry good implementation
• dev container video tutorial
• Ruff official documentation
• Ruff vscode extension
• Chef repository with some more modern tooling

(back to top)