diff options
| author | Paul Kehrer <paul.l.kehrer@gmail.com> | 2017-10-11 20:29:23 +0800 |
|---|---|---|
| committer | Alex Gaynor <alex.gaynor@gmail.com> | 2017-10-11 08:29:23 -0400 |
| commit | e885bd65a871926a8866db92035d814e3d179bf7 (patch) | |
| tree | 3b4456e27928ddf9ac11b0091412de3e75000129 /docs/x509/reference.rst | |
| parent | 1aac78c4d036d20e8892f3861ea947cadf6ab739 (diff) | |
| download | cryptography-e885bd65a871926a8866db92035d814e3d179bf7.tar.gz cryptography-e885bd65a871926a8866db92035d814e3d179bf7.tar.bz2 cryptography-e885bd65a871926a8866db92035d814e3d179bf7.zip | |
Update docs and changelog for URI, RFC822Name, and DNSName (#3955)
* Update docs and changelog for URI, RFC822Name, and DNSName
As of 2.1 we want users to pass A-label strings, but we still accept
U-label strings and auto-encode on their behalf (with a deprecation
warning). However, we do not return U-label in the value attribute so
we are making a backwards incompatible change for users that utilize
internationalized domain names.
* language updates
* add presentational to the word list
* the linux dictionary is pathetic
Diffstat (limited to 'docs/x509/reference.rst')
| -rw-r--r-- | docs/x509/reference.rst | 94 |
1 files changed, 37 insertions, 57 deletions
diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index 238a24e5..014d1f47 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -1242,66 +1242,53 @@ General Name Classes .. versionadded:: 0.9 - ..note:: + .. versionchanged:: 2.1 - Starting with version 2.1 unicode input is deprecated. If passing an - email address containing an internationalized domain name (IDN) you - should first IDNA encode the hostname and then pass the resulting - bytes. + .. warning:: - This corresponds to an email address. For example, ``user@example.com``. - - :param bytes value: The email address. If the address contains an - internationalized domain name then it must be encoded to an - :term:`A-label` before being passed. + Starting with version 2.1 :term:`U-label` input is deprecated. If + passing an internationalized domain name (IDN) you should first IDNA + encode the value and then pass the result as a string. Accessing + ``value`` will return the :term:`A-label` encoded form even if you pass + a U-label. This breaks backwards compatibility, but only for + internationalized domain names. - .. attribute:: bytes_value - .. versionadded:: 2.1 - - :type: bytes + This corresponds to an email address. For example, ``user@example.com``. - The value as a byte string. This will contain an :term:`A-label` if - the domain in the address is an internationalized domain name. + :param value: The email address. If the address contains an + internationalized domain name then it must be encoded to an + :term:`A-label` string before being passed. .. attribute:: value - .. deprecated:: 2.1 - - Deprecated accessor for the idna-decoded value of :attr:`bytes_value` - :type: :term:`text` .. class:: DNSName(value) .. versionadded:: 0.9 - ..note:: + .. versionchanged:: 2.1 - Starting with version 2.1 unicode input is deprecated. If passing an - internationalized domain name (IDN) you should first IDNA encode the - hostname and then pass the resulting bytes. + .. warning:: - This corresponds to a domain name. For example, ``cryptography.io``. + Starting with version 2.1 :term:`U-label` input is deprecated. If + passing an internationalized domain name (IDN) you should first IDNA + encode the value and then pass the result as a string. Accessing + ``value`` will return the :term:`A-label` encoded form even if you pass + a U-label. This breaks backwards compatibility, but only for + internationalized domain names. - :param bytes value: The domain name. If it is an internationalized domain - name then it must be encoded to an :term:`A-label` before being passed. - - .. attribute:: bytes_value - - .. versionadded:: 2.1 + This corresponds to a domain name. For example, ``cryptography.io``. - :type: bytes + :param value: The domain name. If it is an internationalized domain + name then it must be encoded to an :term:`A-label` string before being + passed. - The value as a byte string. This will contain an :term:`A-label` if - it is an internationalized domain name. + :type: :term:`text` .. attribute:: value - .. deprecated:: 2.1 - - Deprecated accessor for the idna-decoded value of :attr:`bytes_value` - :type: :term:`text` .. class:: DirectoryName(value) @@ -1318,33 +1305,26 @@ General Name Classes .. versionadded:: 0.9 - ..note:: + .. versionchanged:: 2.1 + + .. warning:: - Starting with version 2.1 unicode input is deprecated. If passing an - internationalized domain name (IDN) within the URI you should first - IDNA encode the hostname and then pass the resulting bytes. + Starting with version 2.1 :term:`U-label` input is deprecated. If + passing an internationalized domain name (IDN) you should first IDNA + encode the value and then pass the result as a string. Accessing + ``value`` will return the :term:`A-label` encoded form even if you pass + a U-label. This breaks backwards compatibility, but only for + internationalized domain names. This corresponds to a uniform resource identifier. For example, ``https://cryptography.io``. - :param bytes value: The URI. If it contains an internationalized domain - name then it must be encoded to an :term:`A-label` before being passed. - - .. attribute:: bytes_value - - .. versionadded:: 2.1 - - :type: bytes - - The value as a byte string. This will contain an :term:`A-label` if - the URI contains an internationalized domain name. + :param value: The URI. If it contains an internationalized domain + name then it must be encoded to an :term:`A-label` string before + being passed. .. attribute:: value - .. deprecated:: 2.1 - - Deprecated accessor for the idna-decoded value of :attr:`bytes_value` - :type: :term:`text` .. class:: IPAddress(value) |