Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
tutorials:python_development_standards [2018/05/01 08:52]
dgarcia [Python development standards]
tutorials:python_development_standards [2019/06/16 23:52] (current)
dgarcia [Logging]
Line 19: Line 19:
  
 To install: To install:
-<​code>​+<​code ​bash>
 apt-get install flake8 apt-get install flake8
 </​code>​ </​code>​
  
 Usage: Usage:
-<​code>​+<​code ​bash>
 flake8 path/​to/​code/​ flake8 path/​to/​code/​
 </​code>​ </​code>​
Line 32: Line 32:
  
 To install: To install:
-<​code>​+<​code ​bash>
 apt-get install yapf3 apt-get install yapf3
 </​code>​ </​code>​
  
 Usage: Usage:
-<​code>​+<​code ​bash>
 yapf3 -ir path/​to/​code_dir yapf3 -ir path/​to/​code_dir
 </​code>​ </​code>​
 or or
-<​code>​+<​code ​bash>
 yapf3 -i path/​to/​code/​file.py yapf3 -i path/​to/​code/​file.py
 +</​code>​
 +
 +==== Logging ====
 +
 +Logging is a very important part of every software project, because it is the best way to deliver valuable information to our users. Logs are used to report errors, warnings, or just general information of how the program is executing. Good logs help us to discover why the program fails some times, they help us diagnose problems with our programs and help us plan strategies for improvement. It is crucial to maintain a good and healthy logging practices so that you can increase the maintainability of your code.
 +
 +Python developers, knowing that logs are so important, have developed a module just for this: the [[https://​docs.python.org/​3.7/​library/​logging.html|Logging]] module. There are 5 default levels of logging, ordered from most important to less important are: ''​CRITICAL'',​ ''​Error'',​ ''​Warning'',​ ''​Info'',​ ''​Debug''​.
 +
 +=== Logging levels ===
 +
 +''​CRITICAL''​ logs are messages that are shown to the user that report that something **very bad** happened. The program is not able to continue its execution after that failure and it may cause colateral damage (affect a database, a network, files...).
 +
 +''​Error''​ logs are used when something goes wrong, but only a part is affected. Most failures can be logged as ''​Error''​.
 +
 +The ''​Warning''​ level is used to report errors from which your application is able to recover autonomously. Your system won't crash because of a ''​Warning'',​ but you are alerting the user that something is not OK. ''​Warning''​ logs can also be used in libraries when you want to tell your users that there are going to be some API changes. For example, if you want to change the name of a function, or if a method will be deprecated, the best thing to do is to create a ''​Warning''​ to announce that before doing the changes.
 +
 +''​Info''​ logs are for general information,​ there is nothing going wrong with your program, but you want to inform the user about events that might be of interest. Messages like "The file has been opened",​ "​Connection established"​ are common ''​Info''​ messages.
 +
 +Finally ''​Debug''​ logs are used only during development. Let's say that you are not sure why your program is behaving in a certain way, and you believe that there might be a problem with the value of a certain variable. So you can create a ''​Debug''​ log to print that variable'​s value, to see if there really is a problem.
 +
 +When you define a logging level, you are telling Python which messages you want to receive. If you define a level //A//, you will receive all //A// messages and all messages with more priority. If you say that you want a ''​Error''​ level, so you will receive ''​Error''​ and ''​CRITICAL''​ logs only. If you define ''​Debug''​ level, you will receive all logs. For most cases you will want to set ''​Info''​ or ''​Warning''​ levels.
 +
 +=== Loggers ===
 +
 +In Python, the [[https://​docs.python.org/​3.7/​library/​logging.html#​logging.Logger|logger]] is the object in charge of handling your logs. This are the objects that you as a programmer will use to create the logs. In order to get a logger you just have to call the module level function [[https://​docs.python.org/​3.7/​library/​logging.html#​logging.getLogger|getLogger()]]. This function will return a logger object that you can use. Loggers have the ''​setLevel''​ method. This method sets the level of your logger as explained above. Then you have the ''​debug'',​ ''​info'',​ ''​warning'',​ ''​error'',​ and ''​critical''​ methods which create a message of their respective level. Note that if you set the ''​Warning''​ level, and create a ''​Debug''​ message, it won't be shown to the user. That is exactly the idea of defining these levels.
 +
 +The following is an example,
 +
 +<code python>
 +# myapp.py
 +import logging
 +import math
 +
 +def main():
 +    # Instead of printing the message send it to a file named '​filename'​
 +    # Set the INFO level
 +    logging.basicConfig(filename="​myapp.log",​ level=logging.INFO)
 +    ​
 +    # log some info
 +    logging.info("​Started"​)
 +    total = 0
 +    for number in range(-2, 100):
 +        logging.debug(number)
 +        try:
 +            math.sqrt(number)
 +        except ValueError:
 +            # report that there was an error, but we handled it.
 +            logging.warning("​Recovering from a negative sqrt")
 +            number = 0
 +       
 +        total += number
 +       
 +    if total < 0:
 +        # If after adding possive numbers you got a negative, then there is something really wrong
 +        logging.error("​Negative sum of positive numbers"​)
 +        raise ValueError
 +    ​
 +    # If everything went OK, report it
 +    logging.info('​Finished'​)
 +
 +if __name__ == '​__main__':​
 +    main()
 </​code>​ </​code>​
  
Line 111: Line 173:
 ==== Issues ==== ==== Issues ====
  
-Any problems encountered due to migration should be reported with a github ​issue on the corresponding repo.+Any problems encountered due to migration should be reported with a GitLab ​issue on the corresponding repo.
 ==== Progress tracking ==== ==== Progress tracking ====
  
  • tutorials/python_development_standards.1525182737.txt.gz
  • Last modified: 2018/05/01 08:52
  • by dgarcia