Merge branch 'master' into feature/sentry

.gitignore

@@ -114,4 +114,7 @@ examples/ssl/clients/.index.bin
 
 # mkdocs
 doc/_build
-doc/env
+doc/env
+
+# macOS supplementary file
+.DS_Store

asab/log.py

@@ -447,11 +447,12 @@ def _on_write(self):
 		self._loop.remove_writer(self._socket)
 
 		while not self._queue.empty():
-			# TODO: Handle eventual error in writing -> break the cycle and restart on write handler
 			msg = self._queue.get_nowait()
-			msg = msg.encode("utf-8")
-			self._socket.sendall(msg)
-
+			try:
+				self._socket.sendall(msg)
+			except Exception as e:
+				print("Error when writing to syslog '{}'".format(self._address), e, file=sys.stderr)
+				self._enqueue(msg)
 
 	def _on_read(self):
 		try:
@@ -480,7 +481,7 @@ def emit(self, record):
 					self._enqueue(msg)
 
 			else:
-				self._enqueue(record)
+				self._enqueue(msg)
 
 
 		except Exception as e:

asab/tls.py

@@ -18,7 +18,7 @@ class SSLContextBuilder(Configurable):
 	ConfigDefaults = {
 		'cert': '',  # The certfile string must be the path to a PEM file containing the certificate as well as any number of CA certificates needed to establish the certificate’s authenticity.
 		'key': '',  # The keyfile string, if present, must point to a file containing the private key in. Otherwise the private key will be taken from certfile as well.
-		'password': '',
+		'key_password': '',
 
 		# Following three options are fed into SSLContext.load_verify_locations(...)
 		'cafile': '',
@@ -55,16 +55,16 @@ def build(self, protocol=ssl.PROTOCOL_TLS) -> ssl.SSLContext:
 		if len(keyfile) == 0:
 			keyfile = None
 
-		password = self.Config.get("password")
-		if len(password) == 0:
-			password = None
+		key_password = self.Config.get("key_password")
+		if len(key_password) == 0:
+			key_password = None
 
 		cert = self.Config.get("cert")
 		if len(cert) != 0:
 			ctx.load_cert_chain(
 				cert,
 				keyfile=keyfile,
-				password=password,
+				password=key_password,
 			)
 
 		cafile = self.Config.get("cafile")

docs.Dockerfile

@@ -0,0 +1,9 @@
+FROM squidfunk/mkdocs-material
+RUN pip3 install mkdocs-print-site-plugin \
+mkdocs-awesome-pages-plugin \
+mkdocs-glightbox \
+mkdocs-autorefs \
+mkdocs-diagrams \
+mkdocs-git-revision-date-localized-plugin \
+mkdocstrings \
+mkdocstrings-python

docs/contributing.md

@@ -5,8 +5,8 @@ We appreciate your effort to help us improve ASAB. In case you are interested in
 
 ## Coding conventions
 
-In TeskaLabs, we are following [PEP8 Style Guide](https://www.python.org/dev/peps/pep-0008/) that provides guidelines and
-best practices on how to write Python code to improve its readability and consistency.
+At TeskaLabs, we follow the [PEP8 Style Guide](https://www.python.org/dev/peps/pep-0008/), which provides guidelines and
+best practices on writing Python code for improved readability and consistency.
 
 To check if changes in your code are compliant with PEP8, you can use [flake8](https://flake8.pycqa.org/en/latest/):
 
@@ -30,7 +30,7 @@ flake8 .
     chmod u+x .git/hooks/pre-commit
     ```
 
-We shall provide some parts of the PEP8 Style Guide that we are focused on.
+These are the parts of the PEP8 Style Guide we care about the most:
 
 ### Tabs
 
@@ -40,23 +40,23 @@ We use tabs as an indentation method. Do not mix them with spaces!
 
 Surround top-level function and class definitions with two blank lines.
 
-Method definitions inside a class are surrounded by a single blank line.
+Surround method definitions inside a class with a single blank line.
 
-Extra blank lines may be used (sparingly) to separate groups of related functions. Blank lines may be omitted between a bunch of related one-liners (e.g. a set of dummy implementations).
+You may use extra blank lines (sparingly) to separate groups of related functions. You can omit blank lines between a bunch of related one-liners (e.g. a set of dummy implementations).
 
 Use blank lines in functions, sparingly, to indicate logical sections.
 
 ### Imports
 
-Imports shall be written one-per-line style as per the example below
+Write imports one-per-line style as per the example:
 
 ```python
 import os
 import sys
 import logging
 ```
 
-Following additional rules apply for imports:
+Also:
 
 1. Use **relative imports** when you import locally from a package.
 2. Use **absolute imports** when you import from external package.
@@ -66,13 +66,13 @@ used for importing symbols that you want to expose as a given module public API.
 
 ## Documentation conventions
 
-As a documentation engine, we use [mkdocs-material](https://squidfunk.github.io/mkdocs-material/). If you want to learn about various features provided by the engine, you can [read more](https://squidfunk.github.io/mkdocs-material/reference/).
+We use [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) as our documentation engine. To learn about features, visit the [reference page](https://squidfunk.github.io/mkdocs-material/reference/).
 
-MkDocs uses markdown for writing documentation.
+MkDocs uses Markdown for writing documentation.
 
 ### Docstrings formatting
 
-In order for the automatic documentation to be generated without errors, [Google style docstring guide](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) must be followed. Here is an example of the properly documented function:
+In order for the automatic documentation to be generated without errors, [Google style docstring guide](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) must be followed. Here is an example of a properly documented function:
 
 ```python
 def fetch_smalltable_rows(
@@ -114,7 +114,7 @@ def fetch_smalltable_rows(
 
 
 !!! tip
-    If you use code annotations, it will be automatically incorporated into the documentation. In case you for some reason do not want to use them and still would like to have type hints in documentation, you can manually add them like this:
+    Code annotations will be automatically incorporated into the documentation. If you don't want to use code annotations and would still like to have type hints in documentation, you can manually add them like this:
 
     ```python
     def sum_of_squares(a, b):

docs/getting-started/containers.md

@@ -1,9 +1,6 @@
-# Containerisation
+# Containerization
 
-ASAB is designed for deployment into containers such as LXC/LXD or
-Docker. It allows to build e.g. microservices that provides REST
-interface or consume MQ messages while being deployed into a container
-for a sake of the infrastructure flexibility.
+ASAB is designed for deployment into containers such as LXC/LXD or Docker. ASAB allows you to build microservices that provide REST APIs or consume MQ messages while being deployed into a container for the sake of the infrastructure flexibility.
 
 ## Running ASAB in a LXC/LXD container
 
@@ -58,7 +55,7 @@ for a sake of the infrastructure flexibility.
     ```
 
     !!! note
-        If you need to install python packages that require compilation
+        If you need to install Python packages that require compilation
         using C compiler, you have to add following dependencies:
 
         ``` bash
@@ -77,17 +74,17 @@ for a sake of the infrastructure flexibility.
 
 In order for ASAB applications to read the Docker container name as well
 as other information related to the container to be used in logs,
-metrics and other analysis, the Docker Remote API must be enabled. To do so:
+metrics, and other analysis, the Docker Remote API must be enabled. To enable the Docker Remote API:
 
-1.  Open the docker service file:
+1.  Open the Docker service file:
 
     ``` bash
     vi /lib/systemd/system/docker.service
     ```
 
 2.  Find the line which starts with `ExecStart` and add `-H=tcp://0.0.0.0:2375`.
 3.  Save the file.
-4.  Reload the docker daemon and restart the Docker service:
+4.  Reload the Docker daemon and restart the Docker service:
 
     ``` bash
     sudo systemctl daemon-reload && sudo service docker restart
@@ -103,5 +100,5 @@ metrics and other analysis, the Docker Remote API must be enabled. To do so:
 
 Thus, the metric service as well as log manager can use the container
 name as hostname instead of container ID, which provides better
-readability when analyzing the logs and metrics, typically using
+readability when analyzing the logs and metrics, typically when using
 InfluxDB and Grafana.

docs/getting-started/installation_first_app.md

@@ -2,25 +2,25 @@
 
 ## Installation
 
-ASAB is distributed via [pypi](https://pypi.org/project/asab/). For installing ASAB, there are three options you can choose from:
+ASAB is distributed via [pypi](https://pypi.org/project/asab/). There are three installation options:
 
 === "Using pip"
 
-    This is the simplest and recommended installation method.
+    We recommend using pip because it's the simplest installation method.
 
     ``` bash
     pip install asab
     ```
 
-=== "Cloning from git repository"
+=== "Cloning from the Git repository"
 
-    You can clone it from master branch using pip:
+    You can clone the repository from the master branch using pip:
 
     ``` bash
     pip install git+https://github.com/TeskaLabs/asab.git
     ```
 
-    Or you can clone the repository manually:
+    Or clone the repository manually:
 
     ``` bash
     git clone https://github.com/TeskaLabs/asab.git
@@ -30,7 +30,7 @@ ASAB is distributed via [pypi](https://pypi.org/project/asab/). For installing A
 
 === "Using EasyInstall"
 
-    You can install asab using [EasyInstall](http://peak.telecommunity.com/DevCenter/EasyInstall) package manager.
+    You can install asab using the [EasyInstall](http://peak.telecommunity.com/DevCenter/EasyInstall) package manager.
 
     ``` bash
     easy_install asab
@@ -56,30 +56,29 @@ ASAB is distributed via [pypi](https://pypi.org/project/asab/). For installing A
             app.run()
     ```
 
-    1.  ASAB application uses a Python 3.7+. This is specified a by hashbang
-    line at the very beginning of the file.
+    1. All ASAB applications use Python 3.7+. This is specified by a "hashbang" line at the very beginning of the file.
 
-    1. ASAB is included from as `asab` module via an import
+    2. ASAB is included from as `asab` module via an import
     statement.
 
-    1. Every ASAB Application needs to have an application object. It is a
+    3. Every ASAB Application needs to have an application object. It is a
     **singleton**: the application must create and operate
     precisely one instance of the application. ASAB provides the base
     [asab.Application][#TODO] class that you need to
     inherit from to implement your custom application class.
 
-    1. The `#!python Application.main()` method is one of
+    4. The `#!python Application.main()` method is one of
     the application lifecycle methods, that you can override to implement
     desired application functionality. The `main` method is a
-    coroutine, so that you can await any tasks etc. in fully asynchronous
-    way. This method is called when ASAB application is executed and
+    coroutine, so that you can await any tasks etc. in a fully asynchronous
+    way. This method is called when the ASAB application is executed and
     initialized. The lifecycle stage is called "runtime".
 
-    1. In this example, we just print a message to a screen.
+    5. In this example, the app is printing a message to the screen.
 
-    2. This part of the code is executed when the Python program is launched.
+    6. This part of the code is executed when you launch the Python program.
     It creates the application object and executes the `#!python run()` method which creates and runs an event loop. 
-    This is a standard way of how ASAB application is started.
+    This is the standard way of starting any ASAB application.
 
 
 2.  Run the server:
@@ -95,12 +94,10 @@ ASAB is distributed via [pypi](https://pypi.org/project/asab/). For installing A
     ```
 
 
-3.  Stop the application by `Ctrl+C`.
+3.  Stop the application by pressing `Ctrl+C`.
 
     !!! info
-        The ASAB is designed around a so-called [event
-        loop](https://en.wikipedia.org/wiki/Event_loop). It is meant primarily
-        for server architectures. For that reason, it doesn't terminate and
-        continue running and serving eventual requests.
+        ASAB is designed around an [event loop](https://en.wikipedia.org/wiki/Event_loop). It is meant primarily
+        for server architectures. For that reason, an ASAB application keeps running and serving requests unless or until you terminate the application. See [run time](../../reference/application/#run-time).
 
-You can continue with a step-by-step tutorial on how to build ASAB based [web server](./web_server.md).
+You can continue with a step-by-step tutorial on how to build an ASAB-based [web server](./web_server.md).