mutt_ldap.py: Don't load the config file if were being imported as a library

mutt_ldap.py: Rename sys to _sys on import

Keeping the namespace clean when __name__ == '__main__' is not really
important, but this way all the imports are consistently renamed.
This future-proofs the code in case those modules ever need to get
shifted to module-wide imports.

mutt_ldap.py: Add an output-encoding option

This avoids crashing with:

  UnicodeEncodeError: 'ascii' codec can't encode characters

when mutt_ldap.py's stdout is not connected to a terminal (and
therefore doesn't have sys.stdout.encodign set up).

  $ python2.7 -c "print(u'α')" | cat
  Traceback (most recent call last):
    File "<string>", line 1, in <module>
  UnicodeEncodeError: 'ascii' codec can't encode characters in
    position 0-1: ordinal not in range(128)
  $ python2.7 -c 'import sys; print(sys.stdout.encoding)'
  UTF-8
  $ python2.7 -c 'import sys; print(sys.stdout.encoding)' | cat
  None
  $ python3.2 -c "print('α')" | cat
  α
  $ python3.2 -c 'import sys; print(sys.stdout.encoding)'
  UTF-8
  $ python3.2 -c 'import sys; print(sys.stdout.encoding)' | cat
  UTF-8

Both settings should match the value of the Mutt configuration
variable $charset [1,2]:

On Thu, Jan 24, 2013 at 06:25:24PM +0000, Michael Elkins wrote:
> On Thu, Jan 24, 2013 at 12:36:02PM -0500, W. Trevor King wrote:
> > I have a script that queries for address completion using the
> > query_command setting, but the docs are silent on the encoding for
> > the arguments and expected output [1]. ...
>
> It expects the output to be in the same encoding as $charset.
> Mutt performs the RFC2047 encoding automatically.

On Thu, Jan 24, 2013 at 07:00:53PM +0000, Michael Elkins wrote:
> On Thu, Jan 24, 2013 at 01:42:34PM -0500, W. Trevor King wrote:
> > ...Is it also $charset for the argv input?
>
> Yes.

If you don't specify a $charset in your Mutt config, you can probably
get away with not specifying charsets for these config options,
because Mutt's default charset detection will likely match up with
Python's locale.getpreferredencoding().

[1]: http://marc.info/?l=mutt-dev&m=135905197022081&w=2
[2]: http://marc.info/?l=mutt-dev&m=135905407723082&w=2

README: Fix 'mutt-ldap.py' -> 'mutt_ldap.py' typos

These are out of date after:

  commit d3879f6e4509c35f0bcb79e0e4eb99a1d767fd35
  Author: W. Trevor King <wking@tremily.us>
  Date:   Sun Jan 20 14:13:42 2013 -0500

    mutt_ldap.py: Rename with underscore for package import

.gitignore: Ignore distutils' build output

MANIFEST.in: Distribute COPYING

COPYING: Add text of GPLv3

README.rst: Add symlink for GitHub rendering

README: Every stand-alone project desrves one

This is based on my usual template.  I also simplified the docstring
in mutt_ldap.py to stay DRY, since that information is now in the
README.

.gitignore: Ignore *.pyc (generated when you run setup.py)

setup.py: Package Mutt-LDAP using distutils

mutt_ldap.py: Rename with underscore for package import

If I'm breaking Mutt-LDAP as a stand-alone package, I should probably
make it importable.  Even if nobody else imports it, we can still want
this for setup.py-based installation.

CachedLDAPConnection: Lazy LDAP connections

This is faster, and it allows us to return cached results even when
the LDAP server is not available (e.g. if your network is down).

Add logging to stdout (via StreamHandler)

This makes it easy to trace execution and make sure everything is
happening as you think it should.  There's currently no command-line
switch to increase verbosity.  Once we drop support for Python 2.6,
I'll put in an argparse.ArgumentParser.

CachedLDAPConnection: Convert cache format from Pickle to JSON

Now that we're only storing text fields (via the cache.fields
configuration setting), this is pretty easy to change.

CachedLDAPConnection: Drop the old cache on version missmatch

The expected CachedLDAPConnection._cache_version tracks __version__,
so if you bump __version__, you invalidate the existing cache.  There
shouldn't be anything critical in the cache, and this is safer than
trying to remember to bump an independent _cache_version after major
changes.

Add a __version__ (for easier compatibility tracking)

CachedLDAPConnection: Add support for cache.longevity-days

Cull entries older than longevity-days (defaults to 14).  This
requires changing the cache values from a list of entries to a dict
with 'time' and 'entries' keys.  Hmm, I should probably add a
reasonable cache versioning scheme...

Prefix imported modules with underscores

This cleans up the namespace inside the module, and makes it less
likely that you'll clobber an imported module with a local variable
name.  I also removed imports for modules we no longer use.

Alphebetize standard library imports

Use hyphenated configuration options (instead of underscores)

I like them better ;).

CachedLDAPConnection: Don't cache fields we don't use

I had previously said:
> It would be nice to automatically detect and drop any non text
> fields, but that's probably not worth the trouble either...

Since the configuration ID is in the cached key, we already know
exactly which fields we need to save in the cache.  Only caching those
fields avoids binary fields and fields with large values (jpegPhoto is
both).  I made the cached fields configurable because the
CachedLDAPConnection instance doesn't know about the fields needed by
format_entry() and format_columns().  If you don't configure the
cached fields, a minimal default is setup in the main block.

Restructure around an LDAPConnection class

This keeps us organized and simplifies the connection API (using the
'with' statement).

I also simplified the cache structure to keep all cached entries in a
single pickled dict, to avoid calculating safe filenames for each
query.  The number of queries you make in 14 days will probably not be
large enough for any fan-out efficiencies to be worth the trouble.

I considered using JSON instead of Pickle, but JSON does not support
raw byte strings (e.g. jpegPhoto), and it's not worth encoding
non-text fields using Base64, etc., when Pickle already works.

It would be nice to automatically detect and drop any non text fields,
but that's probably not worth the trouble either...

Decode search results to Unicode and print as Unicode

LDAPv3 strings are encoded in UTF-8 [1], so use that encoding to
decode them in format_columns().  Adjust format_entry() and the main
block to handle the Unicode output from format_columns().

[1]: http://tools.ietf.org/html/rfc2251#section-4.1.2

Bump my copyright to 2013 and add Niels de Vos

Adapt to Unicode sys.argv

Convert sys.argv to Unicode (using a configurable encoding)

In Python 3, sys.argv is already Unicode, but there's no clean way to
do this automatically in Python 2 [1].  If your system doesn't use
UTF-8 for it's argv encoding, you should set system.argv-encoding in
your ~/.mutt-ldap.rc.  For example, if your system uses UTF-16, try:

  [system]
  argv-encoding = utf-16

[1]: http://bugs.python.org/issue2128

search: Move asynchronous result handling inside search()

The result of search() should be an iterable returning entries.  If we
want to use the asynchronous connection.search() and
connection.result(), that's fine, but we should handle the result
unpacking inside search().

One benefit to Wade's new generator approach is that we can start
formatting early entries while we wait for later entries to arrive.

search: `post` and `query` should be Unicode strings

They're being formatted into the Unicode `filterstr`.  Being explicit
here should make the transition to Python 3 less annoying.

Merge remote-tracking branch 'wberrier/master' into master

* wberrier/master:
  prevent an error when no search string is given
  Return partial results if the search takes a long time
  implement caching system for big/slow ldap servers
  make search fields configurable
  Add support for an optional display column
  Fix for python 2.6: add position indexes to format strings
  Add query filter section (in order to pare down results)
  Return results in a format that mutt expects
  fix typo in reference to .rc file
  Add Wade Berrier (me) to author/copyright list

prevent an error when no search string is given

Return partial results if the search takes a long time

An impartial result is better than no result.  Done by requiring search
to have a pre-allocated connection.

implement caching system for big/slow ldap servers

make search fields configurable

Add support for an optional display column

Again, according to http://www.mutt.org/doc/manual/manual-4.html#ss4.5

Fix for python 2.6: add position indexes to format strings

Turns out that omitting the indexes is only supported in python >= 2.7

It's possible this script would work with python < 2.6 but the old
format strings would be necessary

Add query filter section (in order to pare down results)

Return results in a format that mutt expects

According to: http://www.mutt.org/doc/manual/manual-4.html#ss4.5

fix typo in reference to .rc file

Add Wade Berrier (me) to author/copyright list

posts:ldap: update Python scripts to explicitly use Python 2.

python-ldap doesn't have a Python 3 version yet.  I made a few other
changes to increase Python 3 compatibility, and added a full copyright
blurb to abook-ldif-cleanup.py.

Also search on displayName in mutt-ldap.py and ldap-jpeg.py.

Also prefer displayName to cn when formatting names.

Add starttls support to mutt-ldap.py and ldap-jpeg.py.

Also remove `rdn` from the searched attributes, because I don't have
such a field in any of my schemas.

Add auth.gssapi option to mutt-ldap.py (for use with Kerberos).

Add GnuTLS and secure LDAP information.

Add mutt-ldap.py.