SHARE
TWEET

Untitled

a guest Jun 16th, 2019 54 Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
  1. # Draft
  2.  
  3. ## Using to_bytes/to_native/to_text
  4.  
  5. ### errors
  6.  
  7. The default value for `errors`, although specified as `None` in the
  8. function signature is `surrogate_then_replace`
  9.  
  10. The most common and recommended values for compatibility between python2
  11. and python3 are:
  12.  
  13. * `surrogate_then_replace`
  14. * `surrogate_or_strict`
  15.  
  16. When to use which?
  17.  
  18. `surrogate_then_replace` should be used when the data is informational only,
  19. such as when displaying information to the user. Ultimately, just heading to
  20. a log or displayed to the user.
  21.  
  22. `surrogate_or_strict` should be used when the data makes a difference to the
  23. computer's understanding of the world. Such as with file paths or database
  24. keys.
  25.  
  26. ### to_native
  27.  
  28. "native" in this context is meant to indicate the default string type on
  29. Python 2 and 3 as produced by `str`
  30.  
  31. #### On the controller
  32.  
  33. `to_native` on the controller, is used for a small set of functionality:
  34.  
  35. 1. When converting information for use in exceptions
  36. 1. When the underlying python API expects a native string type
  37.  
  38. Typically speaking, native values should not be long lived, and should be
  39. converted at the borders to native where they are needed. If a variable
  40. must be assigned to a native value, the variable should be prefixed with
  41. `n_` such as `n_output`.
  42.  
  43. #### On the target
  44.  
  45. 1. Typically most all strings on the target should utilize the native string
  46.    type for the most easy integration of the underlying python APIs. However,
  47.    be careful to note the information from the `errors` section, which
  48.    dictates which `errors` value to use for informational vs operational values.
  49.  
  50. ### to_bytes
  51.  
  52. "bytes" in this context refers to the data type produced by `bytes` on Python 2
  53. and Python3.
  54.  
  55. On Python 2 this is `str` and on Python 3 this is `bytes`.
  56.  
  57. Values converted to `bytes` should not be long lived. Typically values should
  58. be converted at the borders to bytes where they are needed. If a variable must
  59. be assigned to a bytes value, the variable should be prefixed with `b_` such
  60. as `b_path`.  This includes params in the function signature, if a function
  61. accepts a bytes value.
  62.  
  63. #### Everywhere
  64.  
  65. When dealing with byte-oriented APIs
  66.  
  67. ### to_text
  68.  
  69. "text" in this context is meant to indicate the type produced by the `unicode` function on Python2, and `str` on Python3.
  70.  
  71. #### On the controller
  72.  
  73. When data is ingested into Ansible, values should typically be cast to text.
  74.  
  75. Only on the borders where the data leaves Ansible should it be converted to
  76. bytes or native.
  77.  
  78. ### On the target
  79.  
  80. It is not likely to need `to_text` in many scenarios on the target. Only when
  81. the API you are dealing with specifically needs text types, such as in some
  82. MySQL libraries.
RAW Paste Data
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy. OK, I Understand
 
Top