From 4625d074d834f1b8636bd8af84f963b60e1d0e18 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sun, 14 Apr 2024 11:52:10 -0400 Subject: [PATCH] Removed sections pertaining to Python 2 concerns. --- README.rst | 115 ----------------------------------------------------- 1 file changed, 115 deletions(-) diff --git a/README.rst b/README.rst index 465e835..32027f5 100644 --- a/README.rst +++ b/README.rst @@ -30,94 +30,6 @@ simply import it explicitly as a backport:: For detailed documentation consult the vanilla version at http://docs.python.org/3/library/configparser.html. -Why you'll love ``configparser`` -================================ - -Whereas almost completely compatible with its older brother, ``configparser`` -sports a bunch of interesting new features: - -* full mapping protocol access (`more info - `_):: - - >>> parser = ConfigParser() - >>> parser.read_string(""" - [DEFAULT] - location = upper left - visible = yes - editable = no - color = blue - - [main] - title = Main Menu - color = green - - [options] - title = Options - """) - >>> parser['main']['color'] - 'green' - >>> parser['main']['editable'] - 'no' - >>> section = parser['options'] - >>> section['title'] - 'Options' - >>> section['title'] = 'Options (editable: %(editable)s)' - >>> section['title'] - 'Options (editable: no)' - -* there's now one default ``ConfigParser`` class, which basically is the old - ``SafeConfigParser`` with a bunch of tweaks which make it more predictable for - users. Don't need interpolation? Simply use - ``ConfigParser(interpolation=None)``, no need to use a distinct - ``RawConfigParser`` anymore. - -* the parser is highly `customizable upon instantiation - `__ - supporting things like changing option delimiters, comment characters, the - name of the DEFAULT section, the interpolation syntax, etc. - -* you can easily create your own interpolation syntax but there are two powerful - implementations built-in (`more info - `__): - - * the classic ``%(string-like)s`` syntax (called ``BasicInterpolation``) - - * a new ``${buildout:like}`` syntax (called ``ExtendedInterpolation``) - -* fallback values may be specified in getters (`more info - `__):: - - >>> config.get('closet', 'monster', - ... fallback='No such things as monsters') - 'No such things as monsters' - -* ``ConfigParser`` objects can now read data directly `from strings - `__ - and `from dictionaries - `__. - That means importing configuration from JSON or specifying default values for - the whole configuration (multiple sections) is now a single line of code. Same - goes for copying data from another ``ConfigParser`` instance, thanks to its - mapping protocol support. - -* many smaller tweaks, updates and fixes - -A few words about Unicode -========================= - -``configparser`` comes from Python 3 and as such it works well with Unicode. -The library is generally cleaned up in terms of internal data storage and -reading/writing files. There are a couple of incompatibilities with the old -``ConfigParser`` due to that. However, the work required to migrate is well -worth it as it shows the issues that would likely come up during migration of -your project to Python 3. - -The design assumes that Unicode strings are used whenever possible [1]_. That -gives you the certainty that what's stored in a configuration object is text. -Once your configuration is read, the rest of your application doesn't have to -deal with encoding issues. All you have is text [2]_. The only two phases when -you should explicitly state encoding is when you either read from an external -source (e.g. a file) or write back. Versioning ========== @@ -178,33 +90,6 @@ The process works like this: 5. Update the docs and release the new version. -Footnotes -========= - -.. [1] To somewhat ease migration, passing bytestrings is still supported but - they are converted to Unicode for internal storage anyway. This means - that for the vast majority of strings used in configuration files, it - won't matter if you pass them as bytestrings or Unicode. However, if you - pass a bytestring that cannot be converted to Unicode using the naive - ASCII codec, a ``UnicodeDecodeError`` will be raised. This is purposeful - and helps you manage proper encoding for all content you store in - memory, read from various sources and write back. - -.. [2] Life gets much easier when you understand that you basically manage - **text** in your application. You don't care about bytes but about - letters. In that regard the concept of content encoding is meaningless. - The only time when you deal with raw bytes is when you write the data to - a file. Then you have to specify how your text should be encoded. On - the other end, to get meaningful text from a file, the application - reading it has to know which encoding was used during its creation. But - once the bytes are read and properly decoded, all you have is text. This - is especially powerful when you start interacting with multiple data - sources. Even if each of them uses a different encoding, inside your - application data is held in abstract text form. You can program your - business logic without worrying about which data came from which source. - You can freely exchange the data you store between sources. Only - reading/writing files requires encoding your text to bytes. - For Enterprise ==============