Skip to content

Commit 08d53c7

Browse files
awolverpawolverp
committed
Complete documentation and update README.md
1 parent 122a8ad commit 08d53c7

File tree

5 files changed

+71
-23
lines changed

5 files changed

+71
-23
lines changed

‎README.md

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,17 @@
44
<p align="center">
55
<em>The fast, most optimal, and correct HTML & XML parsing library</em>
66
</p>
7+
<p align="center">
8+
<a href="https://awolverp.github.io/markupever" target="_blank"><b>Documentation</b></a> | <a href="https://github.com/awolverp/cachebox/releases"><b>Releases</b></a> | <a href="https://awolverp.github.io/markupever/#performance" target="_blank"><b>Benchmarks</b></a>
9+
</p>
710

11+
![text](https://img.shields.io/badge/coverage-100-08000)
12+
![image](https://img.shields.io/pypi/v/markupever.svg)
13+
![image](https://img.shields.io/pypi/l/markupever.svg)
14+
![image](https://img.shields.io/pypi/pyversions/markupever.svg)
15+
![python-test](https://github.com/awolverp/markupever/actions/workflows/test.yml/badge.svg)
816

9-
---
10-
11-
**DOCUMENTATION**: <a href="https://awolverp.github.io/markupever" target="_blank">https://awolverp.github.io/markupever</a>
12-
13-
**SOURCE CODE**: <a href="https://github.com/awolverp/markupever" target="_blank">https://github.com/awolverp/markupever</a>
14-
15-
---
17+
------
1618

1719
MarkupEver is a modern, fast (high-performance), XML & HTML languages parsing library written in Rust.
1820

@@ -23,11 +25,6 @@ MarkupEver is a modern, fast (high-performance), XML & HTML languages parsing li
2325
* 🧶 **Thread-safe**: Completely thread-safe.
2426
* 🎯 **Quering**: Use your **CSS** knowledge for selecting elements from a HTML or XML document.
2527

26-
> [!NOTE]\
27-
> ❤️ I ask for your support to continue on this path and make this Python library better and better ...
28-
> - Star this repository
29-
> - Tell me in issues your ideas and questions
30-
3128
## Installation
3229
You can install MarkupEver by using **pip**:
3330

@@ -76,8 +73,8 @@ print(root.serialize())
7673
- [x] Rewrite TreeDom `__repr__` and `__str__`
7774
- [x] Write benchmarks
7875
- [x] Write memory usage
79-
- [ ] Add PyPI version, downloads, test coverage, and python versions badges
80-
- [ ] Complete docs
76+
- [x] Add PyPI version, test coverage, and python versions badges
77+
- [x] Complete docs
8178
- [ ] Add prettier feature
8279
- [ ] Provide more control on serializer
8380
- [ ] Add advanced examples to docs (such as socket and http streams)

‎docs/docs/querying.md

Lines changed: 47 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,50 @@
11
---
2-
title: Querying
2+
title: CSS Selectors
33
---
44

5-
# Querying
6-
Comming Soon ...
5+
# CSS Selectors
6+
The **MarkupEver** supports all the syntax that [soupsieve](https://facelessuser.github.io/soupsieve/selectors/basic/) does, except for some pseudo-elements (I prefer not to document all these syntaxes again).
7+
8+
## Some Examples
9+
To start, imagine this document:
10+
11+
```python
12+
import markupever
13+
14+
tree = markupever.parse(
15+
"""
16+
<html>
17+
<head>
18+
<title>Example Document</title>
19+
</head>
20+
<body>
21+
<p class="par-one">CSS Selector Example</p>
22+
<p class="par-two">I wish you a good day</p>
23+
<p class="end-par">I wish you a good day</p>
24+
</body>
25+
</html>
26+
""",
27+
markupever.HtmlOptions()
28+
)
29+
```
30+
31+
Let's see some examples:
32+
33+
```python
34+
print(tree.select_one("head > title").text())
35+
# Example Document
36+
37+
for element in tree.select("[class^=par-]"):
38+
print(element)
39+
# Element(name=QualName(local="p", ns="http://www.w3.org/1999/xhtml", prefix=None), attrs=[(QualName(local="class"), "par-one")], template=false, integration_point=false)
40+
# Element(name=QualName(local="p", ns="http://www.w3.org/1999/xhtml", prefix=None), attrs=[(QualName(local="class"), "par-two")], template=false, integration_point=false)
41+
42+
print(tree.select_one("p", offset=3))
43+
# Element(name=QualName(local="p", ns="http://www.w3.org/1999/xhtml", prefix=None), attrs=[(QualName(local="class"), "end-par")], template=false, integration_point=false)
44+
45+
for element in tree.select("[class*=par]", offset=3, limit=1):
46+
print(element)
47+
# Element(name=QualName(local="p", ns="http://www.w3.org/1999/xhtml", prefix=None), attrs=[(QualName(local="class"), "end-par")], template=false, integration_point=false)
48+
```
49+
50+

‎docs/docs/treedom.md

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -143,9 +143,16 @@ Let's discuss about `first_child`, `last_child`, `parent`, `next_sibling` and `p
143143
# Text(content="\n ")
144144
```
145145

146-
"While these properties are useful, they might not always meet our needs. In such cases, methods like `.children()`, `.ancestors()`, `.prev_siblings()`, `.next_siblings()`, `.first_children()`, `.last_children()`, `.traverse()`, and `.descendants()` can provide additional functionality.
147-
148-
...
146+
While these properties are useful, they might not always meet our needs. In such cases, methods like `.children()`, `.ancestors()`, `.prev_siblings()`, `.next_siblings()`, `.first_children()`, `.last_children()`, `.traverse()`, and `.descendants()` can provide additional functionality.
147+
148+
* **children()** - Returns an iterator which iterates over children of node.
149+
* **ancestors()** - Returns an iterator which iterates over ancestors (parents) of node.
150+
* **prev_siblings()** - Returns an iterator which iterates over previous siblings of node.
151+
* **next_siblings()** - Returns an iterator which iterates over next siblings of node.
152+
* **first_children()** - Returns an iterator which iterates over first children.
153+
* **last_children()** - Returns an iterator which iterates over last children.
154+
* **traverse()** - Returns a traverse iterator.
155+
* **descendants()** - Returns an iterator which iterates over a node and its descendants.
149156

150157
## Build a document
151158
In **MarkupEver**, we use a class named `TreeDom` (1) as a tree structure. This class allows you to work with the document — move, create, remove, select, serialize, and more. In this tutorial, <u>we'll create a document without using the `Parser` class</u>. We'll focus on `TreeDom` properties and methods.

‎python/markupever/_display.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import typing
22

33

4-
class _DisplayCharacterToken:
4+
class _DisplayCharacterToken: # pragma: no cover
55
__slots__ = ("siblings", "children")
66

77
def __init__(self, siblings: bool):
@@ -24,7 +24,7 @@ def __str__(self):
2424
return "└── "
2525

2626

27-
class _Indentation:
27+
class _Indentation: # pragma: no cover
2828
__slots__ = ("tokens", "ignore_root")
2929

3030
def __init__(self, ignore_root: bool):

‎python/markupever/dom.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ def __str__(self) -> str:
7777
indent.indent(edge.node.next_sibling is not None)
7878
res += str(indent) + str(edge.node) + "\n"
7979

80-
else:
80+
else: # pragma: no cover
8181
indent.indent(edge.node.next_sibling is not None)
8282
res += str(indent) + str(edge.node) + "\n"
8383
indent.deindent()

0 commit comments

Comments
 (0)