a guest Jun 16th, 2019 54 Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
- # Draft
- ## Using to_bytes/to_native/to_text
- ### errors
- The default value for `errors`, although specified as `None` in the
- function signature is `surrogate_then_replace`
- The most common and recommended values for compatibility between python2
- and python3 are:
- * `surrogate_then_replace`
- * `surrogate_or_strict`
- When to use which?
- `surrogate_then_replace` should be used when the data is informational only,
- such as when displaying information to the user. Ultimately, just heading to
- a log or displayed to the user.
- `surrogate_or_strict` should be used when the data makes a difference to the
- computer's understanding of the world. Such as with file paths or database
- ### to_native
- "native" in this context is meant to indicate the default string type on
- Python 2 and 3 as produced by `str`
- #### On the controller
- `to_native` on the controller, is used for a small set of functionality:
- 1. When converting information for use in exceptions
- 1. When the underlying python API expects a native string type
- Typically speaking, native values should not be long lived, and should be
- converted at the borders to native where they are needed. If a variable
- must be assigned to a native value, the variable should be prefixed with
- `n_` such as `n_output`.
- #### On the target
- 1. Typically most all strings on the target should utilize the native string
- type for the most easy integration of the underlying python APIs. However,
- be careful to note the information from the `errors` section, which
- dictates which `errors` value to use for informational vs operational values.
- ### to_bytes
- "bytes" in this context refers to the data type produced by `bytes` on Python 2
- and Python3.
- On Python 2 this is `str` and on Python 3 this is `bytes`.
- Values converted to `bytes` should not be long lived. Typically values should
- be converted at the borders to bytes where they are needed. If a variable must
- be assigned to a bytes value, the variable should be prefixed with `b_` such
- as `b_path`. This includes params in the function signature, if a function
- accepts a bytes value.
- #### Everywhere
- When dealing with byte-oriented APIs
- ### to_text
- "text" in this context is meant to indicate the type produced by the `unicode` function on Python2, and `str` on Python3.
- #### On the controller
- When data is ingested into Ansible, values should typically be cast to text.
- Only on the borders where the data leaves Ansible should it be converted to
- bytes or native.
- ### On the target
- It is not likely to need `to_text` in many scenarios on the target. Only when
- the API you are dealing with specifically needs text types, such as in some
- MySQL libraries.
RAW Paste Data