### Install readability-lxml with pip

Source: https://github.com/buriy/python-readability/blob/master/README.md

Use pip to install the library. This is the standard method for Python package installation.

```bash
pip install readability-lxml
```

--------------------------------

### Install readability-lxml with conda

Source: https://github.com/buriy/python-readability/blob/master/README.md

Alternatively, use conda with the conda-forge channel to install the library. This is useful for managing environments with conda.

```bash
conda install -c conda-forge readability-lxml
```

--------------------------------

### Readability CLI Usage Examples

Source: https://context7.com/buriy/python-readability/llms.txt

The `readability` CLI allows for quick ad-hoc extraction of articles from URLs or local HTML files. Options include specifying keywords, enabling verbose logging, and annotating output with XPath.

```bash
# Install
pip install readability-lxml

# Extract article from a URL, print title + summary to stdout
readability -u https://en.wikipedia.org/wiki/Pasta

# Extract from a local HTML file
readability article.html

# Open result in default browser (useful for debugging)
readability -b -u https://en.wikipedia.org/wiki/Pasta

# Enable verbose logging (1=WARNING, 2=INFO, 3=DEBUG)
readability -vvv -u https://example.com/article > output.html

# Use positive/negative keyword hints and save log
readability \
  -p "article-body,post-content" \
  -n "sidebar,advertisement" \
  --log /tmp/readability.log \
  -u https://example.com/article

# Annotate output with original XPath positions
readability -x -u https://example.com/article
```

--------------------------------

### Video Playback Event Handlers

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

Defines placeholder functions for various video playback events such as starting, playing, tracking ad countdowns, completion, pausing, and seeking. These are hooks for integrating video player functionality.

```javascript
function siVideoBegin(cvpInstance, videoId) { }
function siVideoPlay(cvpInstance, videoId) {
  var cvpData = cvpInstance.getContentEntry(videoId);
  var cvpObject = window.JSON.parse(cvpData);
  jQuery('#cnnCVPRecapDetails').show();
  jQuery('#cvpHeadline').html(cvpObject.headline);
  jQuery('#cvpDescription').html(cvpObject.description);
  jQuery('#cvpSource').html(cvpObject.source);
}
function siVideoPlayHead(cvpInstance, playheadTime, totalDuration) { }
function siVideoAdStarted(cvpInstance, videoId) { }
function siVideoTrackingAdCountdown(seconds) { }
function siVideoComplete(cvpInstance, videoId) { }
function siVideoPause(cvpInstance, videoId, paused) { }
function siVideoSeek() { }
```

--------------------------------

### Get Full Page Title from URL

Source: https://context7.com/buriy/python-readability/llms.txt

Fetches the HTML content from a URL using requests and then extracts the normalized text of the <title> tag using the Document class. Returns '[no-title]' if no title is found.

```python
import requests
from readability import Document

response = requests.get("https://en.wikipedia.org/wiki/Python_(programming_language)")
doc = Document(response.content)

title = doc.title()
print(title)
# Output: "Python (programming language) - Wikipedia"
```

--------------------------------

### JavaScript Performance Timing

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/too-many-images.sample.html

This script measures various performance metrics during page load, including response start time and total page time. It's useful for optimizing website performance.

```javascript
(function() { var b=window,f="chrome",g="jstiming",k="tick";(function(){function d(a){this.t={};this.tick=function(a,d,c){var e=void 0!=c?c:(new Date).getTime();this.t\[a\]=\[e,d\];if(void 0==c)try{b.console.timeStamp("CSI/"+a)}catch(h){}};this\[k\]("start",null,a)}var a;b.performance&&(a=b.performance.timing);var n=a?new d(a.responseStart):new d;b.jstiming={Timer:d,load:n};if(a){var c=a.navigationStart,h=a.responseStart;0<c&&h>=c&&(b\[g\]srt=h-c)}if(a){var e=b\[g\]load;0<c&&h>=c&&(e\[k\]("_wtsrt",void 0,c),e\[k\]("wtsrt	","_wtsrt",h),e\[k\]("tbsd	","wtsrt	"))}}catch(p){}})();b.tickAboveFold=function(d){var a=0;if(d.offsetParent){do a+=d.offsetTop;while(d=d.offsetParent)}d=a;750>=d&&b\[g\]load\[k\]("aft")};var l=!1;function m(){l||(l=!0,b\[g\]load\[k\]("firstScrollTime"))}b.addEventListener?b.addEventListener("scroll",m,!1):b.attachEvent("onscroll",m); })();
```

--------------------------------

### Get Raw Body HTML with Readability

Source: https://context7.com/buriy/python-readability/llms.txt

Use `Document.content()` to get the raw `<body>` HTML after lxml cleaning, without readability scoring. This is useful for preserving the entire cleaned document body.

```python
from readability import Document

html = """
<html>
  <head><title>Page</title></head>
  <body>
    <script>alert('xss')</script>
    <style>.foo { color: red }</style>
    <p>Main content here that is long enough to matter.</p>
    <div class="nav">Navigation links</div>
  </body>
</html>
"""

doc = Document(html)
body = doc.content()
# Scripts and styles are stripped by lxml Cleaner; content is preserved
assert "<script>" not in body
assert "<style>" not in body
assert "Main content" in body
print(body)
# Output: <body><p>Main content here that is long enough to matter.</p>
#         <div class="nav">Navigation links</div></body>
```

--------------------------------

### Get Article Author with Readability

Source: https://context7.com/buriy/python-readability/llms.txt

Use `Document.author()` to retrieve the author's name from the `<meta name="author">` tag. Returns `"[no-author]"` if the tag is missing or empty.

```python
from readability import Document

html_with_author = """
<html>
  <head>
    <title>Article Title</title>
    <meta name="author" content="Jane Doe">
  </head>
  <body>
    <p>Article content goes here with enough text to be recognized.</p>
  </body>
</html>
"""

doc = Document(html_with_author)
print(doc.author())  # "Jane Doe"

html_no_author = "<html><head><title>T</title></head><body><p>text</p></body></html>"
doc2 = Document(html_no_author)
print(doc2.author())  # "[no-author]"
```

--------------------------------

### Get Cleaned-Up Short Title

Source: https://context7.com/buriy/python-readability/llms.txt

Extracts a shortened version of the title by stripping site-name suffixes and prioritizing article-specific titles using heading elements and CSS heuristics. Includes special handling for CJK titles.

```python
from readability import Document

html = """
<html>
  <head><title>How to Cook Pasta | Best Recipe Site</title></head>
  <body>
    <h1>How to Cook Pasta</h1>
    <p>Bring a pot of salted water to boil. Cook pasta until al dente.</p>
  </body>
</html>
"""

doc = Document(html)
print(doc.title())        # "How to Cook Pasta | Best Recipe Site"
print(doc.short_title())  # "How to Cook Pasta"

# CJK example
html_cjk = """
<html>
  <head><title>Short Part | これは長いタイトルです</title></head>
  <body><p>コンテンツはここにあります。</p></body>
</html>
"""
doc_cjk = Document(html_cjk)
print(doc_cjk.short_title())  # "これは長いタイトルです"
```

--------------------------------

### Initialize Document with HTML String

Source: https://context7.com/buriy/python-readability/llms.txt

Basic initialization of the Document class with a raw HTML string. Supports optional parameters for fine-tuning content extraction.

```python
from readability import Document

# From a raw HTML string
html = """
<html>
  <head><title>My Blog - How to Cook Pasta | Recipe Site</title></head>
  <body>
    <nav><a href="/">Home</a> <a href="/about">About</a></nav>
    <article class="post-content">
      <h1>How to Cook Pasta</h1>
      <p>Bring a large pot of salted water to a rolling boil over high heat.
         Add 500g of dried pasta and cook according to package instructions,
         usually 8–12 minutes, until al dente.</p>
      <p>Reserve a cup of pasta water before draining. This starchy water
         helps emulsify sauces and is essential for a silky finish.</p>
    </article>
    <div class="sidebar">Sponsored links...</div>
    <div id="comments">User comments...</div>
  </body>
</html>
"""

# Basic usage
doc = Document(html)

# With all options
doc = Document(
    html,
    positive_keywords=["post-content", "article"],  # boost these class/id patterns
    negative_keywords=["sidebar", "advertisement"],  # suppress these patterns
    url="https://example.com/recipe/pasta",           # resolve relative links
    min_text_length=25,    # paragraphs shorter than this are ignored (default: 25)
    retry_length=250,      # minimum article length before retrying (default: 250)
    xpath=False,           # if True, adds x="xpath" attributes to each node
    handle_failures="discard",  # lxml link resolution failure handling
)
```

--------------------------------

### Initialize Sports Data Variables

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

Sets up variables for sports ID, path, feed name, and viewcast status. These are typically used for fetching and displaying sports-related data.

```javascript
var SPORTID = "MLB";
var PATH = "/baseball/mlb/scoreboards/2012/04/16/";
var FEEDNAME = "scoreboard.dat";
isViewcast = true;
```

--------------------------------

### Document Constructor

Source: https://context7.com/buriy/python-readability/llms.txt

Initializes a readability document from HTML input. Supports various options for customization.

```APIDOC
## Document(input, ...)

### Description
Initializes a readability document from an HTML string, bytes, or an existing `lxml` element/tree. The document is not re-entrant; create a new `Document` for each page. Parsing is lazy — the HTML is not processed until a method is called.

### Parameters
- **input**: (string, bytes, or lxml element/tree) - The HTML content to parse.
- **positive_keywords**: (list of strings, optional) - Class/id patterns to boost candidate nodes.
- **negative_keywords**: (list of strings, optional) - Patterns to suppress candidate nodes.
- **url**: (string, optional) - Base URL for resolving relative links.
- **min_text_length**: (int, optional) - Minimum text length for paragraphs to be considered (default: 25).
- **retry_length**: (int, optional) - Minimum article length before retrying (default: 250).
- **xpath**: (bool, optional) - If True, adds x="xpath" attributes to each node (default: False).
- **handle_failures**: (string, optional) - lxml link resolution failure handling.

### Request Example
```python
from readability import Document

html = """
<html>
  <head><title>My Blog - How to Cook Pasta | Recipe Site</title></head>
  <body>
    <nav><a href="/">Home</a> <a href="/about">About</a></nav>
    <article class="post-content">
      <h1>How to Cook Pasta</h1>
      <p>Bring a large pot of salted water to a rolling boil over high heat.
         Add 500g of dried pasta and cook according to package instructions,
         usually 8–12 minutes, until al dente.</p>
      <p>Reserve a cup of pasta water before draining. This starchy water
         helps emulsify sauces and is essential for a silky finish.</p>
    </article>
    <div class="sidebar">Sponsored links...</div>
    <div id="comments">User comments...</div>
  </body>
</html>
"""

# Basic usage
doc = Document(html)

# With all options
doc = Document(
    html,
    positive_keywords=["post-content", "article"],
    negative_keywords=["sidebar", "advertisement"],
    url="https://example.com/recipe/pasta",
    min_text_length=25,
    retry_length=250,
    xpath=False,
    handle_failures="discard",
)
```
```

--------------------------------

### Document Initialization with Keywords

Source: https://context7.com/buriy/python-readability/llms.txt

Allows biasing the scoring of candidate elements during content extraction by providing positive and negative keywords. These keywords can be strings or compiled regular expressions that match against the `class` or `id` attributes of nodes, influencing the selection of the main article content.

```APIDOC
## Document(positive_keywords, negative_keywords)

### Description
Initializes the `Document` object with `positive_keywords` and `negative_keywords` to bias the candidate scoring. This feature adds or subtracts 25 points to a node's score if its `class` or `id` attribute matches the provided patterns. It accepts comma-separated strings, lists of strings, or compiled `re.Pattern` objects. This is useful for sites where default readability heuristics may not yield optimal results.

### Parameters
* `positive_keywords` (str | list[str] | re.Pattern) - Keywords or patterns to positively bias candidate scoring.
* `negative_keywords` (str | list[str] | re.Pattern) - Keywords or patterns to negatively bias candidate scoring.

### Request Example
```python
import re
from readability import Document

html = """
<html>
  <head><title>News Article</title></head>
  <body>
    <div class="news-item main-story">
      <p>Breaking: Scientists discover new species of deep-sea fish in the
         Pacific Ocean. The discovery was made by researchers from the
         University of Hawaii during a routine survey.</p>
      <p>The fish, tentatively named Abyssalus pacificus, was found at a
         depth of 4,000 meters and exhibits bioluminescent properties
         never before observed in this genus.</p>
    </div>
    <div class="mysidebar related-links">
      <a href="/story1">Related story 1</a>
      <a href="/story2">Related story 2</a>
    </div>
  </body>
</html>
"""

# Using a list of strings
doc = Document(
    html,
    positive_keywords=["news-item", "main-story"],
    negative_keywords=["mysidebar", "related-links"],
)
similarity = doc.summary(html_partial=True)
assert "Scientists discover" in similarity
assert "Related story" not in similarity

# Using a compiled regex
doc2 = Document(
    html,
    positive_keywords=re.compile(r"news|main|article|story"),
    negative_keywords=re.compile(r"sidebar|related|ads|promo"),
)
summary2 = doc2.summary(html_partial=True)
assert "bioluminescent" in summary2
```

### Response
#### Success Response
Initializes the Document object with the specified keywords, affecting subsequent calls to methods like `summary()`.
```

--------------------------------

### Open Blogger Navbar Iframe

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/too-many-images.sample.html

Opens a Blogger navbar iframe with specified parameters. Ensure the 'gapi.iframes' library is loaded.

```javascript
gapi.load("gapi.iframes:gapi.iframes.style.bubble", function() { if (gapi.iframes && gapi.iframes.getContext) { gapi.iframes.getContext().openChild({ url: '//www.blogger.com/navbar.g?targetBlogID\075113083922500631895\46blogName\75melposen.blogspot.no\46publishMode\75PUBLISH\_MODE\_BLOGSPOT\46navbarType\75LIGHT\46layoutType\75LAYOUTS\46searchRoot\75http://melposen.blogspot.com/search\46blogLocale\75no\46v\0752\46homepageUrl\75http://melposen.blogspot.com/\46targetPostID\0754645670632029404989\46blogPostOrPageUrl\75http://melposen.blogspot.com/2012/02/saftsentrifuge.html\46vt\75-6326341907690819742', where: document.getElementById("navbar-iframe-container"), id: "navbar-iframe" }); } });
```

--------------------------------

### Ad Configuration Initialization

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

Initializes an ad configuration object with a specific ID and enables scientific tracking for ad performance. This is used for setting up advertising on the page.

```javascript
var adConfig=new TiiAdConfig('3475.si2');
adConfig.setRevSciTracking(true);
```

--------------------------------

### Dynamic Ad Query String Construction

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

Constructs a query string for ad requests, including ad configuration details and factory parameters. It also includes logic to append debug parameters if debug mode is enabled.

```javascript
var adFactory = new TiiAdFactory(adConfig, "mlb/gameflashpage");
iframeAdFactory.queryString = 'TiiAdConfig=3475.si2&adConfigPairs=' + '&TiiAdFactory=' + encodeURIComponent('mlb/gameflashpage') + '&adFactoryPairs=' + '&paramPairs=' + encodeURIComponent('sport=mlb');
if (TiiAdsIsDebugMode()) {
  iframeAdFactory.queryString += '&debugads=y';
}
```

--------------------------------

### JavaScript for SI Tracking Initialization

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

This JavaScript code initializes the SI tracking system and sends ADM data. It also defines a function to determine Quantcast labels based on page section information.

```javascript
siTracking.init(); //ADM cnnad_sendADMData(); cnnad_ugsync(); function siQuantcast() { var lb = "Time Inc News Business and Sports,Sports Illustrated"; var lb_ch = (jsmd.get("m:page.section\[0\]") ? jsmd.get("m:page.section\[0\]") : ""); lb+=(lb_ch != null && typeof(lb_ch) == "string" && lb_ch.length > 0) ? "." + lb_ch:""; return lb; } \_qoptions={ qacct:"p-5dyPa639IrgIw", labels:siQuantcast() };
```

--------------------------------

### Dynamic Subscription Content Generation (JavaScript)

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

This JavaScript code dynamically generates HTML for subscription offers based on a random condition. It's used to display different promotional content.

```javascript
var min=1; var max=2; x = Math.floor(Math.random() * (max - min + 1)) + min; if(x/2 == 1) { document.write('<dt><a href="https://subscription.si.com/storefront/Give-the-Gift-of-Sports-Illustrated/site/si-donor0411jacket.html?xid=sirosheader&link=1001406" target="_blank" rel="nofollow" id="cnn_cm_subscribe0"><img src="http://i.cdn.turner.com/si/2011_images/cm/170x30.png" alt="Give the Gift of SI" title="Give the Gift of SI"/></a></dt>'); document.write('<dd><a href="https://subscription.si.com/storefront/Give-the-Gift-of-Sports-Illustrated/site/si-donor0411jacket.html?xid=sirosheader&link=1001406" target="_blank" rel="nofollow" id="cnn_cm_subscribe1"><img src="http://i.cdn.turner.com/si/2011_images/cm/170X110.jpg" alt="Give the Gift of SI" title="Give the Gift of SI"/></a></dd>'); } else { document.write('<dt><a href="http://www.si.com/swim2012" target="_blank" rel="nofollow" id="cnn_cm_subscribe0"><img src="http://i.cdn.turner.com/si/2012_images/cm/si-btn_swim.png" alt="Swimsuit 2012" title="Swimsuit 2012"/></a></dt>'); document.write('<dd><a href="http://www.si.com/swim2012" target="_blank" rel="nofollow" id="cnn_cm_subscribe1"><img src="http://i.cdn.turner.com/si/2012_images/cm/SWIM_2012_dropdown.png" alt="Swimsuit 2012" title="Swimsuit 2012"/></a></dd>'); }
```

--------------------------------

### Ad Factory and Refresh Interval

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

Configures the ad factory URL and sets up an interval to refresh ads every 45 seconds. This is crucial for dynamic ad loading and display.

```javascript
iframeAdFactory.url = '/si_adspaces/4.0/iframe.html';
window.setInterval(function(){
  iframeAdFactory.refresh()
}, 45000);
```

--------------------------------

### Generate SI Subscription Offers

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

This JavaScript code generates HTML for subscription offer buttons and dropdowns. It includes commented-out logic for a 50/50 split and a specific style for a dropdown element.

```javascript
var min=1; var max=2; x = Math.floor(Math.random() * (max - min + 1)) + min; /*turning off 50/50 for now*/ /*if(x/2 == 1) { document.write('<dt><a href="https://subscription.si.com/storefront/subscribe-to-sports-illustrated/link/1002346.html" target="_blank" rel="nofollow" id="cnn_cm_subscribe2"><img src="http://i.cdn.turner.com/si/.element/img/4.1/global/cm/button_subscribe_si_red.png" alt="Subscribe to SI" title="Subscribe to SI"/></a></dt>'); document.write('<dd><a href="https://subscription.si.com/storefront/subscribe-to-sports-illustrated/link/1002346.html" target="_blank" rel="nofollow" id="cnn_cm_subscribe4"><img src="http://i.cdn.turner.com/si/.element/img/4.1/global/cm/dropdown_subscribe_si_red.png" alt="Subscribe to SI" title="Subscribe to SI"/></a></dd>'); } else {*/ document.write('<dt><a href="https://subscription.si.com/storefront/subscribe-to-sports-illustrated/link/1002346.html" target="_blank" rel="nofollow" id="cnn_cm_subscribe2"><img src="http://i.cdn.turner.com/si/.element/img/4.1/global/cm/button_subscribe_si_red.png" alt="Subscribe to SI" title="Subscribe to SI"/></a></dt>'); document.write('<dd style="margin-left:-79px"><a href="https://subscription.si.com/storefront/subscribe-to-sports-illustrated/link/1002346.html" target="_blank" rel="nofollow" id="cnn_cm_subscribe4"><img src="http://i.cdn.turner.com/si/2012_images/cm/bn_2osi16579_290x162_v1.png" alt="Subscribe to SI" title="Subscribe to SI"/></a></dd>'); //}
```

--------------------------------

### Load Google Top Exp Script

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/too-many-images.sample.html

Dynamically loads the Google Top Exp script into the page's head. This is useful for integrating Google ad or analytics scripts.

```javascript
(function() { var script = document.createElement('script'); script.type = 'text/javascript'; script.src = '//pagead2.googlesyndication.com/pagead/js/google\_top\_exp.js'; var head = document.getElementsByTagName('head')\[0\]; if (head) { head.appendChild(script); }})();
```

--------------------------------

### Web Font Loading with Google Fonts

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/too-many-images.sample.html

Configures Google Fonts loading with specific font families and provides callbacks for loading and active states. Includes a fallback for Internet Explorer 6.

```javascript
if (navigator.userAgent.indexOf('MSIE 6') == -1) { WebFontConfig = { google: { families: [ 'Coming Soon' ], api: '//themes.googleusercontent.com/fonts/css?kit=myblyOycMnPMGjfPG-DzPz33tNpxd7DqNl3prDFz23I' }, loading: function() { if (window.jstiming) window.jstiming.load.tick('webfontLoading'); }, active: function() { if (window.jstiming) window.jstiming.load.tick('webfontActive'); } }; (function() { var wf = document.createElement('script'); wf.src = '//ajax.googleapis.com/ajax/libs/webfont/1/webfont.js'; wf.type = 'text/javascript'; wf.async = 'true'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(wf, s); })(); } else { document.documentElement.className = 'wf-inactive'; }
```

--------------------------------

### Document.short_title()

Source: https://context7.com/buriy/python-readability/llms.txt

Returns a shortened, cleaned-up version of the title, prioritizing article-specific titles over site names.

```APIDOC
## Document.short_title()

### Description
Returns a shortened version of the title by stripping site-name suffixes separated by `|`, `-`, `::`, or `/`. It cross-references heading elements (`h1`, `h2`, `h3`) and common CSS heuristics (`.title`, `#heading`, `.pageTitle`, etc.) to find the most likely article-specific title. Has special handling for CJK titles (min length 4, max 100 characters).

### Method
GET

### Endpoint
N/A (Method of Document object)

### Response
#### Success Response (200)
- **short_title** (string) - The cleaned-up article title.

### Response Example
```python
from readability import Document

html = """
<html>
  <head><title>How to Cook Pasta | Best Recipe Site</title></head>
  <body>
    <h1>How to Cook Pasta</h1>
    <p>Bring a pot of salted water to boil. Cook pasta until al dente.</p>
  </body>
</html>
"""

doc = Document(html)
print(doc.title())        # "How to Cook Pasta | Best Recipe Site"
print(doc.short_title())  # "How to Cook Pasta"

# CJK example
html_cjk = """
<html>
  <head><title>Short Part | これは長いタイトルです</title></head>
  <body><p>コンテンツはここにあります。</p></body>
</html>
"""
doc_cjk = Document(html_cjk)
print(doc_cjk.short_title())  # "これは長いタイトルです"
```
```

--------------------------------

### Extract Article Summary with Readability

Source: https://context7.com/buriy/python-readability/llms.txt

Use `Document.summary()` to extract the main article content. It can return full or partial HTML and optionally keep all images. Handle potential parsing errors with a try-except block.

```python
import requests
from readability import Document
from readability.readability import Unparseable

url = "https://www.theguardian.com/technology/2024/01/01/some-article"
response = requests.get(url, headers={"User-Agent": "Mozilla/5.0"})

doc = Document(response.content, url=url)

# Full HTML document output (default)
try:
    full_html = doc.summary()
    # Returns: <html><body><div><body id="readabilityBody">...</body></div></body></html>
    print(full_html[:200])
except Unparseable as e:
    print(f"Could not parse article: {e}")

# Partial HTML — just the article div, no wrapping html/body tags
partial_html = doc.summary(html_partial=True)
# Returns: <div><div class="article-body">...</div></div>
print(partial_html[:200])

# Keep all images (by default only the first/main image is retained)
html_with_images = doc.summary(keep_all_images=True)
assert "<img" in html_with_images
```

--------------------------------

### Promotional Image Link (HTML)

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

This HTML snippet displays a promotional image for 'MLB 2K 12' that links to a subscription page. It's used for direct marketing offers.

```html
<a href="https://subscription.si.com/storefront/subscribe-to-sports-illustrated/link/1009469.html"><img src="http://i.cdn.turner.com/si/2012_images/cm/si-btn3_MLB2K12.png" alt="Get MLB 2K 12 FREE" title="Get MLB 2K 12 FREE"/></a>
```

--------------------------------

### Document Accepting Pre-parsed lxml Trees

Source: https://context7.com/buriy/python-readability/llms.txt

The Document class can directly accept an `lxml` `HtmlElement` or `_ElementTree`, avoiding redundant parsing if the HTML is already in an lxml format.

```python
import lxml.html
from readability import Document

raw_html = b"""
<html>
  <head><title>Pre-parsed Document</title></head>
  <body>
    <p>Content that was already parsed by lxml for other reasons.</p>
    <p>Second paragraph with more content for the readability scorer.</p>
  </body>
</html>
"""

# Parse once with lxml
tree = lxml.html.fromstring(raw_html)

# Feed the lxml element directly — no second parse
doc = Document(tree)
print(doc.title())    # "Pre-parsed Document"
print(doc.summary())
```

--------------------------------

### Extract Title and Summary from HTML

Source: https://github.com/buriy/python-readability/blob/master/README.md

Import necessary libraries and use the Document class to parse HTML content fetched via requests. The title() method returns the document's title, and summary() returns the cleaned HTML body.

```python
>>> import requests
>>> from readability import Document

>>> response = requests.get('http://example.com')
>>> doc = Document(response.content)
>>> doc.title()
'Example Domain'

>>> doc.summary()
"""<html><body><div><body id=\"readabilityBody\">
<div>
    <h1>Example Domain</h1>
<p>This domain is established to be used for illustrative examples in documents. You may
    use this
    domain in examples without prior coordination or asking for permission.</p>
    <p><a href=\"http://www.iana.org/domains/example\">More information...</a></p>
</div>
</body>
</div></body></html>"""
```

--------------------------------

### Document with URL for Absolute Link Resolution

Source: https://context7.com/buriy/python-readability/llms.txt

When a URL is provided to the Document constructor, relative links (href, src) within the HTML are resolved to absolute URLs. This is crucial for rendering content outside its original domain.

```python
import requests
from readability import Document

url = "https://example.com/blog/my-article"
response = requests.get(url)

# Without url: relative links stay relative (/images/photo.jpg)
doc_no_url = Document(response.content)

# With url: relative links become absolute (https://example.com/images/photo.jpg)
doc_with_url = Document(response.content, url=url)

summary = doc_with_url.summary()
# All <a href="..."> and <img src="..."> are now absolute URLs
assert "https://example.com" in summary or len(summary) > 0
```

--------------------------------

### Document with XPath Annotations

Source: https://context7.com/buriy/python-readability/llms.txt

Setting `xpath=True` adds an 'x' attribute to each HTML element, indicating its XPath in the original document. This aids in mapping extracted content back to the source DOM.

```python
from readability import Document

html = """
<html>
  <body>
    <div class="article">
      <p>This is the main article paragraph with sufficient content.</p>
      <p>Second paragraph adding more substantive text to the article body.</p>
    </div>
  </body>
</html>
"""

doc = Document(html, xpath=True)
summary = doc.summary()
# Each element has x="..." attribute pointing to its original xpath
# e.g., <div x="/html/body/div" class="article">...</div>
assert 'x="' in summary
print(summary)
```

--------------------------------

### Promotional Dropdown Image Link (HTML)

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

This HTML snippet displays a promotional image for 'MLB 2K 12' designed for a dropdown, linking to a subscription page. It's an alternative format for marketing offers.

```html
<a href="https://subscription.si.com/storefront/subscribe-to-sports-illustrated/link/1009469.html"><img src="http://i.cdn.turner.com/si/2012_images/cm/si-MLB2K12-dropdown.jpg" alt="Get MLB 2K 12 FREE" title="Get MLB 2K 12 FREE"/></a>
```

--------------------------------

### Generate Random Subscription Offers

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

This JavaScript code generates a random number to decide which subscription offer to display. It's used for A/B testing or rotating promotions.

```javascript
var min=1; var max=2; x = Math.floor(Math.random() * (max - min + 1)) + min; if(x/2 == 1) { document.write('<dt><a href="https://subscription.si.com/storefront/subscribe-to-sports-illustrated/link/1006340.html" target="_blank" rel="nofollow" id="cnn_cm_subscribe0"><img src="http://i.cdn.turner.com/si/2011_images/cm/WS11_btn_champ_STL.png" alt="Get the Cardinals Championship Package" title="Get the Cardinals Championship Package"/></a></dt>'); document.write('<dd><a href="https://subscription.si.com/storefront/subscribe-to-sports-illustrated/link/1006340.html" target="_blank" rel="nofollow" id="cnn_cm_subscribe1"><img src="http://i.cdn.turner.com/si/2011_images/cm/WS11_dropdown_STL.png" alt="Get the Cardinals Championship Package" title="Get the Cardinals Championship Package"/></a></dd>'); } else { document.write('<dt><a href="https://subscription.si.com/storefront/subscribe-to-sports-illustrated/link/1007180.html" target="_blank" rel="nofollow" id="cnn_cm_subscribe0"><img src="http://i.cdn.turner.com/si/2011_images/cm/EA-N4S-TheRun-btn.png" alt="Get Need for Speed 12 FREE" title="Get Need for Speed 12 FREE"/></a></dt>'); document.write('<dd><a href="https://subscription.si.com/storefront/subscribe-to-sports-illustrated/link/1007180.html" target="_blank" rel="nofollow" id="cnn_cm_subscribe1"><img src="http://i.cdn.turner.com/si/2011_images/cm/EA-N4S-TheRun-SI-dropdown.jpg" alt="Get Need for Speed 12 FREE" title="Get Need for Speed 12 FREE"/></a></dd>'); }
```

--------------------------------

### Bias Readability Scoring with Keywords

Source: https://context7.com/buriy/python-readability/llms.txt

Customize content extraction by biasing scores using `positive_keywords` and `negative_keywords`. These can be strings, lists of strings, or compiled regex patterns to match `class` or `id` attributes.

```python
import re
from readability import Document

html = """
<html>
  <head><title>News Article</title></head>
  <body>
    <div class="news-item main-story">
      <p>Breaking: Scientists discover new species of deep-sea fish in the
         Pacific Ocean. The discovery was made by researchers from the
         University of Hawaii during a routine survey.</p>
      <p>The fish, tentatively named Abyssalus pacificus, was found at a
         depth of 4,000 meters and exhibits bioluminescent properties
         never before observed in this genus.</p>
    </div>
    <div class="mysidebar related-links">
      <a href="/story1">Related story 1</a>
      <a href="/story2">Related story 2</a>
    </div>
  </body>
</html>
"""

# Using a list of strings
doc = Document(
    html,
    positive_keywords=["news-item", "main-story"],
    negative_keywords=["mysidebar", "related-links"],
)
summary = doc.summary(html_partial=True)
assert "Scientists discover" in summary
assert "Related story" not in summary

# Using a compiled regex
doc2 = Document(
    html,
    positive_keywords=re.compile(r"news|main|article|story"),
    negative_keywords=re.compile(r"sidebar|related|ads|promo"),
)
summary2 = doc2.summary(html_partial=True)
assert "bioluminescent" in summary2
```

--------------------------------

### Document.summary()

Source: https://context7.com/buriy/python-readability/llms.txt

Extracts the main article content from an HTML document. It scores elements by text length, comma density, and link density, promoting the highest-scoring candidate and its siblings. It also strips unwanted elements like scripts and styles. Options are available to return partial HTML or to retain all images.

```APIDOC
## Document.summary(html_partial=False, keep_all_images=False)

### Description
Extracts the primary article content by scoring paragraph, pre, and table elements based on text length, comma density, and link density. It promotes the highest-scoring candidate and its qualifying siblings into a cleaned HTML output, stripping scripts, styles, forms, non-video iframes, and low-signal nodes. If the initial pass yields insufficient content, it retries with less aggressive filtering.

### Parameters
* `html_partial` (bool) - Optional - If True, returns only the article div without wrapping `<html>` and `<body>` tags.
* `keep_all_images` (bool) - Optional - If True, retains all `<img>` tags; by default, only the first/main image is kept.

### Request Example
```python
from readability import Document
import requests

url = "https://www.theguardian.com/technology/2024/01/01/some-article"
response = requests.get(url, headers={"User-Agent": "Mozilla/5.0"})

doc = Document(response.content, url=url)

# Full HTML document output (default)
full_html = doc.summary()
print(full_html[:200])

# Partial HTML — just the article div, no wrapping html/body tags
partial_html = doc.summary(html_partial=True)
print(partial_html[:200])

# Keep all images
html_with_images = doc.summary(keep_all_images=True)
assert "<img" in html_with_images
```

### Response
#### Success Response
Returns a string containing the cleaned HTML of the article content. The format depends on the `html_partial` parameter.
```

--------------------------------

### Document.content()

Source: https://context7.com/buriy/python-readability/llms.txt

Returns the raw HTML of the document's body after it has been parsed and cleaned by lxml. This method preserves the entire cleaned body content without applying readability scoring or article extraction, making it suitable for cases where the full cleaned document is needed.

```APIDOC
## Document.content()

### Description
Returns the full `<body>` HTML of the parsed and lxml-cleaned document. This method does not perform readability scoring or article extraction, providing the entire cleaned document body. It's useful when the complete cleaned document is required.

### Request Example
```python
from readability import Document

html = """
<html>
  <head><title>Page</title></head>
  <body>
    <script>alert('xss')</script>
    <style>.foo { color: red }</style>
    <p>Main content here that is long enough to matter.</p>
    <div class="nav">Navigation links</div>
  </body>
</html>
"""

doc = Document(html)
body = doc.content()
# Scripts and styles are stripped by lxml Cleaner; content is preserved
assert "<script>" not in body
assert "<style>" not in body
assert "Main content" in body
print(body)
```

### Response
#### Success Response
Returns a string containing the raw, cleaned HTML of the document's body.
```

--------------------------------

### Handling Unparseable HTML with Exception

Source: https://context7.com/buriy/python-readability/llms.txt

The `Unparseable` exception is raised by `Document.summary()` for fatal parsing errors. The `safe_extract` function demonstrates how to catch this and other exceptions for robust extraction.

```python
from readability import Document
from readability.readability import Unparseable

def safe_extract(html_content, url=None):
    """Extract article with full error handling."""
    try:
        doc = Document(html_content, url=url)
        return {
            "title": doc.title(),
            "short_title": doc.short_title(),
            "author": doc.author(),
            "summary": doc.summary(html_partial=True),
        }
    except Unparseable as e:
        return {"error": f"Parsing failed: {e}", "summary": None}
    except Exception as e:
        return {"error": f"Unexpected error: {e}", "summary": None}

# Normal usage
result = safe_extract("<html><body><p>Hello world content here.</p></body></html>")
print(result["summary"])

# Handling failure
result = safe_extract(b"\xff\xfe broken garbage \x00\x01")
print(result.get("error"))
```

--------------------------------

### Document.title()

Source: https://context7.com/buriy/python-readability/llms.txt

Returns the normalized text of the page's `<title>` tag, converting entity references to plain ASCII.

```APIDOC
## Document.title()

### Description
Returns the normalized text of the `<title>` tag. Entity references (`&mdash;`, `&nbsp;`, etc.) are converted to plain ASCII equivalents. Returns `"[no-title]"` if no title element is found.

### Method
GET

### Endpoint
N/A (Method of Document object)

### Response
#### Success Response (200)
- **title** (string) - The normalized page title.

### Response Example
```python
import requests
from readability import Document

response = requests.get("https://en.wikipedia.org/wiki/Python_(programming_language)")
doc = Document(response.content)

title = doc.title()
print(title)
# Output: "Python (programming language) - Wikipedia"
```
```

--------------------------------

### JavaScript for Homepage and iPad Specifics

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

This JavaScript code handles specific functionalities for the homepage, such as tagging links. It also includes logic to adjust a link for iPad users and sets the height for a poll frame.

```javascript
// Add whitespace to cnnClear var breaks = $c('cnnClear','div'); /\* Homepage \*/ if (cnnPage.isHomepage) { cnnTagHPLinks(); /\* iPad \*/ if(navigator.userAgent.indexOf('iPad')>-1) { $e('cnnShareRow\_mobile').href='http://ax.itunes.apple.com/WebObjects/MZStore.' +'woa/wa/browserRedirect?url=itms%253A%252F%252Fax.itunes.apple.com%252FWebObj' +'ects%252FMZStore.woa%252Fwa%252FviewSoftware%253Fid%253D329510739%2526mt%253D8'; } /\* Poll frame height issue \*/ if ($e('cnnPollFrame')) { $e('cnnPollFrame').setAttribute('height','169'); } }
```

--------------------------------

### CSS for Navigation Bar (CSS)

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

This CSS snippet styles the navigation bar, specifically adjusting padding for anchor tags within list items. It ensures consistent spacing across different navigation elements.

```css
DIV.cnnTopnav LI A { color:#000;display:block;padding:0 11px 0 11px!important; }
```

--------------------------------

### Conditional Subscription Offer Logic

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

This JavaScript snippet includes logic to potentially modify subscription links based on whether the current page is the homepage. It uses DOM manipulation to update href attributes.

```javascript
if (cnnPage.isHomepage) { var button = $e('cnn_cm_subscribe0'); button.href = 'https://subscription.si.com/storefront/subscribe-to-sports-illustrated/link/1004340.html'; button = $e('cnn_cm_subscribe1'); button.href = 'https://subscription.si.com/storefront/subscribe-to-sports-illustrated/link/1004340.html'; }
```

--------------------------------

### Conditional JavaScript for NBA Path

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

This JavaScript code checks the current URL path to determine if it matches NBA-related sections. It dynamically writes content based on the match, likely for displaying specific legal notices or branding.

```javascript
if( ( ( document.location.pathname ).indexOf( '/basketball/nba' ) >= 0 ) || ( ( document.location.pathname ).indexOf( '/video/nba' ) == 0 ) ) { document.write( 'TM & &#169; 2012 Turner Broadcasting System, Inc. A Time Warner Company. All Rights Reserved. SI.com is part of CNN Digital Network, which is part of the Turner Digital Network.' ); } else { document.write( 'TM & &#169; 2012 Turner Broadcasting System, Inc. A Time Warner Company. All Rights Reserved. SI.com is part of CNN Digital Network, which is part of the Turner Digital Network.' ); }
```

--------------------------------

### Document.author()

Source: https://context7.com/buriy/python-readability/llms.txt

Retrieves the author's name from the document's meta tags. It specifically looks for the `<meta name="author" content="...">` tag. If the tag is not found or is empty, it returns a default string indicating no author was found.

```APIDOC
## Document.author()

### Description
Reads the `<meta name="author" content="...">` tag from the document head to extract the article's author. Returns `"[no-author]"` if the tag is not present or its content is empty.

### Request Example
```python
from readability import Document

html_with_author = """
<html>
  <head>
    <title>Article Title</title>
    <meta name="author" content="Jane Doe">
  </head>
  <body>
    <p>Article content goes here with enough text to be recognized.</p>
  </body>
</html>
"""

doc = Document(html_with_author)
print(doc.author())  # "Jane Doe"

html_no_author = "<html><head><title>T</title></head><body><p>text</p></body></html>"
doc2 = Document(html_no_author)
print(doc2.author())  # "[no-author]"
```

### Response
#### Success Response
Returns a string representing the author's name or `"[no-author]"` if not found.
```

--------------------------------

### Ad Iframe Conditional Logic

Source: https://github.com/buriy/python-readability/blob/master/tests/samples/si-game.sample.html

This JavaScript code checks the current path to prevent ad iframe loading under specific conditions, likely to avoid conflicts or unnecessary ad requests.

```javascript
<!-- $pathname is defined in metadata.js if($pathname.indexOf("/.element/ssi/ads.iframes/") == -1 && $pathname.indexOf("/doubleclick/dartiframe.html") == -1) { var jsmd=\_jsmd.init(); if(document.referrer !== window.location.href){ jsmd.send(); } } //-->
```