Elenco dei contenuti
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).
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.
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
- 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).
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 cookiecutterPuoi 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.gitUna 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.
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
poetry install
- Modifica quello che è necessario
- Se vuoi testare il template interno puoi lanciare il comando:
make bake-testper testare la generazione del progetto con cookiecutter, dopo di che:- Modifica il template nella nuova finestra di vscode che si aprirà
- 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.
Utilizziamo mkdocs per creare la documentazione di questo progetto
per lanciare la documentazione in locale usa il comando:
mkdocs serveSe vuoi prepare la build degli artefatti prima di rilasciare su github pages puoi lanciare:
mkdocs buildPer altre informazioni su mkdocs rimandiamo alla repository del nostro sito realizzata interamente in mkdocs e un buon esempio di come si può configurare website
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.
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 :)
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.
Reach out the community of PythonBiellaGroup!
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