new my_package1.my_module1

Etienne Pallier
1 parent 50af407d
Showing 1 changed file with 188 additions and 13 deletions Show diff stats
doc/code_style/my_package1/my_module1.py
 #!/usr/bin/env python3
  
+# Sphinx Napoleon syntax : https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
+
+# This import must be at the very beginning of the file
 from __future__ import annotations
  
 # TODO :
@@ -36,9 +39,10 @@ from __future__ import annotations
  
 # --- GENERAL PURPOSE IMPORTS ---
  
-from typing import Dict, List, Tuple
+from typing import Dict, List, Tuple, Sequence, Any, TypeVar, Union, Callable
 import platform
 from datetime import date
+import random
  
 # --- PROJECT SPECIFIC IMPORTS ---
  
@@ -67,13 +71,16 @@ IS_WINDOWS = platform.system() == &quot;Windows&quot;
 # - General Functions
 #
  
-def general_function_that_returns_a_float(arg_a: int, arg_b: str, arg_c: float=1.2, arg_d: bool=True) -> float:
-    '''
-    This function is used for ... blabla ...
+#
+# 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) -> float:
+    ''' This function is used for ... blabla ...
  
     Args:
         arg_a: the path of the file to wrap
-        arg_b: instance to wrap
+        arg_b: instance to wrap (in Python 3.10 we will be able to use 'str | int | float' instead)
         arg_c: toto
         arg_d: whether or not to delete the file when the File instance is destructed
  
@@ -94,8 +101,11 @@ def general_function_that_returns_a_float(arg_a: int, arg_b: str, arg_c: float=1
  
     return 3.5
  
+#
+# Typehint : Tuple (immutable)
+#
  
-def general_function_that_returns_a_tuple_of_3_elem(a: int, b: int=2, c: str='titi') -> Tuple[str, float, str]:
+def general_function_that_returns_a_tuple_of_3_elem(a: int, b: int=2, c: str='titi') -> Tuple[int, float, str]:
     ''' Commentaire général sur la fonction
  
     Args:
@@ -107,19 +117,181 @@ def general_function_that_returns_a_tuple_of_3_elem(a: int, b: int=2, c: str=&#39;ti
     return (a, b, c+' toto')
  
  
-class MySuperClass1:
-    pass
+#
+# Typehint : Sequence = List (mutable) or Tuple (immutable)
+#
  
+def square(elems: Sequence[float]) -> List[float]:
+    ''' function that takes a Sequence (either List of Tuple) as input, and send a List as output 
  
-class MySuperClass2:
+    Usage:
+
+    >>> square( [1,2,3] )
+    [1, 4, 9]
+    >>> square( (1,2,3) )
+    [1, 4, 9]
+    '''
+
+    return [x**2 for x in elems]
+
+
+#
+# Typehint : TypeAlias
+#
+
+SUITS = "♠ ♡ ♢ ♣".split()
+RANKS = "2 3 4 5 6 7 8 9 10 J Q K A".split()
+
+# Type aliases
+Card = Tuple[str, str]
+Deck = List[Card]
+
+
+def create_deck_without_alias(shuffle: bool = False) -> List[Tuple[str, str]]:
+    """Create a new deck of 52 cards"""
+    deck = [(s, r) for r in RANKS for s in SUITS]
+    if shuffle:
+        random.shuffle(deck)
+    return deck
+
+
+def create_deck_with_alias(shuffle: bool = False) -> Deck:
+    """Create a new deck of 52 cards
+
+    Card = Tuple[str, str]
+
+    Deck = List[Card]
+
+    Return Deck
+    """
+    deck = [(s, r) for r in RANKS for s in SUITS]
+    if shuffle:
+        random.shuffle(deck)
+    return deck
+
+
+#
+# Typehint : Generics avec Sequence, Any, TypeVar
+#
+
+def choose_from_list_of_Any_returns_a_Any(items: Sequence[Any]) -> Any:
+    ''' Option1 (BAD) : avoid using 'Any' because too general '''
+    return random.choice(items)
+
+
+T = TypeVar('T')
+def choose_from_list_of_a_specific_type_returns_same_type(items: Sequence[T]) -> T:
+    ''' Option2 (BETTER) : prefer 'TypeVar' instead of 'Any'
+
+    T = TypeVar("T")
+    '''
+    return random.choice(items)
+
+
+T = TypeVar("T", str, float)
+def choose_from_list_of_a_specific_constrained_type_returns_same_type(items: Sequence[T]) -> T:
+    ''' Option3 (still BETTER) : use a 'constrained TypeVar'
+
+    T = TypeVar("T", str, float)
+
+    (you could name 'T' as you want, for example, 'Choosable'...)
+
+    => the function accepts only sequence of str or float:
+
+    - if str: return str
+
+    - if float: return float
+
+    Usage:
+
+    choose(["Guido", "Jukka", "Ivan"])    => str, OK
+
+    choose([1, 2, 3])                => float, OK (car int subtype of float)
+
+    choose([True, 42, 3.14])        => float, OK (car bool subtype of int which is subtype of float)
+
+    choose(["Python", 3, 7])            => object, KO (rejected)
+    '''
+
+    return random.choice(items)
+
+
+#
+# Typehint : Callable
+#
+
+def create_greeting(congrat: str, name: str, nb: int) -> str:
+    #return f"Hello {name}"
+    return f"{congrat} {name} {nb}"
+
+
+def do_twice(func: Callable[[str, str, int], str], arg1: str, arg2: str, arg3: int) -> None:
+    '''
+    Usage:
+
+    >>> do_twice(create_greeting, "Hello", "Jekyll", 1)
+    Hello Jekyll 1
+    Hello Jekyll 1
+    '''
+    print(func(arg1, arg2, arg3))
+    print(func(arg1, arg2, arg3))
+
+
+# '''
+#    *******************************
+#      CUSTOM EXCEPTIONS
+#    *******************************
+#    See https://docs.python.org/3/tutorial/errors.html
+# '''
+
+
+class DCCNotFoundException(Exception):
+    ''' Raised when a specific DCC is not available '''
     pass
  
  
+class UnknownGenericCmdArgException(Exception):
+    ''' Raised when a GENERIC cmd argument is not recognized by the controller (no native cmd available for the generic cmd) '''
+
+    def __init__(self, name: str, arg: str):
+        self.name = name
+        self.arg = arg
+
+    def __str__(self):
+        return f"The argument '{self.arg}' does not exist for generic cmd {self.name}"
+
+
+class UnknownNativeCmdException(Exception):
+    ''' Raised when a NATIVE command name is not recognized by the controller '''
+    def __init__(self, *args, **kwargs):
+        super().__init__(self, *args, **kwargs)
+
+
+class UnimplementedGenericCmdException(Exception):
+    ''' Raised when a GENERIC cmd has no implementation in the controller (no native cmd available for the generic cmd) '''
+    def __str__(self):
+        return f"({type(self).__name__}): Device Generic command has no implementation in the controller"
+
+
 # '''
 # =================================================================
-#     CLASS MyFirstClass
+#     CLASSES
 # =================================================================
 # '''
+
+
+class MySuperClass1:
+    pass
+
+
+class MySuperClass2:
+    pass
+
+
+#
+# CLASS MyFirstClass
+#
+
 class MySimpleClass(MySuperClass1, MySuperClass2):
     ''' a Class with multi-inheritance
  
@@ -129,7 +301,7 @@ class MySimpleClass(MySuperClass1, MySuperClass2):
     '''
  
     #
-    # The class attributes
+    # Class attributes
     #
  
     names: List[str] = ["Guido", "Jukka", "Ivan"]
@@ -146,7 +318,7 @@ class MySimpleClass(MySuperClass1, MySuperClass2):
     pickle_file = "obsconfig.p"
  
     #
-    # The class methods
+    # Class methods
     #
  
     def __init__(self, a: int, b: float) -> None:
@@ -218,6 +390,9 @@ class Person:
     # a class method to create a Person object by birth year
     @classmethod
     def fromBirthYear(cls, name: str, year: int) -> Person:
+        '''
+        NB : return type 'Person' is possible because of: 'from __future__ import annotations'
+        '''
         return cls(name, date.today().year - year)
  
     # a class method to create a Person object from another
@@ -247,7 +422,7 @@ def main() -&gt; None:
     c = a+b
  
     a = general_function_that_returns_a_tuple_of_3_elem(1, 2)
-    print(a)
+    #print(a)
  
     import doctest
     doctest.testmod()