Python Reference · String Methods
Python str.encode() method
Reference for Python str.encode(): turn a string into bytes with an encoding, choose an error handler, and handle UnicodeEncodeError correctly.
The str.encode() method converts a string, which is a sequence of Unicode characters, into a bytes object using a character encoding. You need bytes whenever text leaves your program: writing to a binary file, sending over a network or hashing.
The default encoding is UTF-8, which can represent every Unicode character. Other encodings, such as ASCII or Latin-1, can only represent some characters and need an error strategy for the rest. The reverse operation is bytes.decode().
data = "héllo".encode("utf-8") print(data) # b'h\xc3\xa9llo'
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input · what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input · what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Syntax
str.encode(encoding="utf-8", errors="strict")
| Name | Description |
|---|---|
encoding |
Optional. The name of the codec, such as "utf-8", "ascii", "latin-1" or "utf-16". Default "utf-8". |
errors |
Optional. What to do with characters the codec cannot represent. Default "strict". |
Common error handlers:
| Handler | Effect |
|---|---|
"strict" |
Raise UnicodeEncodeError. |
"ignore" |
Drop the character. |
"replace" |
Substitute ?. |
"xmlcharrefreplace" |
Insert an XML entity such as ☕. |
"backslashreplace" |
Insert an escape such as ☕. |
Return value: a bytes object.
Raises: UnicodeEncodeError (a subclass of ValueError) for unencodable characters with the strict handler; LookupError for an unknown encoding name.
Usage notes
- Characters versus bytes. One character may take 1 to 4 bytes in UTF-8, so
len(text)andlen(text.encode())can differ. Use the byte length for sizes on disk or on the wire. - Always be explicit when files or protocols are involved. Relying on a platform default causes bugs when code moves to another machine. UTF-8 is the right default almost everywhere.
ignoreandreplacelose data. Use them for display or logging, never for data you must restore.- Lone surrogates (such as
"\ud800") cannot be encoded as UTF-8 with the strict handler. The"surrogateescape"handler exists for round-tripping undecodable bytes. - Byte order.
"utf-16"adds a byte order mark;"utf-16-le"and"utf-16-be"do not. - Immutable result. Use
bytearray()if you need to modify the data after encoding. - Opposite direction.
bytes.decode()orstr(data, "utf-8"). Decoding with the wrong codec gives garbled text or an error.
Related
bytes(),bytearray(),ord(),chr(),ascii(),open()- Lessons: Strings, String methods