Skip to content

Latest commit

 

History

History
233 lines (170 loc) · 9.41 KB

README-en.md

File metadata and controls

233 lines (170 loc) · 9.41 KB

Contributors Forks Stargazers Issues MIT License

Python Biella Group: Bear

Base Environment for Any Reasonable project


📙 Explore the docs

View Demo · Report Bug · Request Feature

Table of Contents
  1. About The Project
  2. Built With
  3. Roadmap
  4. Usage
  5. How to maintain it
  6. Technical Documentation
  7. Contributing
  8. License
  9. Known issues
  10. Contacts
  11. References

About The Project

This project it's the base template for a Python project that we are using in PythonBiellaGroup to create our tools, libraries and projects.

We call it Bear because it's a Base Environment for Any Reasonable project and also because the bear is the symbol of the city of Biella (Piedmont) Italy.

Requirements

For this project it's required to have installed:

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

We recommend to install Poetry using Pyenv (following the official instructions).

Built With

It's based on Modern Python Tools such as:

  • cookiecutter: for templating
  • poetry: for dependency management
  • mypy: for static type checking
  • black: for code formatting
  • bandit: for security checks
  • pre-commit: for pre-commit hooks
  • ruff: for linting
  • pydantic: for type checking
  • pydantic-settings: for the setting management

We suggest to use VSCode as IDE for this project since you can find a lot of prepared configurations for:

  • debugging
  • testing
  • settings
  • extensions
  • testone

You can find and extensive documentation created with mkdocs to this github page link

Roadmap

  • Fix cookiecutter for windows powershell usage
  • Add mkdocs implementation on Base package with an example with python code
  • Publish mkdocs documentation page on gitlab pages
  • Add sphynx implementation with cookiecutter rule to choose between mkdocs and sphynx
  • Fix pre-commit
  • Add better implementation of detect-secrets
  • Add a system to check dependencies updates, vulnerabilities and security issues
  • Better README documentation and CONTRIBUTING documentation
  • Fix the docker with poetry
  • Fix the devcontainer
  • Add a docker container with PDM installation
  • Add gitlab pipeline example
  • Add github pipeline example
  • Add package build

See the open issues for a full list of proposed features (and known issues).

(back to top)

Usage

You can use this repository as a template to create your own project with cookiecutter

Just remember to add cookiecutter as a dependency into your local version installation of python using pip (or something else).

pip install cookiecutter

You can use this following command (both on Windows and Posix systems):

# If you are using https
cookiecutter https://github.com/PythonBiellaGroup/Bear.git

# If you are using ssh
cookiecutter [email protected]:PythonBiellaGroup/Bear.git

once you launch this commands just follow the guide and fill the required fields.

You can also create an Alias for this command to make it easier to use it in your terminal:

# If you are using https
alias pbg-project="cookiecutter https://github.com/PythonBiellaGroup/Bear.git --overwrite-if-exists"

# If you are using ssh
alias pbg-project="cookiecutter [email protected]:PythonBiellaGroup/Bear.git --overwrite-if-exists"

so you can use simply the command: pbg-project after you restart your terminal to download and create a new project.

(back to top)

How to maintain it

Unfortunately there is no automatic way to update the templates inside cookiecutter yet, you have to do it manually.

  1. Clone the repository
  2. Launch the dependency installation using: poetry or pdm
    1. poetry install
    2. or pdm install
  3. Modify something
  4. If you want to test a specific inner template (like the Base template) you can launch: cookiecutter . to test cookiecutter project generation
    1. After that you can modify the template
    2. When you finish your modification you have to copy and paste all the modifications manually inside the cookiecutter generation folder
  5. Then remember to open a pull request or push to the repository (in develop firtst) if you have the permissions.

Please remember also to follow a Gitflow workflow and to use the develop branch as the main branch for development.

(back to top)

Technical Documentation

We use mkdocs to create the documentation for this project.

To launch the documentation locally:(remember to install the python env with poetry or pdm before):

mkdocs serve

If you want to prepare the build artifacts for the gitlab pages documentation, you have to run:

mkdocs build

(back to top)

Contributing

You can help us to improve this project by opening issues or doing some pull request if you want to add more functionalities or if you want to fix some bugs.

Please follow the Contributing guidelines to contribute to this project.

(back to top)

License

This repository is licensed under the MIT license. See LICENSE file for details.

If you use this repository in your work, please cite it as or just write to us to say thanks with your feedback and experience :)

(back to top)

Known issues

With mac if you want to use devcontainer with vscode probably you will experience a long building time on the first time. This is due to the amd64 base docker image we are using as a baseline.

(back to top)

Contacts

Reach out the community of PythonBiellaGroup!

Contacts

(back to top)

References

Useful links and other documentation website you can check

(back to top)