Software Heritage - Listers#

Collection of listers for source code distribution places like development forges, FOSS distributions, package managers, etc. Each lister is in charge to enumerate the software origins (e.g., VCS, packages, etc.) available at a source code distribution place.

A lister is a component from the Software Heritage stack aims to produce listings of software origins and their urls hosted on various public developer platforms or package managers. As these operations are quite similar, this package provides a set of Python modules abstracting common software origins listing behaviors.

It also provides several lister implementations, contained in the Python swh.lister.* modules. See this documentation for the list of supported listers.

Dependencies#

All required python dependencies can be found in the requirements*.txt files located at the root of the repository.

In order to be able to run all the listers (and thus execute the tests), some tools must be available on your system, namely:

  • opam

  • tar

  • psql

On a Debian-like system, you may use:

Local deployment#

Lister configuration#

Each lister implemented so far by Software Heritage (bitbucket, cgit, cran, debian, gitea, github, gitlab, gnu, golang, launchpad, npm, packagist, phabricator, pypi, tuleap, maven) must be configured by following the instructions below (please note that you have to replace <lister_name> by one of the lister name introduced above).

Preparation steps#

  1. mkdir ~/.config/swh/

  2. create configuration file ~/.config/swh/listers.yml

Configuration file sample#

Minimalistic configuration shared by all listers to add in file ~/.config/swh/listers.yml:

scheduler:
  cls: 'remote'
  args:
    url: 'http://localhost:5008/'

credentials: {}

Note: This expects scheduler (5008) service to run locally

Executing a lister#

Once configured, a lister can be executed by using the swh CLI tool with the following options and commands:

$ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister <lister_name> [lister_parameters]

Examples:

$ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister bitbucket

$ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister cran

$ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister gitea url=https://codeberg.org/api/v1/

$ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister gitlab url=https://salsa.debian.org/api/v4/

$ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister npm

$ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister pypi

Licensing#

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

See top-level LICENSE file for the full text of the GNU General Public License along with this program.

Overview#

Reference Documentation#