Merge pull request #364 from RWTH-EBC/341-Introduce-pre-commit-hook-a…

…nd-formatter

341 introduce pre commit hook and formatter

.gitignore

@@ -14,6 +14,7 @@ __pycache__
 !.github/issue-branch.yml
 
 *.yaml
+!.pre-commit-config.yaml
 
 # pip install #
 #####################

.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+  # Using black mirror since it's 2x faster https://black.readthedocs.io/en/stable/integrations/source_version_control.html
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 24.10.0
+    hooks:
+      - id: black
+        # Specifying the latest version of Python supported by Filip
+        language_version: python

CONTRIBUTING.md

@@ -34,6 +34,29 @@ We use PEP8 as a coding style guide. Some IDEs (like PyCharm) automatically show
 
 For committing style guide please use Conventional Commits 1.0.0. For more details how to structure your commits please visit this [page](https://www.conventionalcommits.org/en/v1.0.0/).
 
+### Pre-commit Hooks
+
+In order to make the development easy and uniform, use of pre-commit is highly recommended. The pre-commit hooks run before every commit to ensure the code is compliant with the project style.
+
+Check if pre-commit is installed:
+```bash
+pre-commit --version
+```
+Install pre-commit via pip if it's not already installed.
+```bash
+pip install pre-commit~=4.0.1
+```
+Install the git hook scripts:
+```bash
+pre-commit install
+```
+This will run pre-commit automatically on every git commit. Checkout [pre-commit-config.yaml](.pre-commit-config.yaml) file to find out which hooks are currently configured.
+
+> **Note:** Currently we are using the pre-commit to perform black formatter. You can perform a formatting to all files by running the following command:
+> ```bash
+> pre-commit run black --all-files
+> ```
+
 ## Documentation
 
 All created or modified functions should be documented properly. 

README.md

@@ -84,10 +84,11 @@ If you want to benefit from the latest changes, use the following command
 pip install -U git+git://github.com/RWTH-EBC/filip
 ```
 
-> **Note**: For local development, you can install the library in editable mode with the following command:
-> ````
-> pip install -e .
+> **Note**: For development, you should install FiLiP in editable mode with the following command:
+> ````bash
+> pip install -e .[development]
 > ````
+> The `development` option will install extra libraries required for contribution. Please check the [CONTRIBUTING.md](CONTRIBUTING.md) for more information. 
 
 #### Install semantics module (optional)
 

docs/source/conf.py

@@ -11,31 +11,38 @@
 import sys
 import datetime
 from pathlib import Path
+
 # pylint: disable-all
 
-sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath("../.."))
 sys.setrecursionlimit(1500)
 
 # -- Project information -----------------------------------------------------
 
-project = 'FiLiP'
-copyright = f'2021-{datetime.datetime.now().year}, RWTH Aachen University, ' \
-            f'E.ON Energy Research Center, ' \
-            f'Institute for Energy Efficient Buildings and Indoor Climate'
-author = 'E.ON ERC - EBC'
+project = "FiLiP"
+copyright = (
+    f"2021-{datetime.datetime.now().year}, RWTH Aachen University, "
+    f"E.ON Energy Research Center, "
+    f"Institute for Energy Efficient Buildings and Indoor Climate"
+)
+author = "E.ON ERC - EBC"
 
 # The full version, including alpha/beta/rc tags
 # Get the version from FiliP/filip/__init__.py:
 with open(Path(__file__).parents[2].joinpath("filip", "__init__.py"), "r") as file:
     for line in file.readlines():
         if line.startswith("__version__"):
-            release = line.replace("__version__", "").split("=")[1].strip().replace(
-                "'", "").replace(
-                '"', '')
+            release = (
+                line.replace("__version__", "")
+                .split("=")[1]
+                .strip()
+                .replace("'", "")
+                .replace('"', "")
+            )
 release = release
 
 # The short X.Y version.
-version = '.'.join(release.split('.')[0:2])
+version = ".".join(release.split(".")[0:2])
 
 
 # -- General configuration ------------------------------------------------
@@ -47,28 +54,29 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.inheritance_diagram',
-              'sphinx.ext.intersphinx',
-              'sphinx.ext.ifconfig',
-              'sphinx.ext.viewcode',
-              'sphinx.ext.githubpages',
-              'sphinx.ext.coverage',
-              'm2r2',  # Enable .md files
-              'sphinx.ext.napoleon',  # Enable google docstrings
-              'sphinxcontrib.autodoc_pydantic'  # add support for pydantic
-              ]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.inheritance_diagram",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.coverage",
+    "m2r2",  # Enable .md files
+    "sphinx.ext.napoleon",  # Enable google docstrings
+    "sphinxcontrib.autodoc_pydantic",  # add support for pydantic
+]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-source_suffix = ['.rst', '.md']
+source_suffix = [".rst", ".md"]
 
 # The master toctree document.
-master_doc = 'contents'
+master_doc = "contents"
 
 
 # The language for content autogenerated by Sphinx. Refer to documentation
@@ -84,7 +92,7 @@
 exclude_patterns = []
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'friendly'
+pygments_style = "friendly"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
@@ -104,7 +112,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -162,10 +170,7 @@
 # This is required for the material theme
 # Refs: https://bashtage.github.io/sphinx-material/index.html
 html_sidebars = {
-    "**": ["logo-text.html",
-           "globaltoc.html",
-           "localtoc.html",
-           "searchbox.html"]
+    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
 }
 
 # This is required for the alabaster theme
@@ -181,7 +186,7 @@
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'FiLiPdoc'
+htmlhelp_basename = "FiLiPdoc"
 
 
 # -- Options for LaTeX output ---------------------------------------------
@@ -190,15 +195,12 @@
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -208,19 +210,15 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'FiLiP.tex', 'FiLiP Documentation',
-     'EON EBC', 'manual'),
+    (master_doc, "FiLiP.tex", "FiLiP Documentation", "EON EBC", "manual"),
 ]
 
 
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'FiLiP', 'FiLiP Documentation',
-     [author], 1)
-]
+man_pages = [(master_doc, "FiLiP", "FiLiP Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output -------------------------------------------
@@ -229,9 +227,15 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'FiLiP', 'FiLiP Documentation',
-     author, 'FiLiP', 'FIWARE Library for Python',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "FiLiP",
+        "FiLiP Documentation",
+        author,
+        "FiLiP",
+        "FIWARE Library for Python",
+        "Miscellaneous",
+    ),
 ]
 
 # -- Options for Epub output ----------------------------------------------
@@ -252,8 +256,8 @@
 # epub_uid = ''
 
 # A list of files that should not be packed into the epub file.
-epub_exclude_files = ['search.html']
+epub_exclude_files = ["search.html"]
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {"https://docs.python.org/": None}

examples/basics/e01_http_clients.py

@@ -6,12 +6,10 @@
 
 # ## Import packages
 import requests
-from filip.clients.ngsi_v2 import \
-    ContextBrokerClient, \
-    IoTAClient, \
-    QuantumLeapClient
+from filip.clients.ngsi_v2 import ContextBrokerClient, IoTAClient, QuantumLeapClient
 from filip.models.base import FiwareHeader
 from filip.config import settings
+
 # ## Parameters
 #
 # Note: This example also reads parameters from the '.env.filip'-file
@@ -25,12 +23,12 @@
 #
 # Here you can also change the used Fiware service
 # FIWARE-Service
-service = 'filip'
+service = "filip"
 # FIWARE-Servicepath
-service_path = '/example'
+service_path = "/example"
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
 
     # # 1 FiwareHeader
     #
@@ -41,17 +39,15 @@
     # In short, a fiware header specifies a location in Fiware where the
     # created entities will be saved and requests are executed.
     # It can be thought of as a separate subdirectory where you work in.
-    fiware_header = FiwareHeader(service='filip',
-                                 service_path='/example')
+    fiware_header = FiwareHeader(service="filip", service_path="/example")
 
     # # 2 Client modes
     # You can run the clients in different modes:
     #
     # ## 2.1 Run it as a pure python object.
     #
     # This will open and close a connection each time you use a function.
-    cb_client = ContextBrokerClient(url=CB_URL,
-                                    fiware_header=fiware_header)
+    cb_client = ContextBrokerClient(url=CB_URL, fiware_header=fiware_header)
     print(f"OCB Version: {cb_client.get_version()}")
 
     # ## 2.2 Run the client via python's context protocol.
@@ -103,8 +99,7 @@
     # additional keyword arguments a requests.request would also take,
     # e.g. headers, params etc.
 
-    cb_client = ContextBrokerClient(url=CB_URL,
-                                    fiware_header=fiware_header)
+    cb_client = ContextBrokerClient(url=CB_URL, fiware_header=fiware_header)
 
     # # 5 Combined Client
     #

examples/basics/e02_baerer_token.py

@@ -12,20 +12,21 @@
 # Host address of Context Broker
 CB_URL = "https://localhost:1026"
 # FIWARE-Service
-fiware_service = 'filip'
+fiware_service = "filip"
 # FIWARE-Servicepath
-fiware_service_path = '/example'
+fiware_service_path = "/example"
 # FIWARE-Bearer token
 # TODO it has to be replaced with the token of your protected endpoint
-fiware_baerer_token = 'BAERER_TOKEN'
+fiware_baerer_token = "BAERER_TOKEN"
 
-if __name__ == '__main__':
-    fiware_header = FiwareHeaderSecure(service=fiware_service,
-                                       service_path=fiware_service_path,
-                                       authorization=f"""Bearer {
-                                       fiware_baerer_token}""")
-    cb_client = ContextBrokerClient(url=CB_URL,
-                                    fiware_header=fiware_header)
+if __name__ == "__main__":
+    fiware_header = FiwareHeaderSecure(
+        service=fiware_service,
+        service_path=fiware_service_path,
+        authorization=f"""Bearer {
+                                       fiware_baerer_token}""",
+    )
+    cb_client = ContextBrokerClient(url=CB_URL, fiware_header=fiware_header)
     # query entities from protected orion endpoint
     entity_list = cb_client.get_entity_list()
     print(entity_list)

examples/basics/e11_logging.py

@@ -8,8 +8,10 @@
 
 # import python's built-in logging implementation
 import logging
+
 # import an api client from filip as example
 from filip.clients.ngsi_v2 import ContextBrokerClient
+
 # setting up the basic configuration of the logging system. Please check the
 # official documentation and the functions docstrings for more details.
 # Handling for 'handlers' in the logging system is not trivial.
@@ -20,9 +22,9 @@
 
 # In this example we will simply change the log level and the log format.
 logging.basicConfig(
-    level='DEBUG',
-    format='%(asctime)s %(name)s %(levelname)s: %(message)s')
+    level="DEBUG", format="%(asctime)s %(name)s %(levelname)s: %(message)s"
+)
 
 # You need to change the output
-ocb = ContextBrokerClient(url='http://<PleaseChange.Me>')
+ocb = ContextBrokerClient(url="http://<PleaseChange.Me>")
 ocb.get_version()