Commit 88b21b40 authored by Kirill Smelkov's avatar Kirill Smelkov

golang_str: Refresh b/u and bstr/ustr docstrings

Document explicitly which types b/u accept and how they are handled.
Change bstr/ustr docstrings to also be more explicit.

Documentation changes only.
parent b7cda092
...@@ -30,18 +30,18 @@ from libc.stdint cimport uint8_t ...@@ -30,18 +30,18 @@ from libc.stdint cimport uint8_t
pystrconv = None # = golang.strconv imported at runtime (see __init__.py) pystrconv = None # = golang.strconv imported at runtime (see __init__.py)
def pyb(s): # -> bstr def pyb(s): # -> bstr
"""b converts str/unicode/bytes s to UTF-8 encoded bytestring. """b converts object to bstr.
Bytes input is preserved as-is: - For bstr the same object is returned.
- For bytes the data is
preserved as-is and only result type is changed to bstr.
- For ustr/unicode the data is UTF-8 encoded. The encoding always succeeds.
b(bytes_input) == bytes_input TypeError is raised if type(s) is not one of the above.
Unicode input is UTF-8 encoded. The encoding always succeeds.
b is reverse operation to u - the following invariant is always true: b is reverse operation to u - the following invariant is always true:
b(u(bytes_input)) == bytes_input b(u(bytes_input)) is bstr with the same data as bytes_input.
TypeError is raised if type(s) is not one of the above.
See also: u, bstr/ustr. See also: u, bstr/ustr.
""" """
...@@ -58,21 +58,21 @@ def pyb(s): # -> bstr ...@@ -58,21 +58,21 @@ def pyb(s): # -> bstr
return pybstr(s) return pybstr(s)
def pyu(s): # -> ustr def pyu(s): # -> ustr
"""u converts str/unicode/bytes s to unicode string. """u converts object to ustr.
Unicode input is preserved as-is:
u(unicode_input) == unicode_input - For ustr the same object is returned.
- For unicode the data is preserved as-is and only result type is changed to ustr.
Bytes input is UTF-8 decoded. The decoding always succeeds and input - For bstr or bytes the data is UTF-8 decoded.
The decoding always succeeds and input
information is not lost: non-valid UTF-8 bytes are decoded into information is not lost: non-valid UTF-8 bytes are decoded into
surrogate codes ranging from U+DC80 to U+DCFF. surrogate codes ranging from U+DC80 to U+DCFF.
u is reverse operation to b - the following invariant is always true:
u(b(unicode_input)) == unicode_input
TypeError is raised if type(s) is not one of the above. TypeError is raised if type(s) is not one of the above.
u is reverse operation to b - the following invariant is always true:
u(b(unicode_input)) is ustr with the same data as unicode_input.
See also: b, bstr/ustr. See also: b, bstr/ustr.
""" """
if type(s) is pyustr: if type(s) is pyustr:
...@@ -109,10 +109,16 @@ cdef __pystr(object obj): # -> ~str ...@@ -109,10 +109,16 @@ cdef __pystr(object obj): # -> ~str
# XXX cannot `cdef class`: github.com/cython/cython/issues/711 # XXX cannot `cdef class`: github.com/cython/cython/issues/711
class pybstr(bytes): class pybstr(bytes):
"""bstr is like bytes but can be automatically converted to Python unicode """bstr is byte-string.
string via UTF-8 decoding.
It is based on bytes and can automatically convert to unicode.
The conversion never fails and never looses information:
bstr → ustr → bstr
The decoding never fails nor looses information - see u for details. is always identity even if bytes data is not valid UTF-8.
See also: b, ustr/u.
""" """
# don't allow to set arbitrary attributes. # don't allow to set arbitrary attributes.
...@@ -131,10 +137,16 @@ class pybstr(bytes): ...@@ -131,10 +137,16 @@ class pybstr(bytes):
cdef class pyustr(unicode): cdef class pyustr(unicode):
"""ustr is like unicode(py2)|str(py3) but can be automatically converted """ustr is unicode-string.
to bytes via UTF-8 encoding.
It is based on unicode and can automatically convert to bytes.
The conversion never fails and never looses information:
ustr → bstr → ustr
is always identity even if bytes data is not valid UTF-8.
The encoding always succeeds - see b for details. See also: u, bstr/b.
""" """
def __bytes__(self): return pyb(self) def __bytes__(self): return pyb(self)
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment