New version of the code style page - added lot of new stuff

Etienne Pallier
1 parent b999fd50
Showing 1 changed file with 358 additions and 5 deletions Show diff stats
doc/code_style/my_package1/my_module1.py
@@ -6,13 +6,22 @@
  
     This file conforms to the Sphinx Napoleon syntax :
     https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
+
+    VERSION 17.02.2022
+
+    Changes :
+
+    - added new type annotation : Literal
+    
+    - added new types : NamedTuple, Dataclass, Enum, TypedDict
+    
+    - added custom and derived Exceptions
 =================================================================
 """
  
 # This import MUST BE at the very beginning of the file (or syntax error...)
 from __future__ import annotations
  
-VERSION = "16.02.2022"
  
 # TODO :
 # - exception (custom)
@@ -29,7 +38,9 @@ VERSION = &quot;16.02.2022&quot;
  
 # --- 1) GENERAL PURPOSE IMPORTS ---
  
-from typing import Dict, List, Tuple, Sequence, Any, TypeVar, Union, Callable
+from typing import Dict, List, Tuple, Sequence, Any, TypeVar, Union, Callable, Literal
+import typing
+
 import platform
 from datetime import date
 import random
@@ -66,13 +77,13 @@ IS_WINDOWS = platform.system() == &quot;Windows&quot;
 # - Typehint : Union (but not yet '|', only available with python 3.10)
  
 def general_function_that_returns_a_float(
-    arg_a: int, arg_b: Union[str, int, float], arg_c: float = 1.2, arg_d: bool = True
+    arg_a: int, arg_b: str | int, arg_c: float = 1.2, arg_d: bool = True
 ) -> float:
-    """This function illustrates Typehint 'Union' (but not yet '|', only available with python 3.10)
+    """This function illustrates Typehint 'Union' (or '|')
  
     Args:
         arg_a: the path of the file to wrap
-        arg_b: instance to wrap (in Python 3.10 we will be able to use 'str | int | float' instead)
+        arg_b: instance to wrap
         arg_c: toto
         arg_d: whether or not to delete the file when the File instance is destructed
  
@@ -83,6 +94,14 @@ def general_function_that_returns_a_float(
         AttributeError: The ``Raises`` section is a list of all exceptions
             that are relevant to the interface.
         ValueError: If `arg_a` is equal to `arg_b`.
+
+    Usage:
+
+        general_function_that_returns_a_float(arg_a=1, arg_b="toto")    # => OK
+
+        general_function_that_returns_a_float(arg_a=1, arg_b=1.2)       # => KO (float not allowed)
+
+
     """
  
     # comment on a
@@ -94,6 +113,7 @@ def general_function_that_returns_a_float(
     return 3.5
  
  
+
 # - Typehint : Tuple (immutable)
  
 def general_function_that_returns_a_tuple_of_3_elem(
@@ -260,6 +280,40 @@ def do_twice(
     print(func(arg1, arg2, arg3))
  
  
+# - Typehint : typing.Literal (new in 3.8)
+
+def validate_simple(data: Any) -> Literal[True]:  
+    """This function illustrates Typehint 'Literal' (new in 3.8)
+    
+    => should always return True
+    """
+    pass
+
+
+MODE = Literal['r', 'rb', 'w', 'wb']
+
+
+def open_helper(file: str, mode: MODE) -> str:
+    """This function illustrates Typehint 'Literal' (new in 3.8)
+
+    (Type alias :)
+
+    MODE = Literal['r', 'rb', 'w', 'wb']
+
+    Usage:
+    
+    OK :
+
+    >>> open_helper('/some/path', 'r')
+
+    Error :
+    
+    >>> open_helper('/other/path', 'typo')  
+    """
+
+    pass
+
+
 # '''
 #    *******************************
 #      CUSTOM EXCEPTIONS CLASSES
@@ -299,6 +353,98 @@ class UnimplementedGenericCmdException(Exception):
         return f"({type(self).__name__}): Device Generic command has no implementation in the controller"
  
  
+class MyImprovedException(Exception):
+    """Improved Exeption class with predefined list of standard error messages, and optional specific message
+    
+    Usage:
+
+    >>> e = MyImprovedException(MyImprovedException.ERROR_BAD_PARAM)
+    >>> e.error_msg
+    'Bad Parameter'
+    >>> e
+    MyImprovedException('Bad Parameter')
+    >>> print(e)
+    (MyImprovedException): Bad Parameter
+
+    >>> e = MyImprovedException(MyImprovedException.ERROR_BAD_PARAM, "my specific message added")
+    >>> e
+    MyImprovedException('Bad Parameter', 'my specific message added')
+    >>> print(e)
+    (MyImprovedException): Bad Parameter ; Specific message: my specific message added
+    """
+
+    # List of standard error messages
+    ERROR_UNDEFINED_PARAM = "Parameter not defined"
+    ERROR_BAD_PARAM = "Bad Parameter"
+    ERROR_MISSING_PARAM = "a Parameter is missing"
+    ERROR_TOO_MANY_PARAM = "Too many Parameters"
+
+    def __init__(self, error_msg: str, specific_msg: str = None):
+        #super().__init__(error_msg)
+        self.error_msg = error_msg
+        self.specific_msg = specific_msg
+
+    def __str__(self):
+        #msg = f"({type(self).__name__}): {self.error_msg}"
+        msg = f"({self.__class__.__name__}): {self.error_msg}"
+        if self.specific_msg:
+            msg += f" ; Specific message: {self.specific_msg}"
+        return msg
+
+
+class MyOwnDerivedException(MyImprovedException):
+    """
+    Usage:
+    
+    >>> try:
+    ...     print("doing something dangerous...")
+    ...     raise MyOwnDerivedException(MyOwnDerivedException.ERROR_MISSING_PARAM)
+    ... except MyOwnDerivedException as e:
+    ...     print(e)
+    doing something dangerous...
+    (MyOwnDerivedException): a Parameter is missing
+
+    >>> try:
+    ...     print("doing something dangerous...")
+    ...     raise MyOwnDerivedException(MyOwnDerivedException.ERROR_NEW_CASE2, 'my own special message')
+    ... except MyImprovedException as e:  # we can use superclass also
+    ...     print(e)
+    doing something dangerous...
+    (MyOwnDerivedException): Nouveau cas d'erreur 2 ; Specific message: my own special message
+
+    General example :
+
+    >>> try:
+    ...     # do something
+    ...     pass
+    ...
+    ... except ValueError:
+    ...     # handle ValueError exception
+    ...     pass
+    ...
+    ... except (TypeError, ZeroDivisionError):
+    ...     # handle multiple exceptions
+    ...     # TypeError and ZeroDivisionError
+    ...     pass
+    ...
+    ... except:
+    ...     # handle all other exceptions
+    ...     pass
+
+    """
+    # Add new specific error cases for this exception type:
+    ERROR_NEW_CASE1 = "Nouveau cas d'erreur 1"
+    ERROR_NEW_CASE2 = "Nouveau cas d'erreur 2"
+
+'''
+try:
+    print("doing something dangerous...")
+    raise MyOwnDerivedException(MyOwnDerivedException.ERROR_MISSING_PARAM)
+except MyOwnDerivedException as e:
+    print(e)
+'''
+
+
 # '''
 # =================================================================
 #     GENERAL CLASSES
@@ -433,6 +579,213 @@ class Person:
  
 # '''
 # =================================================================
+#     - CLASS Employee
+# =================================================================
+# '''
+
+# class typing.NamedTuple : Typed version of collections.namedtuple()
+
+class Employee(typing.NamedTuple):
+    """Illustrates usage of collections.namedtuple & typing.NamedTuple
+
+    See https://towardsdatascience.com/what-are-named-tuples-in-python-59dc7bd15680
+
+    See https://www.netjstech.com/2020/01/named-tuple-python.html
+
+    Usage:
+    
+    1) Here we use typing.NamedTuple :
+    
+    >>> andrew = Employee('Andrew', 'Brown', ['Develoer', 'Manager'], 'US')
+    >>> print(andrew)
+    Employee(first_name='Andrew', last_name='Brown', jobs=['Develoer', 'Manager'], country='US')
+
+    >>> alice = Employee(first_name='Alice', last_name='Stevenson', jobs=['Product Owner'])
+    >>> print(alice)
+    Employee(first_name='Alice', last_name='Stevenson', jobs=['Product Owner'], country='France')
+    >>> alice.last_name
+    'Stevenson'
+    >>> alice[1]
+    'Stevenson'
+    >>> for attr in alice: print(attr)
+    Alice
+    Stevenson
+    ['Product Owner']
+    France
+
+
+    2) Here we define the same Employee as above, but using collections.namedtuple :
+    
+    >>> from collections import namedtuple
+    >>> Employee = namedtuple('Employee', 'first_name last_name jobs country')
+
+    or :
+
+    >>> Employee = namedtuple('Employee', ['first_name', 'last_name', 'jobs', 'country'])
+
+    """
+
+    first_name: str
+    last_name: str
+    jobs: list
+    country: str = "France"
+
+
+# '''
+# =================================================================
+#     - CLASS Point2D
+# =================================================================
+# '''
+
+# typing.TypedDict : Special construct to add type hints to a dictionary. At runtime it is a plain dict
+
+class Point2D(typing.TypedDict):
+    """Class to illustrate typing.TypedDict
+
+    (Special construct to add type hints to a dictionary. At runtime it is a plain dict)
+
+    See: https://adamj.eu/tech/2021/05/10/python-type-hints-how-to-use-typeddict/
+
+   
+    Usage:
+    
+    a: Point2D = {'x': 1, 'y': 2, 'label': 'good'}  # OK
+
+    b: Point2D = {'x': 1, 'y': 2}                   # KO (missing label)
+    
+    c: Point2D = {'z': 3, 'label': 'bad'}           # KO (z not defined)
+    
+    d: Point2D = {}                                 # KO (missing x, y, label)
+
+    
+    Definition (other possibilities):
+    
+    Point2D = TypedDict('Point2D', x=int, y=int, label=str)
+    
+    Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
+    """
+    x: int
+    y: int
+    label: str
+
+
+def get_point() -> Point2D:
+    return {
+        'x': 1,
+        'y': 2,
+        'label': 'good'
+    }
+
+
+
+# '''
+# =================================================================
+#     - CLASS Position
+# =================================================================
+# '''
+
+# @dataclass : shortcut for class definition
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Position:
+    """@dataclass
+
+    Class to illustrate Data Classes (@dataclass)
+    
+    See: https://realpython.com/python-data-classes
+    
+    A DataClass is a shortcut to define a "data structure" without method
+
+    It is much like a NamedTuple, but "mutable", and with more features.
+
+    Defines automatically a lot of things for you : 
+    
+    - __init__() (with self.x = x, self.y = y, ...)
+    
+    - __repr()__
+    
+    - __eq()__
+
+    - order, sort, immutable or not (frozen=True), ...
+    
+    NB: on peut quand même ajouter des méthodes à une dataclass car c’est une classe normale...
+
+
+    Definition alternatives :
+
+    >>> from dataclasses import make_dataclass
+    >>> Position = make_dataclass('Position', ['name', 'lat', 'lon'])
+
+    Usage:
+
+    >>> pos = Position('Oslo', 10.8, 59.9)
+    >>> pos
+    Position(name='Oslo', lat=10.8, lon=59.9)
+    >>> pos.lon
+    59.9
+    """
+   
+    name: str
+    lon: float
+    lat: float = 0.0 # with default value
+
+
+@dataclass
+class PlayingCard:
+    """@dataclass
+    
+    Class to illustrate Data Classes (@dataclass)
+    """
+    rank: str
+    suit: str
+
+
+@dataclass
+class Deck:
+    """@dataclass
+    
+    Class to illustrate Data Classes (@dataclass)
+
+    Usage:
+
+    >>> queen_of_hearts = PlayingCard('Q', 'Hearts')
+    
+    >>> ace_of_spades = PlayingCard('A', 'Spades')
+    
+    >>> two_cards = Deck([queen_of_hearts, ace_of_spades])
+    """
+    cards: List[PlayingCard]
+
+
+@dataclass
+class Cmd:
+    """@dataclass
+    
+    PyROS example class to illustrate Data Classes 
+    (@dataclass, and using 'field')
+
+    Usage:
+
+    >>> c = Cmd('get_timezone')
+
+    >>> c = Cmd('do_init','do_init'),
+    """
+
+    generic_name: str = 'generic name'
+    native_name: str = ''
+    desc: str = 'Description'
+    params: Dict[str, str] = field(default_factory=dict)  # equivalent to "= {}" which is not allowed
+    final_simul_response: str = 'simulator response'
+    final_device_responses: Dict[str, str] = field(default_factory=dict)
+    immediate_responses: Dict[str, str] = field(default_factory=dict)
+    errors: Dict[str, str] = field(default_factory=dict)
+
+
+# '''
+# =================================================================
 #    Main function (definition)
 # =================================================================
 # '''