Developer Guide

tl;dr

pip install . .[docs] .[dev] .[test]
make all    # build wheel
make check  # run unit tests
make dist   # build sdist
make html   # build documentation
make lint   # run project linter

Project Layout

  • .github/ contains GitHub specific workflows, actions, and templates.

  • docs/ contains project documentation, including the source for the sphinx-generated documentation.

  • rule34Py/ contains the source code for the rule34Py package.

  • tests/ contains the project test suite.

    • tests/unit/ contains the project unit-tests, which can be run without building or installing the project.

Building the project from source

This project can be built directly from source using a few host tools. Supported development environments include:

  • Ubuntu 24.04

  • Windows

The following instructions are written on the assumption that you are building in a Linux environment.

  1. Start by cloning the repository with git.

    git clone https://github.com/b3yc0d3/rule34Py.git
cd rule34Py

  2. (Optional. Recommended.) Setup a python virtual environment.

    python -m venv .venv
echo "/.venv" >>.git/info/exclude  # excludes your venv from git tracking
source .venv/bin/activate

  3. Install project python dependencies from the pyproject.toml file. Use GNU Make to build the project. The all make target (the default) builds the project’s wheels.

    pip install . .[dev]
make all

    Build output will be placed in the :build/ directory in your workspace.

Note

If you are using a very old python environment, your installed version of setuptools and python may not be aware of how to process pyproject.toml files. If this seems to be the case, try upgrading your build tools by calling python -m pip install --upgrade setuptools build.

Other make targets are supported to clean the project and build other artifacts. Generally, the project Makefile honors the GNU Standard Targets specification.

Running the project test suite

  1. Setup your build environment as in the “Building the project from source” section.

  2. Install the optional test dependencies and invoke their make target.

    pip install .[test]
make test

For more information, reference the :tests/README.md file.

Building the project documentation

  1. Setup your build environment as in the “Building the project from source” section.

  2. Install the optional docs dependencies and invoke their make target.

    pip install .[docs]
make html

    Build output will be placed in the :build/html/ directory.

  3. (Optional.) Host the build output locally to test changes.

    cd build/html
python -m http.server 8080

    Python will host the docs site at http://localhost:8080.

Integrating this project

This project is licensed under the GPLv3 license. Ensure that your project’s licensing strategy is compatible with the GPL. For more information, reference the GNU reference guide for GPLv3 here.

All direct dependencies of this project are either GPL licensed, or are licensed more permissively. But testing code does call the reponses module, which is licensed under the Apache 2.0 license. Reference the :NOTICE.md file for more information.