pbook 1.0
LDAP phonebook written in Python
License: MIT
Keywords: phonebook ldap

PBook
        =====
        
        LDAP phone book written in Python.
        
        
        Output examples
        ---------------
        
        Default search result:
        
            $ pbook john
            First name: John
             Last name: Doe
                E-mail: john.doe@example.com
             Telephone: +44123456789
                        123
                 Title: Placeholder name
                  City: London
             User name: jdoe
        
        Default search results using pattern search filter recognition:
        
            $ pbook 789
            First name: John
             Last name: Doe
                E-mail: john.doe@example.com
             Telephone: +44123456789
                        123
                 Title: Placeholder name
                  City: London
             User name: jdoe
        
        Default search result using LDAP field name decoration:
        
            $ pbook -d john
                  givenName: John
                         sn: Doe
                       mail: john.doe@example.com
            telephoneNumber: +44123456789
                             123
                      title: Placeholder name
                          l: London
                        uid: jdoe
        
        Search result using custom search filter:
        
            $ pbook -S 'title=place*'
            First name: John
             Last name: Doe
                E-mail: john.doe@example.com
             Telephone: +44123456789
                        123
                 Title: Placeholder name
                  City: London
             User name: jdoe
        
        Search result using the `name` search template:
        
            $ pbook -s name doe
            First name: John
             Last name: Doe
                E-mail: john.doe@example.com
             Telephone: +44123456789
                        123
                 Title: Placeholder name
                  City: London
             User name: jdoe
        
        Search result using the `multicolumn` template:
        
            $ pbook -t multicolumn john
             Last name | First name |                         E-mail |            Telephone
            -----------+------------+--------------------------------+----------------------
                   Doe |       John |           john.doe@example.com |    +44123456789, 123
        
        
        Requirements
        ------------
        
        * Python 2.7
        * Python LDAP module (http://www.python-ldap.org)
        
        
        Installation
        ------------
        
        In order to install pbook, just download the code, make sure all dependencies
        are installed (see [Requirements](https://github.com/jtyr/pbook#requirements)
        above) and configure it:
        
            $ git clone https://github.com/jtyr/pbook.git
            $ cd pbook
            $ chmod +x ./pbook
            $ # edit the pbook.conf file
            $ ./pbook -c ./pbook.conf john
        
        Or it's possible to use the Python setup script:
        
            $ git clone https://github.com/jtyr/pbook.git
            $ cd pbook
            $ python ./setup.py install
            $ # edit the /etc/pbook.conf file
            $ pbook john
        
        
        Configuration
        -------------
        
        Look at the `pbook.conf` for a full configuration example. The configuration
        can be defined globally (`/etc/pbook.conf`), per user (`~/.pbook`) or specified
        by an option on the command line (`pbook -c /path/to/pbook.conf john`). The
        configuration file is composed of the following 6 sections:
        
        
        **connection**
        
        In this section we configure the LDAP server connection. Server name, port and
        connection protocol is determined from the `uri` parameter. Password can be
        either defined in clear text or, if the value is set to `-1`, the user will be
        prompted. The recommended approach is to configure `ldapsearch` correctly
        first, and then re-use the parameters in this section. Example of the
        `ldapsearch` command:
        
            $ ldapsearch -H ldaps://ldap.example.com -D uid=jdoe,ou=Users,dc=example,dc=com -b ou=Users,dc=example,dc=com -W uid=jdoe
        
        From this command the configuration would be:
        
            [connection]
            uri=ldaps://ldap.example.com:636
            base_dn=ou=Users,dc=example,dc=com
            bind_dn=uid=jdoe,ou=Users,dc=example,dc=com
            password=-1
        
        
        **search_template**
        
        In this section we configure the LDAP search filter. The default search filter
        is defined by `_default` (e.g. `_default=nane`) or by the command line option
        `-s` (e.g. `pbook -s name john`). Example of search template definition:
        
            [search_template]
            _default=name
            name=(|(givenName=*%s*)(sn=*%s*))
        
        It's also possible to specify a custom search filter on the command line with
        the option `-S` (e.g. `pbook -S 'uid=%s' jdoe` or `pbook -S 'uid=jdoe'`).
        
        
        **search_pattern**
        
        On top of the default search filter, there is also pattern search filter
        recognition. This allows the configuration of a specific search filter based on
        a specified search string. For example, if all telephone numbers in the company
        have the same format except for the last 3 digits, we can define a pattern
        which will search the telephone number if the search string is a 3-digit
        number:
        
            [search_pattern]
            (\d{3})=(telephoneNumber=+44123456\1)
        
        Then we can search for a phone number `+44123456789` by executing `pbook 789`.
        
        
        **label**
        
        This section provides translation of the LDAP fields into a human readable
        format, which is then used in the `pbook` output. For example `givenName=First
        name` translates the `givenName` field to `First name` label.  It's mandatory
        to have a label for every field used in the template (read more bellow).
        Example of label definition:
        
            [label]
            givenName=First name
            sn=Last name
            telephoneNumber=Telephone
        
        
        **template**
        
        The default template is specified by the `_default` parameter (e.g.
        `_default=basic`) or by the command line option `-t` (e.g. `pbook -t basic
        john`). Templates can be defined in two forms. The first of which is a simple
        list of LDAP fields which will be translated into a line-separated list of
        labels and values. For example the following template:
        
            [template]
            _default=basic
            basic=(givenName,sn)
        
        generates the following output:
        
            First name: John
             Last name: Doe
        
        The second form is using the `printf` string format. For example the following
        template:
        
            multicolumn=%(givenName)10.10s | %(sm)10.10s
        
        generates the following output:
        
                  John |        Doe
        
        It is possible to specify a header for the output by a parameter named the same
        the template itself appended with `_header`. The header can refer to labels by
        the label name prefixed with two underscores. The header for the above example
        could look like this:
        
            multicolumn_header=%(__givenName)10.10s | %(__sn)10.10s\n-----------+-----------
        
        and the output would then look like this:
        
            First name |  Last name
            -----------+-----------
                  John |        Doe
        
        
        **output**
        
        This section is optional and may contain definition of replacements for LDAP
        values. In other words, it allows the manipulation of values coming from the
        LDAP search by using a regular expression. For example, if we want to display
        only last three digits of the `telephoneNumber`, we would define the following
        output replacement:
        
            [output]
            telephoneNumber=.*(\d{3})$;\1
        
        
        License
        -------
        
        This software is licensed by the MIT License which can be found in the file
        [LICENSE](http://github.com/jtyr/pbook/blob/master/LICENSE).