perfectpizza
Advanced tools
PerfectPizza is a blazing-fast, functional, and extensible HTML parser written in Python. Built as a modern alternative to BeautifulSoup, it focuses on performance, functional purity, and clean DOM traversal whilst providing comprehensive CSS selector support and immutable operations.
# Clone the repository
git clone https://github.com/yourusername/PerfectPizza.git
cd PerfectPizza
# Or copy the perfectpizza/ directory to your project
from perfectpizza import parse, select, select_one
# Parse HTML
html = '''
<div class="container">
<h1 id="title">Welcome to PerfectPizza!</h1>
<p class="intro">Fast, functional HTML parsing.</p>
<ul class="features">
<li class="feature">CSS4 selectors</li>
<li class="feature">Immutable operations</li>
<li class="feature">High performance</li>
</ul>
</div>
'''
doc = parse(html)
# Query with CSS selectors
title = select_one(doc, '#title')
print(title.text()) # "Welcome to PerfectPizza!"
features = select(doc, '.feature')
for feature in features:
print(f"• {feature.text()}")
# Quick parsing with selectors
paragraphs = pizza('<div><p>One</p><p>Two</p></div>', 'p')
print(len(paragraphs)) # 2
PerfectPizza/
├── perfectpizza/
│ ├── __init__.py # Main API exports
│ ├── dom.py # DOM node classes (Node, Document)
│ ├── parser.py # HTML parser and basic queries
│ ├── selectors.py # CSS selector engine
│ ├── mutations.py # Functional mutation operations
│ └── utils.py # Utilities (HTML output, extraction)
├── test/
│ └── test_parser.py # Comprehensive test suite
├── example.py # Feature demonstration
├── README.md # This file
└── .gitignore # Git ignore patterns
from perfectpizza import parse
doc = parse('<div class="box" id="main"><p>Hello world!</p></div>')
# Navigate the tree
div = doc.find_one('div')
print(div.tag) # 'div'
print(div.get_attr('class')) # 'box'
print(div.has_class('box')) # True
print(div.text()) # 'Hello world!'
# Tree traversal
for child in div.children:
print(child)
for ancestor in div.ancestors():
print(ancestor.tag)
from perfectpizza import select, select_one
# Basic selectors
select(doc, 'div') # All div elements
select(doc, '.class') # All elements with class
select(doc, '#id') # Element with ID
select(doc, '[attr]') # Elements with attribute
select(doc, '[attr="value"]') # Attribute equals value
# Advanced selectors
select(doc, 'div.class#id') # Combined selectors
select(doc, 'div > p') # Direct children
select(doc, 'div + p') # Adjacent siblings
select(doc, 'div ~ p') # General siblings
# Pseudo selectors
select(doc, 'li:first-child') # First child
select(doc, 'li:last-child') # Last child
select(doc, 'li:nth-child(2n+1)') # Odd children
select(doc, 'div:empty') # Empty elements
# Complex combinations
select(doc, 'div.container > ul.list li.item:not(:last-child)')
select(doc, 'article[data-category="tech"] h2.title')
from perfectpizza.mutations import (
set_attr, add_class, remove_class, append_child,
replace_text, clone_node
)
# All mutations return NEW instances
original = select_one(doc, 'div')
modified = add_class(original, 'new-class')
modified = set_attr(modified, 'data-version', '2.0')
print(original.get_classes()) # ['box']
print(modified.get_classes()) # ['box', 'new-class']
# Chain mutations functionally
result = (original
.pipe(lambda n: add_class(n, 'highlight'))
.pipe(lambda n: set_attr(n, 'role', 'main'))
.pipe(lambda n: append_child(n, new_paragraph)))
from perfectpizza.utils import (
extract_text, extract_links, extract_tables,
extract_images, extract_forms
)
# Extract all text content
text = extract_text(doc)
print(text) # Clean, whitespace-normalised text
# Extract structured data
links = extract_links(doc, base_url='https://example.com')
for link in links:
print(f"{link['text']} -> {link['url']}")
images = extract_images(doc)
tables = extract_tables(doc) # Returns list of 2D arrays
forms = extract_forms(doc) # Returns form structure with fields
from perfectpizza.utils import to_html, pretty_html
# Compact HTML
compact = to_html(doc)
# Pretty-printed HTML
pretty = pretty_html(doc, indent_size=2)
print(pretty)
import requests
from perfectpizza import parse, select
# Scrape a webpage
response = requests.get('https://example.com')
doc = parse(response.text)
# Extract article titles and links
articles = select(doc, 'article.post')
for article in articles:
title = select_one(article, 'h2.title')
link = select_one(article, 'a.permalink')
if title and link:
print(f"{title.text()} - {link.get_attr('href')}")
from perfectpizza import parse, select
from perfectpizza.mutations import filter_children, map_children
from perfectpizza.utils import extract_text
def clean_article(node):
"""Remove ads and clean up article content."""
# Remove advertisement blocks
cleaned = filter_children(node,
lambda child: not (isinstance(child, Node) and
child.has_class('ad')))
# Normalise text in paragraphs
cleaned = map_children(cleaned,
lambda child: replace_text(child, ' ', ' ')
if isinstance(child, Node) and child.tag == 'p'
else child)
return cleaned
# Process articles
html = get_article_html()
doc = parse(html)
articles = select(doc, 'article')
for article in articles:
clean_article_node = clean_article(article)
clean_text = extract_text(clean_article_node)
print(clean_text)
from perfectpizza import parse, select
from perfectpizza.utils import extract_tables
import pandas as pd
html = '''
<table class="data">
<thead>
<tr><th>Name</th><th>Age</th><th>City</th></tr>
</thead>
<tbody>
<tr><td>Alice</td><td>30</td><td>London</td></tr>
<tr><td>Bob</td><td>25</td><td>Paris</td></tr>
</tbody>
</table>
'''
doc = parse(html)
tables = extract_tables(doc)
if tables:
# Convert to pandas DataFrame
df = pd.DataFrame(tables[0][1:], columns=tables[0][0])
print(df)
parse(html: str, strict: bool = False) -> Document
Parse HTML string into DOM tree
select(node: Node, selector: str) -> List[Node]
Select all nodes matching CSS selector
select_one(node: Node, selector: str) -> Optional[Node]
Select first node matching CSS selector
pizza(html: str, selector: str = None)
Quick parse and select helper
.text(deep: bool = True) -> str - Extract text content.get_attr(name: str, default=None) -> str - Get attribute value.has_attr(name: str) -> bool - Check if attribute exists.has_class(class_name: str) -> bool - Check for CSS class.find_all(tag: str) -> List[Node] - Find descendants by tag.find_one(tag: str) -> Optional[Node] - Find first descendant.descendants() -> Iterator[Node] - Iterate all descendants.ancestors() -> Iterator[Node] - Iterate all ancestors.siblings() -> List[Node] - Get sibling nodesAll mutations return new Node instances:
set_attr(node, name, value) -> Node - Set attributeremove_attr(node, name) -> Node - Remove attributeadd_class(node, class_name) -> Node - Add CSS classremove_class(node, class_name) -> Node - Remove CSS classappend_child(node, child) -> Node - Append child nodereplace_text(node, old, new) -> Node - Replace text contentclone_node(node, deep=True) -> Node - Clone node treeto_html(node, pretty=False) -> str - Generate HTMLextract_text(node) -> str - Extract clean textextract_links(node, base_url=None) -> List[Dict] - Extract linksextract_tables(node) -> List[List[List[str]]] - Extract table dataextract_images(node, base_url=None) -> List[Dict] - Extract imagesfind_by_text(node, text, exact=False) -> List[Node] - Find by text contentRun the comprehensive test suite:
# Run all tests
python test/test_parser.py
# Run specific test class
python -m unittest test.test_parser.TestCSSSelectors
# Run with verbose output
python test/test_parser.py -v
Test coverage includes:
PerfectPizza is designed for speed and efficiency:
# Example performance test
import time
from perfectpizza import parse, select
# Generate large HTML (1000 articles)
large_html = generate_large_html(1000)
# Parsing performance
start = time.time()
doc = parse(large_html)
print(f"Parsed in {time.time() - start:.3f}s")
# Query performance
start = time.time()
articles = select(doc, 'article.post')
print(f"Selected {len(articles)} articles in {time.time() - start:.3f}s")
# Complex query performance
start = time.time()
titles = select(doc, 'article.post[data-category="tech"] h2.title')
print(f"Complex query found {len(titles)} titles in {time.time() - start:.3f}s")
Typical performance on modern hardware:
xpath(doc, '//div[@class="content"]//p'):contains(), :matches(), :not()Contributions are welcome! Here's how to get started:
git checkout -b feature/amazing-featurepython test/test_parser.pygit commit -m 'Add amazing feature'git push origin feature/amazing-featureMIT License - use freely and with extra cheese! 🧀
Copyright (c) 2025 Harry Graham
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Built with Python, logic, and love. 🍕
PerfectPizza - Because every HTML parser should be as satisfying as a perfect slice!
FAQs
A blazing-fast, functional HTML parser for Python
We found that perfectpizza demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A five-month operation turned 27 npm packages into durable hosting for browser-run lures that mimic document-sharing portals and Microsoft sign-in, targeting 25 organizations across manufacturing, industrial automation, plastics, and healthcare for credential theft.
Research
Fake “Phantom Shuttle” VPN Chrome extensions (active since 2017) hijack proxy auth to intercept traffic and continuously exfiltrate user credentials to attacker infrastructure.
Security News
/Product
Socket Firewall Free is now bundled into Docker Hardened Images, adding build-time and dependency-install supply chain protection on top of hardened base images for Node.js, Python, and Rust.