This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

The counterparts module takes mappings, specified via files in the ConfigParser[1] format (default file name: .counterc), and uses them to look up a string value corresponding to each string that it is given. For example, given a file with a different path in your present tree than in another tree, when generating a list of files, you might wish to automatically substitute that other tree’s path (the counterpart of the present path). First you would keep a list of those special cases in a human-readable config file, and second, arrange to let your shell or Python script use whatever counterparts finds.

The counterpart command provides shell access to the string mapping abilities of the counterparts module. Help for that command is available[2] by running counterpart --help.

Notice the slightly different names of counterpart (the shell command) and counterparts (the Python module). Besides giving a clue as to which is being referred to, the choice of names reflects that the command is for looking up a counterpart whereas the module is a more general treatment of counterparts. Except where noted, the counterpart command and the counterparts module behave the same: The command is essentially a front-end to the module’s get_counterpart_mapping function; it runs the input string(s) through the returned mapping, echoing the results as specified.

[2]counterpart is available after installing counterparts and updating your PATH environment variable if necessary.


Python 2.6+ and Python 3 are supported.

Tests have been run (and passed) on:

  • Mac OS X 10.5 and 10.8, using Python 2.7 and 3.4.


pip is the recommended way to obtain and install counterparts:

pip install counterparts

Written in Python, this package’s source code is on GitHub:

git clone

From the top-level source directory, the usual setuptools operations are available, i.e.:

python install

Usage Summary

By default, counterparts tries to read both ~/.counterc and ./.counterc. Their existence is optional. Any additional config files specified by the caller are mandatory. In general, ConfigParser overrides earlier values with ones from files read later, so values in a user-supplied config file take precedence over the default files when they exist.

Given a .counterc file in the PWD containing:

foo = bar

Using the counterpart command:

$ counterpart foo

$ diff foo `counterpart foo`
# output diff between foo and bar

$ counterpart baz
Traceback (most recent call last):
KeyError: 'Mapping not found in COUNTERPART_MAP: baz'

Because counterparts expects ConfigParser-format files, the sections in [SQUARE BRACES] are case sensitive, but the option lines (left-hand side) ignore case. Therefore, in the above config example: foo, Foo, and FOO would all map to bar, even though [COUNTERPART_map] will not work correctly in place of [COUNTERPART_MAP].

Next, using the counterparts module:

import counterparts
before = "foo"
after = counterparts.map_counterpart(before)

# or, to avoid need for repeated map_counterpart calls to re-read config file(s):
mapping = counterparts.get_counterpart_mapping()
after = mapping[before]
# the variable 'after' is assigned the value '"bar"'

You can specify, via a COUNTERPART_DIR section, a default mapping for strings (“paths” in this case) that are not listed in the COUNTERPART_MAP. The prepend_path option in the COUNTERPART_DIR section tells counterparts to prepend its value to any input that doesn’t hit in the COUNTERPART_MAP.

So, for example, given the .counterc:

up = ..
foo = %(home)s/bar
prepend_path = %(up)s/quux

$ counterpart baz

The previous .counterc example also shows another feature: home is pre-populated in the DEFAULT section. Hence, you can manually provide a path relative to $HOME to use in the other sections’ right-hand-side values:

$ [ `counterpart foo` == "$HOME/bar" ] && echo '%(home)s equals $HOME'
%(home)s equals $HOME

Finally, counterparts also supports an INCLUDE directive. It is specified as a section by that same name, and it accepts a paths option, which is a newline-separated list of one or more other config files. Some files that demonstrate valid uses of the INCLUDE section are:

  • tests/counterparts_data/conf-include-logging
  • tests/counterparts_data/conf-include-more
  • tests/counterparts_data/conf-2-with-include
  • tests/counterparts_data/conf-include-still-more

The INCLUDE section has proven useful for things like controlling logging, setting site-specific options, and picking up global defaults.

Configuration File

The configuration file is in the format used by the ConfigParser module. See Documentation, below, for more about the format.

The special sections and options used by counterparts are described above in the Usage Summary.

The sections and options can be read from the config files of other applications, as long as those applications ignore unknown sections and counterparts is told to look in those files.

If no configuration file is provided to counterparts, it looks first in ./.counterc and second in ~/.counterc.


For the most part, you’re looking at it.

For some useful information on ConfigParser-format files, see:


counterparts is released under the GPLv2, contained in the LICENSE.txt file.


Copyright (c) 2015 by Lionel D. Hummel.


I put counterparts up on GitHub to give me a bite-sized (but meaningful) sample with which to explore the site’s features such as continuous integration and documentation. So this is what I’ve got for its roadmap so far:

  • More tests and documentation are needed.

I’m glad to discuss an expanded roadmap if counterparts proves useful to any contributors besides myself.


counterparts is meant to be a solid, idiomatic, and readable example of Python code. I can think of several ways it is not quite there yet in this release. If you’ve got one in mind, please use the GitHub page to contact the author, ask questions, report bugs, suggest patches, receive updates, etc.:
Release History

Release History


This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
counterparts-0.1.tar.gz (11.3 kB) Copy SHA256 Checksum SHA256 Source Jul 17, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting