# Logilab’s common library

## What’s this ?

This package contains some modules used by different Logilab projects.

It is released under the GNU Lesser General Public License.

There is no documentation available yet but the source code should be clean and well documented.

Designed to ease:

- handling command line options and configuration files

- writing interactive command line tools

- manipulation of files and character strings

- manipulation of common structures such as graph, tree, and pattern such as visitor

- generating text and HTML reports

- more…

## Documentation

Documentation is available at https://logilab-common.readthedocs.io/

## Installation

logilab-common is available on pypi so you can install it using pip

    pip install logilab-common

Or alternatively extract the tarball, jump into the created directory and run

    python setup.py install

For installation options, see

    python setup.py install --help

## Building the documentation

Create a virtualenv and install dependencies

    virtualenv venv
    source venv/bin/activate

    # you need the krb5-config command to build all dependencies
    # on debian you can get it using "apt-get install libkrb5-dev"

    pip install doc/requirements-doc.txt

    # install logilab-common
    pip install -e .

Then build the doc

    cd doc
    make html

It’s now available under doc/_build/html/

## Code style

The python code is verified against flake8 and formatted with black.

- You can run tox -e black to check that the files are well formatted.

- You can run tox -e black-run to format them if needed.

- You can include the .hgrc to your own .hgrc to automatically run black before each commit/amend. This can be done by writing %include ../.hgrc at the end of your .hgrc.

## Comments, support, bug reports

Project page https://www.logilab.org/project/logilab-common

Use the cubicweb-devel at lists.cubicweb.org mailing list.

You can subscribe to this mailing list at https://lists.cubicweb.org/mailman/listinfo/cubicweb-devel

Archives are available at https://lists.cubicweb.org/pipermail/cubicweb-devel/

## Changelog

ChangeLog for logilab.common

## Provided modules

Here is a brief description of the available modules.

### Modules providing high-level features

- cache, a cache implementation with a least recently used algorithm.

- changelog, a tiny library to manipulate our simplified ChangeLog file format.

- clcommands, high-level classes to define command line programs handling different subcommands. It is based on configuration to get easy command line / configuration file handling.

- configuration, some classes to handle unified configuration from both command line (using optparse) and configuration file (using ConfigParser).

- proc, interface to Linux /proc.

- umessage, unicode email support.

- ureports, micro-reports, a way to create simple reports using python objects without care of the final formatting. ReST and html formatters are provided.

### Modules providing low-level functions and structures

- compat, provides a transparent compatibility layer between different python versions.

- date, a set of date manipulation functions.

- daemon, a daemon function and mix-in class to properly start an Unix daemon process.

- decorators, function decorators such as cached, timed…

- deprecation, decorator, metaclass & all to mark functions / classes as deprecated or moved

- fileutils, some file / file path manipulation utilities.

- graph, graph manipulations functions such as cycle detection, bases for dot file generation.

- modutils, python module manipulation functions.

- shellutils, some powerful shell like functions to replace shell scripts with python scripts.

- tasksqueue, a prioritized tasks queue implementation.

- textutils, some text manipulation functions (ansi colorization, line wrapping, rest support…).

- tree, base class to represent tree structure, and some others to make it works with the visitor implementation (see below).

- visitor, a generic visitor pattern implementation.

### Modules extending some standard modules

- debugger, pdb customization.

- logging_ext, extensions to logging module such as a colorized formatter and an easier initialization function.

- optik_ext, defines some new option types (regexp, csv, color, date, etc.) for optik / optparse

### Modules extending some external modules

- sphinx_ext, Sphinx plugin defining a autodocstring directive.

- vcgutils , utilities functions to generate file readable with Georg Sander’s vcg tool (Visualization of Compiler Graphs).

### To be deprecated modules

Those logilab.common modules will much probably be deprecated in future versions:

- testlib: use unittest2 instead

- interface: use zope.interface if you really want this

- table, xmlutils: is that used?

- sphinxutils: we won’t go that way imo (i == syt)

# Reference

Contents:

- logilab.common package
  - Subpackages
  - Submodules
  - logilab.common.cache module
  - logilab.common.changelog module
  - logilab.common.clcommands module
  - logilab.common.compat module
  - logilab.common.configuration module
  - logilab.common.daemon module
  - logilab.common.date module
  - logilab.common.debugger module
  - logilab.common.decorators module
  - logilab.common.deprecation module
  - logilab.common.fileutils module
  - logilab.common.graph module
  - logilab.common.interface module
  - logilab.common.logging_ext module
  - logilab.common.modutils module
  - logilab.common.optik_ext module
  - logilab.common.optparser module
  - logilab.common.proc module
  - logilab.common.pytest module
  - logilab.common.registry module
  - logilab.common.shellutils module
  - logilab.common.sphinx_ext module
  - logilab.common.sphinxutils module
  - logilab.common.table module
  - logilab.common.tasksqueue module
  - logilab.common.testlib module
  - logilab.common.textutils module
  - logilab.common.tree module
  - logilab.common.umessage module
  - logilab.common.urllib2ext module
  - logilab.common.vcgutils module
  - logilab.common.visitor module
  - logilab.common.xmlutils module
  - Module contents
- logilab.common.ureports package
  - Submodules
  - logilab.common.ureports.docbook_writer module
  - logilab.common.ureports.html_writer module
  - logilab.common.ureports.nodes module
  - logilab.common.ureports.text_writer module
  - Module contents

# Indices and tables

- Index

- Module Index

- Search Page