refactor: update contents for coding conventions

ch05construction/02conventions.ipynb.py

@@ -13,17 +13,7 @@
 
 # %% [markdown]
 # ## Coding Conventions
-
-# %% [markdown]
-# Let's import first the context for this chapter.
-
-# %%
-from context import *
-
-# %% [markdown]
 # ### One code, many layouts:
-
-# %% [markdown]
 #
 # Consider the following fragment of python:
 #
@@ -145,6 +135,8 @@ def method_name(a_variable):
 #
 
 # %%
+sEntry = "10.0"
+iOffset = 1
 fNumber = float(sEntry) + iOffset
 
 # %% [markdown]
@@ -153,6 +145,8 @@ def method_name(a_variable):
 # People may find this useful in languages like Python where the type is intrisic in the variable.
 
 # %%
+entry = "10.0"
+offset = 1
 number = float(entry) + offset
 
 # %% [markdown]
@@ -173,6 +167,13 @@ def method_name(a_variable):
 # The following two snippets do the same, but the second is separated into more steps, making it more readable.
 
 # %%
+anothervariable=1
+flag1 = True
+flag2 = False
+variable = 1
+anothervariable = 1
+def do_something(): pass
+
 anothervariable += 1
 if ((variable == anothervariable) and flag1 or flag2): do_something()
 
@@ -219,43 +220,48 @@ def method_name(a_variable):
 #
 # There are automated tools which enforce coding conventions and check for common mistakes.
 #
-# These are called **linters**. A popular one is [pycodestyle](https://pypi.org/project/pycodestyle/):
-#
-# E.g. `pip install pycodestyle` 
-#
-#
-#
+# These are called ** formatters** and **linters**. Some widely used linters and formatters in the Python ecosystem ar -
+#  - [pycodestyle](https://pypi.org/project/pycodestyle/): check your code against PEP8
+#  - [pylint](https://www.pylint.org/): useful information about the quality of your code
+#  - [black](https://github.com/psf/black): code formatter written in Python
+#  - [ruff](https://github.com/astral-sh/ruff): blazing fast code formatter and linter written in Rust with ideas borrowed from Pythonic linters and formatters
 
-# %% magic_args="--no-raise-error" language="bash"
-# pycodestyle species.py
 
 # %% [markdown]
-#
-#
-#
-# It is a good idea to run a linter before every commit, or include it in your CI tests.
-#
-#
+# Most of such tools can be directly used on Python files / repositories using a CLI utility. For instance -
 
-# %% [markdown]
-# There are other tools that help with linting that are worth mentioning.
-# With [pylint](https://www.pylint.org/) you can also get other useful information about the quality of your code:
-#
-# `pip install pylint` 
-#
+
+# %% magic_args="--no-raise-error" language="bash"
+# pycodestyle species.py
 
 # %% magic_args="--no-raise-error" language="bash"
 # pylint species.py
 
+# %% magic_args="--no-raise-error" language="bash"
+# ruff check species.py
+
 # %% [markdown]
-# and with [black](https://black.readthedocs.io/) you can fix all the errors at once.
-# ```bash
-# black species.py
-# ```
 # These linters can be configured to choose which points to flag and which to ignore.
 #
 # Do not blindly believe all these automated tools! Style guides are **guides** not **rules**.
 
 # %% [markdown]
-# Finally, there are tools like [editorconfig](https://editorconfig.org/) to help sharing the conventions used within a project, where each contributor uses different IDEs and tools. There are also bots like [pep8speaks](https://pep8speaks.com/) that comments on contributors' pull requests suggesting what to change to follow the conventions for the project.
+#
+# It is a good idea to run a linter before every commit, or include it in your CI tests.
+#
+# [`pre-commit`](https://pre-commit.com) allows developers to add tools like linters and formatters
+# as git hooks, such that they run before every commit. The hooks can be installed locally using -
+# 
+# ```bash
+# pip install pre-commit
+# pre-commit install  # provided a .pre-commit-config.yaml is present in your repository
+# ```
+# 
+# This would run the checks every time a commit is created locally. The checks will only run on the files
+# modified by that commit.
+
+
+# %% [markdown]
+# Finally, there are tools like [editorconfig](https://editorconfig.org/) to help sharing the conventions used within a project, where each contributor uses different IDEs and tools.
+# There are also bots like [pep8speaks](https://pep8speaks.com/) and [pre-commit.ci](https://pre-commit.ci) that comments/run checks on contributors' pull requests suggesting what to change to follow the conventions for the project.
 #

requirements.txt

@@ -25,3 +25,4 @@ imageio
 pycodestyle
 pylint
 webcolors
+ruff