From e7c75635f8e948f0e3ebf78d18f70c2fc4ae257b Mon Sep 17 00:00:00 2001 From: Kim Davies Date: Tue, 12 Oct 2021 15:49:06 -0700 Subject: [PATCH] Adjust documentation (issue #18) Moved some items around and added text about version compatibility and emoji domains --- README.rst | 46 ++++++++++++++++++++++++++++------------------ 1 file changed, 28 insertions(+), 18 deletions(-) diff --git a/README.rst b/README.rst index cf1eff3..31af3e5 100644 --- a/README.rst +++ b/README.rst @@ -11,7 +11,7 @@ This library also provides support for Unicode Technical Standard 46, This acts as a suitable replacement for the “encodings.idna” module that comes with the Python standard library, but which only supports the -old, deprecated IDNA specification (`RFC 3490 `_). +older superseded IDNA specification (`RFC 3490 `_). Basic functions are simply executed: @@ -23,14 +23,6 @@ Basic functions are simply executed: >>> print(idna.decode('xn--eckwd4c7c.xn--zckzah')) ドメイン.テスト -Packages --------- - -The latest tagged release version is published in the PyPI repository: - -.. image:: https://badge.fury.io/py/idna.svg - :target: https://badge.fury.io/py/idna - Installation ------------ @@ -47,10 +39,6 @@ Alternatively, you can install the package using the bundled setup script: $ python setup.py install -This library works with Python 3.5 or later. Earlier versions of this -library support Python 2 - use "idna<3" in your requirements file if -you need this library for a Python 2 application. - Usage ----- @@ -186,9 +174,31 @@ in computing the table data. For example, ``idna-data --version 9.0.0 make-libda will generate library data against Unicode 9.0.0. -Testing -------- +Additional Notes +---------------- -The library has a test suite based on each rule of the IDNA specification, as -well as tests that are provided as part of the Unicode Technical Standard 46, -`Unicode IDNA Compatibility Processing `_. +* **Packages**. The latest tagged release version is published in the + `Python Package Index `_. + +* **Version support**. This library supports Python 3.5 and higher. As this library + serves as a low-level toolkit for a variety of applications, many of which strive + for broad compatibility with older Python versions, there is no rush to remove + older intepreter support. Removing support for older versions should be well + justified in that the maintenance burden has become too high. + +* **Python 2**. Python 2 is supported by version 2.x of this library. While active + development of the version 2.x series has ended, notable issues being corrected + may be backported to 2.x. Use "idna<3" in your requirements file if you need this + library for a Python 2 application. + +* **Testing**. The library has a test suite based on each rule of the IDNA specification, as + well as tests that are provided as part of the Unicode Technical Standard 46, + `Unicode IDNA Compatibility Processing `_. + +* **Emoji**. It is an occasional request to support emoji domains in this library. Encoding + of symbols like emoji is expressly prohibited by the technical standard IDNA 2008 and + emoji domains are broadly phased out across the domain industry due to associated security + risks. For now, applications that wish need to support these non-compliant labels may + wish to consider trying the encode/decode operation in this library first, and then falling + back to using `encodings.idna`. See `the Github project `_ + for more discussion. \ No newline at end of file