Skip to content

Commit

Permalink
Update README, bump version
Browse files Browse the repository at this point in the history
  • Loading branch information
askonomm committed Jan 1, 2025
1 parent 187c599 commit 2933d60
Show file tree
Hide file tree
Showing 2 changed files with 17 additions and 11 deletions.
24 changes: 15 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

![Coverage](https://raw.githubusercontent.com/askonomm/dompa/refs/heads/master/coverage-badge.svg)

A _work-in-progress_ HTML5 document parser. It takes an input of an HTML string, parses it into a node tree,
A _work-in-progress_ HTML5 document parser. It takes an input of an HTML string, parses it into a node tree,
and provides an API for querying and manipulating the node tree.

## Install
Expand All @@ -11,6 +11,8 @@ and provides an API for querying and manipulating the node tree.
pip install dompa
```

Requires Python 3.10 or higher.

## Usage

The most basic usage looks like this:
Expand All @@ -31,23 +33,25 @@ html = dom.html()

You can run queries on the node tree to get or manipulate node(s).

### `find`
### `query`

You can find nodes with the `find` method which takes a `Callable` that gets `Node` passed to it and that has to return
You can find nodes with the `query` method which takes a `Callable` that gets `Node` passed to it and that has to return
a boolean `true` or `false`, like so:

```python
from dompa import Dompa

dom = Dompa("<h1>Site Title</h1><ul><li>...</li><li>...</li></ul>")
list_items = dom.find(lambda n: n.name == "li")
list_items = dom.query(lambda n: n.name == "li")
```

All nodes returned with `find` are deep copies, so mutating them has no effect on Dompa's state.
All nodes returned with `query` are deep copies, so mutating them has no effect on Dompa's state.

### `update`
### `traverse`

You can update nodes with the `update` method which takes a `Callable` that gets a `Node` passed to it, and has to
The `traverse` method is very similar to the `query` method, but instead of returning deep copies of data it returns a
direct reference to data instead, meaning it is ideal for updating the node tree inside of Dompa. It takes a `Callable`
that gets a `Node` passed to it, and has to
return the updated node, like so:

```python
Expand All @@ -57,13 +61,15 @@ from dompa.nodes import Node, TextNode

dom = Dompa("<h1>Site Title</h1><ul><li>...</li><li>...</li></ul>")


def update_title(node: Node) -> Optional[Node]:
if node.name == "h1":
node.children = [TextNode(value="New Title")]

return node

dom.update(update_title)

dom.traverse(update_title)
```

If you wish to remove a node then return `None` instead of the node.
4 changes: 2 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[project]
name = "dompa"
version = "0.4.1"
version = "0.5.0"
description = "A HTML5 parser."
readme = "README.md"
requires-python = ">=3.10"
Expand All @@ -12,7 +12,7 @@ classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
"Development Status :: 3 - Alpha"
"Development Status :: 4 - Beta"
]

[tool.black]
Expand Down

0 comments on commit 2933d60

Please sign in to comment.