Setup

CLI

Most features of pdom can be accessed directly from its command-line tools. The easiest way to install them on your system is via pipx. pipx is a packagemenager for tools written in python that helps to keep them isolated and up to date. Some notes on how to get pipx running can be found at the end of this section. If you just need the CLI, use the following line to install pdom.

$ pipx install pdom

Library

You can also install the pdom library directly through the Python Package Index (PyPI) for use in your own projects. The use of a virtual environment is recommended.

$ pip install pdom

If the stable version of pdom on PyPI is missing a particular function, you can install the latest development version directly from the GitHub repository.

$ pip install -U git+https://github.com/theia-dev/pdom.git#egg=pdom

Developing and documentation

To work with the source code clone the repository from GitHub and install the requirements. The source code is accompanied by the documentation and an extensive collection of test cases.

$ git clone https://github.com/theia-dev/pdom.git
$ python3 -m venv pdom_env
$ . pdom_env/bin/activate
(pdom_env) $ pip install --upgrade pip
(pdom_env) $ pip install -r pdom/requirements.txt

Building the documentation locally needs a few extra python packages. They can also be installed in the same virtual environment with the following command.

(pdom_env) $ pip install -r pdom/docs/requirements.txt

The HTML version of the documentation can then be built:

(pdom_env) $ sphinx-build -b html pdom/docs pdom/docs_html

The tests are located under pdom/tests can be started with through:

(pdom_env) $ python -m unittest discover -s pdom/tests

pipx

Under macOS:

For macOS the Homebrew package manager is the easiest way to install pipx.

$ brew install pipx
$ pipx ensurepath

Under Linux:

For some distributions the python package system pip is not installed by default. On Debin/Ubuntu systems it can be quickly installed.

$ sudo apt update
$ sudo apt install python3-pip

Then pipx can be added.

$ python3 -m pip install --user pipx
$ python3 -m pipx ensurepath

Under Windows:

Python is not installed by default under Windows. You can get the installer from the Python download page. The python package system pip is already included in the latest releases.

In the windows commandline pipx can then be installed.

$ python3 -m pip install --user pipx
$ python3 -m pipx ensurepath

For more information on pipx refer to its documentation.