Metadata-Version: 2.1
Name: pyphonebook
Version: 2.3.0
Summary: Python API to query the CERN LDAP personnel database.
Home-page: https://pyphonebook.docs.cern.ch
Author: Sara Zanzottera
Author-email: sara.zanzottera@cern.ch
License: LGPLv3+
Download-URL: https://gitlab.cern.ch/linuxsupport/rpms/pyphonebook
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: ~=3.6
Description-Content-Type: text/markdown
License-File: COPYING
Requires-Dist: ldap3
Requires-Dist: pyasn1
Requires-Dist: pyparsing
Provides-Extra: all
Requires-Dist: ldap3 ; extra == 'all'
Requires-Dist: pyasn1 ; extra == 'all'
Requires-Dist: pyparsing ; extra == 'all'
Requires-Dist: argparse-manpage ; extra == 'all'
Requires-Dist: pytest ; extra == 'all'
Requires-Dist: pytest-random-order ; extra == 'all'
Requires-Dist: pytest-cov ; extra == 'all'
Requires-Dist: pytest-console-scripts ; extra == 'all'
Requires-Dist: pytest-mock ; extra == 'all'
Requires-Dist: jq ; extra == 'all'
Requires-Dist: sphinx ; extra == 'all'
Provides-Extra: build
Requires-Dist: argparse-manpage ; extra == 'build'
Provides-Extra: core
Requires-Dist: ldap3 ; extra == 'core'
Requires-Dist: pyasn1 ; extra == 'core'
Requires-Dist: pyparsing ; extra == 'core'
Provides-Extra: dev
Requires-Dist: argparse-manpage ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-random-order ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: pytest-console-scripts ; extra == 'dev'
Requires-Dist: pytest-mock ; extra == 'dev'
Requires-Dist: jq ; extra == 'dev'
Requires-Dist: sphinx ; extra == 'dev'
Provides-Extra: doc
Requires-Dist: sphinx ; extra == 'doc'
Provides-Extra: test
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pytest-random-order ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'
Requires-Dist: pytest-console-scripts ; extra == 'test'
Requires-Dist: pytest-mock ; extra == 'test'
Requires-Dist: jq ; extra == 'test'

<img src="images/pyphonebook-with-text.png" alt="PyPhoneBook" width="70%"/>

---------------

Python API and small CLI tool to query the CERN LDAP personnel database.

The CLI is backward compatible with the old Perl version of PhoneBook.

![status](https://gitlab.cern.ch/linuxsupport/rpms/pyphonebook/badges/master/pipeline.svg) ![coverage](https://gitlab.cern.ch/linuxsupport/rpms/pyphonebook/badges/master/coverage.svg)

## Supported versions
This package is only supported on AlmaLinux 8/9 and RHEL 8/9 with Python3.

## Prerequisites
PyPhoneBook uses `ldap3`, which can be installed from [EPEL](https://fedoraproject.org/wiki/EPEL) on CentOS 8 with:
```bash
sudo dnf install -y python3-ldap3
```

For other distros, please refer to the
[`ldap3` documentation](https://ldap3.readthedocs.io/)

## Build dependencies
The following packages are needed for building

* python3-setuptools
* python3-ldap3

For Debian (and similar, unsupported) the following additional packages are needed:
* dh-python
* python3-stdeb (for Debian only)
* python3-argparse-manpage

For RHEL/CentOS (and similar) the following additional packages are needed:
* epel-rpm-macros
* argparse-manpage

## Packaging and installing
There are different ways to build and install this package.

### Directly build and install with pip
Once the prerequisites are covered, type:
```bash
pip install pyphonebook
```
You can verify the installation was successful by typing:
```bash
pyphonebook
```
You should see a help message.

### RPM
To build the rpm package do
```bash
make rpm
```
The resulting package can be installed via
```bash
sudo dnf install build/RPMS/noarch/pyphonebook-2.1.1-2.el8.noarch.rpm
```

### Debian package (unsupported, may break at any time)
To build the .deb package do
```bash
make deb
```
This will create a folder called ```deb_dist``` containing the final package which can be installed with
```bash
apt install deb_dist/python3-pyphonebook_2.1.1-1_all.deb
```

### Wheel package (unsupported, may break at any time)
to build a .whl package do
```bash
make wheel
```
The resulting package is stored in the newly created folder named ```dist``` and can be installed with pip.

## Usage

### As a CLI tool

For the CLI interface, type

```bash
pyphonebook
```

The CLI can be integrated with other tools with the `--terse` and `--json` output options.

To integrate PyPhoneBook with Python-based tools, please consider using
it as a Python dependency and leveraging the API, which can return
a JSON representation of the entries, and manipulate them as objects.

### As a Python package
The Python API is richer than the CLI interface. Please refer to the
[ReadTheDocs documentation](https://pyphonebook.docs.cern.ch)
for a complete description of the API and some usage examples.

### Read the code

In case of doubt, feel free to dive into the code. The entire codebase is
small and heavily commented, so that it can be understood by non experts too.

Also, `ldap3` takes care of most of the complexity related to LDAP servers
querying, so the rest of the code should pose no challenges.

## Contribute

Please report issues and make PR on the
[GitLab repository](https://gitlab.cern.ch/linuxsupport/rpms/pyphonebook).

Before submitting modifications, please run the tests to ensure your
modification did not introduce any regression.

