Skip to content

Commit

Permalink
Removed sections pertaining to Python 2 concerns.
Browse files Browse the repository at this point in the history
  • Loading branch information
jaraco committed Apr 14, 2024
1 parent 7a65ffc commit 4625d07
Showing 1 changed file with 0 additions and 115 deletions.
115 changes: 0 additions & 115 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
<http://docs.python.org/3/library/configparser.html#mapping-protocol-access>`_)::

>>> 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
<http://docs.python.org/3/library/configparser.html#customizing-parser-behaviour>`__
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
<http://docs.python.org/3/library/configparser.html#interpolation-of-values>`__):

* the classic ``%(string-like)s`` syntax (called ``BasicInterpolation``)

* a new ``${buildout:like}`` syntax (called ``ExtendedInterpolation``)

* fallback values may be specified in getters (`more info
<http://docs.python.org/3/library/configparser.html#fallback-values>`__)::

>>> config.get('closet', 'monster',
... fallback='No such things as monsters')
'No such things as monsters'

* ``ConfigParser`` objects can now read data directly `from strings
<http://docs.python.org/3/library/configparser.html#configparser.ConfigParser.read_string>`__
and `from dictionaries
<http://docs.python.org/3/library/configparser.html#configparser.ConfigParser.read_dict>`__.
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
==========
Expand Down Expand Up @@ -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
==============

Expand Down

0 comments on commit 4625d07

Please sign in to comment.