eventyay python.instructions.md

Python Development Instructions

Import

Import statements should be placed at the top of the file, not inside functions, except to resolve circular import errors.

Logging

• When a logging message needs to be constructed from multiple parts or variables, do not use f-strings or any method that builds the string before passing it to the logger. Instead, use the logger's built-in string interpolation feature. For example, use logger.info('User %s has logged in', username) instead of logger.info(f"User {username} has logged in"). This avoids wasting computation when the log level does not match.

• Avoid catching generic exceptions such as Exception or BaseException. Instead, catch specific exceptions that you expect to handle. This exposes errors originating from developer mistakes early, allowing us to fix them.

• When generating logs during exception handling, do not wrap the exception object with str(). For example, do not:

  except SomeException as e:
      logger.error('An error occurred: %s', str(e))
  

  Instead, do:

  except SomeException as e:
      logger.error('An error occurred: %s', e)
  

• When using logger.exception() for logging, there is no need to include the exception object in the log message. For example, do not:

  except SomeException as e:
      logger.exception('An error occurred: %s', e)
  

  Instead, do:

  except SomeException:
      logger.exception('An error occurred')
  

  because logger.exception() automatically includes the stack trace of the caught exception.

• When converting datetime data to strings, prefer f-strings with format specifiers over .strftime(). For example, use f"{dt:%Y-%m-%d %H:%M:%S}" instead of dt.strftime("%Y-%m-%d %H:%M:%S").

• When embedding datetime data into another string, do not convert the datetime to a string beforehand. For example, do not:

  timestamp = datetime.now().strftime('%Y%m%d-%H%M%S')
  filename = f'export-{timestamp}.csv'