liburlparser Documentation

API References

Language Documentation

Full API reference for each language binding, generated from source.

C++ API C++17

Core library. Covers urlparser::url and urlparser::host (with hostname, ipv4, and ipv6 host variants), the lazily-loaded urlparser::psl Public Suffix List, and every accessor for protocol, userinfo, path, query, and fragment.

Generated with Doxygen

Open C++ Reference

Python API Python 3.10+

nanobind-based extension module exposing Url, Host, Hostname, IPv4, and IPv6 with the same interface as the C++ core, plus the liburlparser.utils helpers. Ships pre-built wheels for Linux, macOS, and Windows.

Generated with Sphinx

Open Python Reference

CLI Reference v2.1.0

Command-line tool for parsing a URL or a bare host straight from the terminal via the liburlparser command. Covers --url, --host, field selection with --parts, and JSON output.

Written in Markdown

Open CLI Reference

Get Started

Installation

Add liburlparser to your project in seconds.

bash

pip install liburlparser

Requires Python 3.10+. Ships a pre-built native extension for Linux, macOS, and Windows — no compiler needed.

CMake — FetchContent

# CMakeLists.txt
include(FetchContent)
FetchContent_Declare(
  liburlparser
  GIT_REPOSITORY https://github.com/mohammadraziei/liburlparser.git
  GIT_TAG        master
)
FetchContent_MakeAvailable(liburlparser)

target_link_libraries(my_app PRIVATE urlparser::urlparser)

Requires CMake 3.19+ and a C++17-compatible compiler. Link against urlparser::urlparser and include urlparser.h.

Option 1 — pip (recommended)

bash

pip install liburlparser

The Python package ships a pre-built native extension — no compiler or CMake needed. After install, the CLI is available as the liburlparser command.

Option 2 — build with CMake

bash

git clone https://github.com/mohammadraziei/liburlparser.git
cd liburlparser
cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_PYTHON=ON
cmake --build build -j$(nproc)

Requires CMake 3.19+, a C++17-compatible compiler, and Python 3.10+. Useful for a custom build configuration or a platform without a pre-built wheel.

Usage

Quick Examples

Parse a URL or host and pull out its parts in a few lines of code.

python

from liburlparser import Url, Host

# Parse a URL
url = Url("https://mail.google.com/about")
print(url.protocol)             # https

# The host is classified as a Hostname, IPv4, or IPv6
hostname = url.host.get_hostname()
print(hostname.domain)          # google
print(hostname.suffix)          # com

# Parse a bare host the same way
host = Host("mail.google.com")
hostname = host.get_hostname()
print(hostname.subdomain)       # mail
print(hostname.domain)          # google
print(hostname.suffix)          # com

# IPv4 / IPv6 hosts are classified automatically too
ip_host = Host("192.168.1.1")
print(ip_host.is_ipv4())        # True

c++

#include <iostream>
#include "urlparser.h"

int main() {
    // Parse a URL
    urlparser::url url("https://www.example.com/path?param=value#section");

    std::cout << "Protocol: " << url.protocol()  << "\n";
    std::cout << "Path: "     << url.abspath()   << "\n";
    std::cout << "Query: "    << url.query()     << "\n";
    std::cout << "Fragment: " << url.fragment()  << "\n";

    // Query parameters come back as raw "key=value" strings, split on '&'
    for (const auto& param : url.params()) {
        std::cout << "Param: " << param << "\n";
    }

    // The host is classified as a hostname, ipv4, or ipv6
    if (const auto* h = url.host().try_hostname()) {
        std::cout << "Domain: " << h->domain() << "\n";
        std::cout << "Suffix: " << h->suffix() << "\n";
    }
}

bash

# Parse a full URL, print it as JSON
liburlparser --url "https://www.example.com/about?x=1"

# Classify a bare host (domain, IPv4, or IPv6 - picked automatically)
liburlparser --host "192.168.1.1"

# Pull out just the parts you want
liburlparser --url "https://www.example.com/about" --parts domain suffix

# Version / docstring
liburlparser --version
liburlparser --doc