### Install and Run Inscriptis Web Service

Source: https://context7.com/weblyzard/inscriptis/llms.txt

Instructions for installing the web service extras and starting the Inscriptis API using uvicorn or the provided Docker image. Covers installation, server startup, and Docker usage.

```bash
# Install with web-service extras
pip install inscriptis[web-service]

# Start the server
uvicorn inscriptis.service.web:app --host 127.0.0.1 --port 5000
# or: inscriptis-api

# Docker
docker pull ghcr.io/weblyzard/inscriptis:latest
docker run -p 5000:5000 ghcr.io/weblyzard/inscriptis:latest
```

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

### Install Inscriptis using easy_install

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Alternative installation method using easy_install if pip is not available.

```bash
$ easy_install inscriptis
```

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

### Install Inscriptis Web Service

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Command to install the Inscriptis library with the optional web-service feature.

```bash
$ pip install inscriptis[web-service]
```

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

### Install Inscriptis using pip

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Install the Inscriptis library using pip. This is the recommended method for most users.

```bash
$ pip install inscriptis
```

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

### Start Inscriptis Web Service

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Command to start the Inscriptis web service using uvicorn.

```bash
$ uvicorn inscriptis.service.web:app --port 5000 --host 127.0.0.1
```

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

### Print Fact Example

Source: https://github.com/weblyzard/inscriptis/blob/master/RENDERING.md

A simple Python print statement. No specific setup or constraints are mentioned.

```python
print(fact)
```

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

### Example HTML for Annotation

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/README.rst

A sample HTML snippet used to demonstrate how annotation rules are applied.

```html
<h1>Chur</h1>
<b>Chur</b> is the capital and largest town of the Swiss canton of the
Grisons and lies in the Grisonian Rhine Valley.
```

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

### Inscriptis Annotation Profile JSON Example

Source: https://context7.com/weblyzard/inscriptis/llms.txt

An example JSON file defining annotation rules for the Inscriptis CLI. Shows how to map HTML elements and CSS selectors to annotation labels.

```json
{
  "h1": ["heading", "h1"],
  "h2": ["heading", "h2"],
  "b":  ["emphasis"],
  "div#class=toc": ["table-of-contents"],
  "#class=FactBox": ["fact-box"],
  "#cite": ["citation"],
  "a#title": ["entity"]
}
```

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

### JSONL Output Example with Annotations

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Example of Inscriptis output in JSONL format, including extracted text and annotations for headings and emphasis.

```json
{"text": "Chur\n\nChur is the capital and largest town of the Swiss canton
             of the Grisons and lies in the Grisonian Rhine Valley.",
    "label": [[0, 4, "heading"], [0, 4, "h1"], [6, 10, "emphasis"]]}
```

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

### Curl Request to Get Version

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Example cURL command to check the version of the Inscriptis web service.

```bash
$ curl http://localhost:5000/version
```

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

### Command-line Usage with Postprocessor

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Example of using the Inscriptis command-line tool with a postprocessor to annotate content.

```bash
$ inscript https://www.fhgr.ch \
          -r ./examples/annotation/annotation-profile.json \
          -p surface
```

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

### Inscriptis CLI Tool Usage

Source: https://context7.com/weblyzard/inscriptis/llms.txt

Examples demonstrating the usage of the `inscript` command-line tool for various conversion and annotation tasks.

```APIDOC
## Basic Usage

### Convert URL to text
```bash
inscript https://en.wikipedia.org/wiki/Chur
```

### Convert local file to text and save
```bash
inscript page.html -o page.txt
```

## Advanced Options

### Strict indentation
```bash
inscript --indentation strict page.html -o page-strict.txt
```

### Show link targets inline
```bash
inscript -l https://example.com
```

### Show image alt captions and deduplicate
```bash
inscript -i -d page.html
```

### Annotate using JSON rules and output raw JSONL
```bash
inscript -r annotation-profile.json https://example.com
```

### Annotate and postprocess to XML
```bash
inscript -r annotation-profile.json -p xml https://example.com
```

### Annotate and postprocess to surface forms (JSON)
```bash
inscript -r annotation-profile.json -p surface https://example.com
```

### Annotate and postprocess to highlighted HTML
```bash
inscript -r annotation-profile.json -p html https://example.com -o annotated.html
```

### Convert from stdin
```bash
echo "<p>Hello <b>world</b></p>" | inscript -o output.txt
```

### Custom table cell separator
```bash
inscript --table-cell-separator " | " page.html
```

## Example `annotation-profile.json`

```json
{
  "h1": ["heading", "h1"],
  "h2": ["heading", "h2"],
  "b":  ["emphasis"],
  "div#class=toc": ["table-of-contents"],
  "#class=FactBox": ["fact-box"],
  "#cite": ["citation"],
  "a#title": ["entity"]
}
```
```

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

### Python Hello World Program

Source: https://github.com/weblyzard/inscriptis/blob/master/RENDERING.md

A basic 'Hello, world!' program in Python. This example is used to show rendering differences.

```python
print('Hello, world!')
```

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

### Python Loop and Print Example

Source: https://github.com/weblyzard/inscriptis/blob/master/tests/html/advanced-prefix-test.txt

Demonstrates a basic Python for loop with a cumulative sum and subsequent print statements.

```python
y=0
for x in range(3,10):
   print(x)
   y += x
print(y)
```

```python
print("Hallo")
print("Echo")
print("123")
```

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

### HTML Snippet for Annotation Example

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

An example HTML snippet used to demonstrate how Inscriptis applies annotation rules.

```html
<h1>Chur</h1>
<b>Chur</b> is the capital and largest town of the Swiss canton
of the Grisons and lies in the Grisonian Rhine Valley.
```

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

### Inscript CLI Usage Examples

Source: https://context7.com/weblyzard/inscriptis/llms.txt

Demonstrates various command-line interface commands for Inscriptis, including converting URLs, local files, applying strict indentation, showing link targets, handling images, annotating, and processing stdin. Covers common use cases and options.

```bash
# Convert a URL to text
inscript https://en.wikipedia.org/wiki/Chur

# Convert a local file, save output
inscript page.html -o page.txt

# Strict indentation (Firefox-like, no extra div/span padding)
inscript --indentation strict page.html -o page-strict.txt

# Show link targets inline: [link text](URL)
inscript -l https://example.com

# Show image alt captions, deduplicate repeated ones
inscript -i -d page.html

# Annotate using a JSON rules file, output raw JSONL
inscript -r annotation-profile.json https://example.com

# Annotate + postprocess to XML
inscript -r annotation-profile.json -p xml https://example.com

# Annotate + postprocess to surface forms (JSON)
inscript -r annotation-profile.json -p surface https://example.com

# Annotate + postprocess to highlighted HTML
inscript -r annotation-profile.json -p html https://example.com -o annotated.html

# Convert from stdin
echo "<p>Hello <b>world</b></p>" | inscript -o output.txt

# Custom table cell separator
inscript --table-cell-separator " | " page.html
```

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

### JSON Output Example for Annotations

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/api.md

Illustrates the expected JSON structure for text and annotations returned by `get_annotated_text()`.

```json
{"text": "Chur\n\nChur is the capital and largest town of the Swiss canton
          of the Grisons and lies in the Grisonian Rhine Valley.",
 "label": [[0, 4, "heading"], [6, 10, "emphasis"]]}
```

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

### Annotated Text Output (JSONL)

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Example of JSON Lines (JSONL) output from Inscriptis when processing annotated HTML. It includes the extracted text and a list of labels with their start and end indices.

```json
{"text": "Chur\n\nChur is the capital and largest town of the Swiss canton
             of the Grisons and lies in the Grisonian Rhine Valley.",
 "label": [[0, 4, "heading"], [0, 4, "h1"], [6, 10, "emphasis"]]}
```

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

### Curl Request to Get Text

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Example cURL command to send an HTML file to the Inscriptis web service and retrieve plain text.

```bash
$ curl -X POST  -H "Content-Type: text/html; encoding=UTF8"  \
          --data-binary @test.html  http://localhost:5000/get_text
```

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

### XML Output with Annotations

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Example XML output from Inscriptis when using the 'xml' postprocessor, including annotated text.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<content>
<heading>Chur</heading>

<emphasis>Chur</emphasis> is the capital and largest town of the Swiss
canton of the Grisons and lies in the Grisonian Rhine Valley.
</content>
```

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

### Python Code Rendering (lynx)

Source: https://github.com/weblyzard/inscriptis/blob/master/RENDERING.md

Python code examples as rendered by lynx, showing differences in whitespace handling compared to inscriptis.

```python
Python programming examples[edit]                                                                                                                                                                     
                                                                                                                                                                                                      
   Hello world program:                                                                                                                                                                               
                                                                                                                                                                                                      
print('Hello, world!')                                                                                                                                                                                
                                                                                                                                                                                                      
   Program to calculate the factorial of a positive integer:                                                                                                                                          
                                                                                                                                                                                                      
n = int(input('Type a number, and its factorial will be printed: '))                                                                                                                                  
                                                                                                                                                                                                      
if n < 0:
    raise ValueError('You must enter a positive integer')                                                                                                                                             
                                                                                                                                                                                                      
fact = 1                                                                                                                                                                                              
i = 2                                                                                                                                                                                                 
while i <= n:                                                                                                                                                                                         
    fact *= i                                                                                                                                                                                         
    i += 1                                                                                                                                                                                            

```

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

### Annotation Rules and Metadata Extraction Example

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/benchmarking.md

Example JSON structure for annotation rules and extracted metadata, used in Inscriptis 2.0 and later for specific test cases.

```json
{
    "annotation_rules": {
        "h1": ["heading"],
        "b": ["emphasis"]
     },
     "result": [
            ["heading", "The first"],
            ["heading", "The second"],
            ["heading", "Subheading"]
     ]
}

```

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

### HTML to Text Conversion Example

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Demonstrates the difference in conversion quality between Inscriptis and Beautiful Soup for HTML enumerations. Inscriptis provides a more accurate, layout-aware output.

```html
<ul>
  <li>first</li>
  <li>second</li>
<ul>
```

```text
* first
* second
```

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

### Inscriptis Web Service API Endpoints

Source: https://context7.com/weblyzard/inscriptis/llms.txt

Examples of using curl to interact with the Inscriptis web service API for converting HTML to text, checking the version, and performing health checks. Demonstrates POST and GET requests.

```bash
# POST /get_text — convert HTML body to plain text
curl -X POST \
     -H "Content-Type: text/html; charset=UTF-8" \
     --data-binary @page.html \
     http://localhost:5000/get_text

# GET /version — retrieve the running inscriptis version
curl http://localhost:5000/version
# 2.7.1

# GET / — service health check
curl http://localhost:5000/
# Inscriptis text to HTML Web service.
```

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

### Python Code Rendering (inscriptis)

Source: https://github.com/weblyzard/inscriptis/blob/master/RENDERING.md

Python code examples as rendered by inscriptis, preserving indentation and structure.

```python
  Python programming examples [ edit ]


  Hello world program:

    print('Hello, world!')
    

  Program to calculate the factorial of a positive integer:

    n = int(input('Type a number, and its factorial will be printed: '))
    
    if n < 0:
        raise ValueError('You must enter a positive integer')
    
    fact = 1
    i = 2
    while i <= n:
        fact *= i
        i += 1
    
    print(fact)
    

  Libraries [ edit ]


  Python's large standard library, commonly cited as one of its greatest strengths,[99] provides tools suited to many tasks. For Internet-facing applications, many standard formats and protocols such as MIME and HTTP are supported. It includes modules for creating graphical user interfaces, connecting to relational databases, generating pseudorandom numbers, arithmetic with arbitrary-precision decimals,[100] manipulating regular expressions, and unit testing.
```

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

### Python Print Statements Example

Source: https://github.com/weblyzard/inscriptis/blob/master/tests/html/advanced-prefix-test.html

This Python snippet shows multiple print statements to output strings to the console.

```python
print("Hallo")
print("Echo")
print("123")
```

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

### JSON Output with Annotations

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Example JSON output from Inscriptis when using the 'surface' postprocessor, showing text and annotation labels.

```json
{
  "text": "  Chur\n\n  Chur is the capital and largest town of the Swiss
             canton of the Grisons and lies in the Grisonian Rhine Valley.",
  "label": [[0, 6, "heading"], [8, 14, "emphasis"]],
  "tag": "<heading>Chur</heading>\n\n<emphasis>Chur</emphasis> is the
           capital and largest town of the Swiss canton of the Grisons and
           lies in the Grisonian Rhine Valley."
}
```

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

### Programmatic Web Service API Call with Requests

Source: https://context7.com/weblyzard/inscriptis/llms.txt

Python example using the 'requests' library to make a POST request to the Inscriptis web service API for HTML to text conversion. Shows how to send HTML content and headers.

```python
import requests

with open("page.html", "rb") as f:
    html_bytes = f.read()

response = requests.post(
    "http://localhost:5000/get_text",
    data=html_bytes,
    headers={"Content-Type": "text/html; charset=UTF-8"},
)
print(response.text)   # plain text output
```

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

### Extract Text from URL using Inscriptis

Source: https://github.com/weblyzard/inscriptis/blob/master/benchmarking/url_list.txt

This snippet shows how to use Inscriptis to extract text from a given URL. Ensure Inscriptis is installed.

```python
from inscriptis import get_text

url = "https://www.watson.de"
text = get_text(url)
print(text)
```

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

### Python Loop and Summation Example

Source: https://github.com/weblyzard/inscriptis/blob/master/tests/html/advanced-prefix-test.html

This Python snippet demonstrates a basic for loop iterating from 3 to 9, calculating a cumulative sum, and printing the final sum.

```python
y=0
for x in range(3,10):
   print(x)
   y += x
print(y)
```

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

### Lynx Wikipedia Table Rendering

Source: https://github.com/weblyzard/inscriptis/blob/master/RENDERING.md

Shows the HTML rendering of a Wikipedia table by Lynx. This example illustrates the differences in rendering compared to inscriptis, particularly in handling of whitespace and structure.

```text
Climate[[166]edit]

   Chur has an [167]oceanic climate in spite of its inland position.
   Summers are warm and sometimes hot, normally averaging around 25 °C
   (77 °F) during the day, whilst winter means are around freezing, with
   daytime temperatures being about 5 °C (41 °F). Between 1981 and 201
   Chur had an average of 104.6 days of rain per year and on average
   received 849 mm (33.4 in) of [168]precipitation. The wettest month was
   August during which time Chur received an average of 112 mm (4.4 in) of
   precipitation. During this month there was precipitation for an average
   of 11.2 days. The driest month of the year was February with an average
   of 47 mm (1.9 in) of precipitation over 6.6 days.^[169][14]
   Climate data for Chur (1981-2010)
   Month Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec Year
   Average high °C (°F) 4.8
   (40.6) 6.4
   (43.5) 11.2
   (52.2) 15.1
   (59.2) 20.0
   (68.0) 22.7
   (72.9) 24.9
   (76.8) 24.1
   (75.4) 20.0
   (68.0) 16.1
   (61.0) 9.5
   (49.1) 5.3
   (41.5) 15.0
   (59.0)
   Daily mean °C (°F) 0.7
   (33.3) 1.8
   (35.2) 5.9
   (42.6) 9.7
   (49.5) 14.3
   (57.7) 17.1
   (62.8) 19.1
   (66.4) 18.5
...
```

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

### Get Plain Text from URL

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/api.md

Fetches HTML content from a URL and extracts its plain text representation using `get_text()`.

```python
import urllib.request
from inscriptis import get_text

url = 'https://www.fhgr.ch'
html = urllib.request.urlopen(url).read().decode('utf-8')

text = get_text(html)

print(text)
```

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

### Create an Annotation Object

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/api.md

Instantiate an Annotation object to mark a span of text with metadata. The start and end indices define the text span, and metadata contains tags describing the span.

```default
Annotation(0, 10, ('heading', ))
```

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

### Get Text from URL using Inscriptis

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Use the Inscriptis library in Python to fetch HTML from a URL and convert it to plain text. Ensure you have the 'urllib.request' and 'inscriptis' modules imported.

```python
import urllib.request
from inscriptis import get_text

url = "https://www.fhgr.ch"
html = urllib.request.urlopen(url).read().decode('utf-8')

text = get_text(html)
print(text)
```

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

### Extract Text from Multiple URLs

Source: https://github.com/weblyzard/inscriptis/blob/master/benchmarking/url_list.txt

This example iterates through a list of URLs and extracts text from each using Inscriptis. It's useful for batch processing web pages.

```python
from inscriptis import get_text

urls = [
    "https://www.watson.de",
    "https://www.watson.ch/Digital%20&%20Games/Android/134350872-Der-Monster-Akku-in-diesem-Smartphone-h%C3%A4lt-bis-15-Tage",
    "https://www.heise.de",
    "https://www.heise.de/newsticker/meldung/Fairphone-2-im-Test-Das-erste-modulare-Smartphone-3043417.html",
    "http://www.nzz.de",
    "https://www.nzz.ch/mobilitaet/auto-mobil/bekenntnis-zum-stromauto-ld.3630",
    "https://de.wikipedia.org/wiki/Wikipedia:Hauptseite",
    "https://de.wikipedia.org/wiki/Python_(Programmiersprache)",
    "https://de.wikipedia.org/wiki/Chur",
    "http://jr-central.co.jp",
    "http://www.aljazeera.net/portal",
    "http://www.aljazeera.net/news/humanrights/2015/12/14/%D8%A3%D9%88%D8%A8%D8%A7%D9%85%D8%A7-%D9%8A%D8%AC%D8%AF%D8%AF-%D8%A7%D9%84%D8%AA%D8%B2%D8%A7%D9%85%D9%87-%D8%A8%D8%A5%D8%BA%D9%84%D8%A7%D9%82-%D8%BA%D9%88%D8%A7%D9%86%D8%AA%D8%A7%D9%86%D8%A7%D9%85%D9%88",
    "https://www.fhgr.ch",
    "https://www.diepresse.com",
    "https://derstandard.at",
    "https://krone.at",
    "https://stackoverflow.com/questions/328356/extracting-text-from-html-file-using-python/46921881",
    "https://www.chur.ch/churinzahlen"
]

for url in urls:
    try:
        text = get_text(url)
        print(f"--- Content from {url} ---")
        print(text)
        print("\n")
    except Exception as e:
        print(f"Could not fetch {url}: {e}")
```

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

### Get Annotated Text from URL

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/api.md

Fetches HTML content from a URL and extracts text along with annotations based on specified rules using `get_annotated_text()`.

```python
import urllib.request
from inscriptis import get_annotated_text

url = "https://www.fhgr.ch"
html = urllib.request.urlopen(url).read().decode('utf-8')

# annotation rules specify the HTML elements and attributes to annotate.
rules = {'h1': ['heading'],
         'h2': ['heading'],
         '#class=FactBox': ['fact-box'],
         'i': ['emphasis']}

output = get_annotated_text(html, ParserConfig(annotation_rules=rules))
print("Text:", output['text'])
print("Annotations:", output['label'])
```

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

### Generate Annotated Text from HTML with Inscriptis

Source: https://context7.com/weblyzard/inscriptis/llms.txt

Use `get_annotated_text` to extract plain text and semantic annotations. Define rules to map HTML elements and attributes to labels. The output includes text and a list of `[start, end, label]` triples.

```python
from inscriptis import get_annotated_text
from inscriptis.model.config import ParserConfig

html = """
<h1>Chur</h1>
<p><b>Chur</b> is the capital and largest town of the Swiss canton of the
<a href="/wiki/Grisons" title="Grisons">Grisons</a>.</p>
"""

rules = {
    "h1": ["heading", "h1"],           # tag rule
    "b":  ["emphasis"],                 # tag rule
    "a#title": ["entity"],             # attribute rule: <a title=">
    "div#class=toc": ["toc"],          # tag+attribute+value rule
    "#class=reference": ["citation"],  # attribute+value rule (any tag)
}

config = ParserConfig(annotation_rules=rules)
output = get_annotated_text(html, config)

print(output["text"])

print(output["label"])

# Each label triple: [start_index, end_index, label_string]
for start, end, label in output["label"]:
    print(f"  {label!r:15s}: {output['text'][start:end]!r}")
```

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

### Override Custom HTML Tag Handlers

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Customize how Inscriptis handles specific HTML start and end tags by providing custom handler functions. This example shows overwriting handlers for the 'a' tag.

```python
from inscriptis import ParserConfig
from inscriptis.html_engine import Inscriptis
from inscriptis.model.tag import CustomHtmlTagHandlerMapping

my_mapping = CustomHtmlTagHandlerMapping(
    start_tag_mapping={'a': my_handle_start_a},
    end_tag_mapping={'a': my_handle_end_a}
)
inscriptis = Inscriptis(html_tree, 
                        ParserConfig(custom_html_tag_handler_mapping=my_mapping))
text = inscriptis.get_text()
```

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

### URL List for Benchmarking

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/benchmarking.md

Format for specifying URLs to be parsed by the benchmarking script. Each URL should be on a new line and include the protocol.

```text
http://www.informationscience.ch
https://en.wikipedia.org/wiki/Information_science

```

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

### Annotation Shifting

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/api.md

Adjusts the start and end indices of annotations based on line formatting and width.

```APIDOC
## inscriptis.annotation.horizontal_shift(annotations: list[Annotation], content_width: int, line_width: int, align: HorizontalAlignment, shift: int = 0) -> list[Annotation]

### Description
Shift annotations based on the given line’s formatting.
Adjusts the start and end indices of annotations based on the line’s
formatting and width.

### Parameters
* **annotations** (list[Annotation]) - A list of Annotations.
* **content_width** (int) - The width of the actual content.
* **line_width** (int) - The width of the line in which the content is placed.
* **align** (HorizontalAlignment) - The horizontal alignment (left, right, center) to assume for the adjustment.
* **shift** (int, optional) - An optional additional shift. Defaults to 0.

### Returns
A list of [Annotation](#inscriptis.annotation.Annotation)s with the adjusted start and end positions.
```

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

### Benchmarking Script Configuration

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/benchmarking.md

Configuration options for the Inscriptis benchmarking script, allowing selection of HTML-to-text algorithms to be executed.

```python
run_lynx = True
run_justext = True
run_html2text = True
run_beautifulsoup = True
run_inscriptis = True

```

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

### Inscript Command Line Usage

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Overview of the command-line parameters for the inscript client, used for converting HTML to text.

```bash
usage: inscript [-h] [-o OUTPUT] [-e ENCODING] [-i] [-d] [-l] [-a] [-r ANNOTATION_RULES] [-p POSTPROCESSOR] [--indentation INDENTATION]
                   [--table-cell-separator TABLE_CELL_SEPARATOR] [-v]
                   [input]

Convert the given HTML document to text.

positional arguments:
  input                 Html input either from a file or a URL (default:stdin).

optional arguments:
  -h, --help            show this help message and exit
  -o OUTPUT, --output OUTPUT
                        Output file (default:stdout).
  -e ENCODING, --encoding ENCODING
                        Input encoding to use (default:utf-8 for files; detected server encoding for Web URLs).
  -i, --display-image-captions
                        Display image captions (default:false).
  -d, --deduplicate-image-captions
                        Deduplicate image captions (default:false).
  -l, --display-link-targets
                        Display link targets (default:false).
  -a, --display-anchor-urls
                        Display anchor URLs (default:false).
  -r ANNOTATION_RULES, --annotation-rules ANNOTATION_RULES
                        Path to an optional JSON file containing rules for annotating the retrieved text.
  -p POSTPROCESSOR, --postprocessor POSTPROCESSOR
                        Optional component for postprocessing the result (html, surface, xml).
  --indentation INDENTATION
                        How to handle indentation (extended or strict; default: extended).
  --table-cell-separator TABLE_CELL_SEPARATOR
                        Separator to use between table cells (default: three spaces).
  -v, --version         display version information
```

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

### Annotation Postprocessors with Inscriptis

Source: https://context7.com/weblyzard/inscriptis/llms.txt

Shows how to use different annotation postprocessors (SurfaceExtractor, XmlExtractor, HtmlExtractor) to transform raw annotated text into various formats. Requires importing specific extractors and providing annotation rules.

```python
from inscriptis import get_annotated_text
from inscriptis.model.config import ParserConfig
from inscriptis.annotation.output.surface import SurfaceExtractor
from inscriptis.annotation.output.xml import XmlExtractor
from inscriptis.annotation.output.html import HtmlExtractor

html = "<h1>Chur</h1><p><b>Chur</b> is the capital of Grisons.</p>"
rules = {"h1": ["heading"], "b": ["emphasis"]}
config = ParserConfig(annotation_rules=rules)
annotated = get_annotated_text(html, config)

# --- SurfaceExtractor: adds 'surface' key with (label, text) pairs ---
surface_result = SurfaceExtractor()(annotated.copy())
print(surface_result["surface"])

# --- XmlExtractor: returns XML string with annotation tags ---
xml_result = XmlExtractor()(annotated.copy())
print(xml_result)

# --- HtmlExtractor: returns color-highlighted HTML ---
html_result = HtmlExtractor()(annotated.copy())
# Returns full HTML page with <span> highlights and injected CSS
print(html_result[:200])
```

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

### Annotate HTML from Web Page using CLI

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/README.rst

Use the inscript CLI with an annotation rules file to convert and annotate HTML content from a web page.

```bash
$ inscript https://www.fhgr.ch -r annotation-profile.json
```

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

### Using Inscriptis Annotation Named Tuple

Source: https://context7.com/weblyzard/inscriptis/llms.txt

Demonstrates the creation and access of fields within the `Annotation` named tuple. This is useful for understanding the structure of individual annotations.

```python
from inscriptis.annotation import Annotation

# Annotation is a NamedTuple: (start, end, metadata)
ann = Annotation(start=0, end=4, metadata="heading")
print(ann.start, ann.end, ann.metadata)   # 0 4 heading
```

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

### Ignore Elements During Parsing

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Prevent specific HTML elements from appearing in the parsed text by setting their display property to `Display.none`. This example removes `form` elements.

```python
from inscriptis import get_text
from inscriptis.css_profiles import CSS_PROFILES, HtmlElement
from inscriptis.html_properties import Display
from inscriptis.model.config import ParserConfig

# create a custom CSS based on the default style sheet and change the
# rendering of `div` and `span` elements
css = CSS_PROFILES['strict'].copy()
css['form'] = HtmlElement(display=Display.none)

# create a parser configuration using a custom css
html = """First line. 
                  <form>
                    User data
                    <label for="name">Name:</label><br>
                    <input type="text" id="name" name="name"><br>
                    <label for="pass">Password:</label><br>
                    <input type="hidden" id="pass" name="pass">
                  </form>"""
config = ParserConfig(css=css)
text = get_text(html, config)
print(text)
```

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

### Override Default CSS Definitions for Rendering

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Customize the rendering of HTML tags by overriding default CSS definitions. This example modifies `div` and `span` elements.

```python
from lxml.html import fromstring

from inscriptis import Inscriptis
from inscriptis.css_profiles import CSS_PROFILES
from inscriptis.html_properties import Display
from inscriptis.model.config import ParserConfig
from inscriptis.model.html_element import HtmlElement

# Create a custom CSS based on the default style sheet and change the
# rendering of `div` and `span` elements.
css = CSS_PROFILES['strict'].copy()
css['div'] = HtmlElement(display=Display.block, padding=2)
css['span'] = HtmlElement(prefix=' ', suffix=' ')

html_tree = fromstring(html)
# create a parser using a custom css
config = ParserConfig(css=css)
parser = Inscriptis(html_tree, config)
text = parser.get_text()
```

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

### Command-line Usage with HTML Postprocessor

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Command to convert a Wikipedia page to HTML with annotations, using specified annotation rules.

```bash
inscript --annotation-rules ./wikipedia.json \
                  --postprocessor html \
                  https://en.wikipedia.org/wiki/Chur
```

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

### Programmatic Use of Inscriptis for Annotated Text

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Python code demonstrating how to use Inscriptis to extract annotated text from a URL, including custom annotation rules.

```python
import urllib.request
from inscriptis import get_annotated_text
from inscriptis.model.config import ParserConfig

url = "https://www.fhgr.ch"
html = urllib.request.urlopen(url).read().decode('utf-8')

rules = {'h1': ['heading', 'h1'],
           'h2': ['heading', 'h2'],
           'b': ['emphasis'],
           'table': ['table']
          }

output = get_annotated_text(html, ParserConfig(annotation_rules=rules))
print("Text:", output['text'])
print("Annotations:", output['label'])
```

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

### Shift Annotations Horizontally

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/api.md

Adjust the start and end indices of annotations based on line formatting, content width, and alignment. This is useful for adapting annotations after text reformatting.

```python
inscriptis.annotation.horizontal_shift(annotations: list[[Annotation](#inscriptis.annotation.Annotation)], content_width: int, line_width: int, align: [HorizontalAlignment](#inscriptis.html_properties.HorizontalAlignment), shift: int = 0) → list[[Annotation](#inscriptis.annotation.Annotation)]
```

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

### inscriptis.model.canvas.block.Block.merge_normal_text

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/api.md

Merges the given text with the current block, handling normal text. If the previous text ended with a whitespace and the new text starts with one, they will collapse into a single whitespace.

```APIDOC
## merge_normal_text(text: str) -> None

### Description
Merge the given text with the current block.

### Parameters
#### Path Parameters
- **text** (str) - Required - the text to merge

### NOTE
If the previous text ended with a whitespace and text starts with one, both
: will automatically collapse into a single whitespace.
```

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

### Prefix Class Methods

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/api.md

Methods for managing prefixes used in text formatting, such as registering, popping, and removing prefixes.

```APIDOC
## Prefix Class Methods

### `first` property

Return the prefix used at the beginning of a tag.

### `pop_next_bullet()` method

Pop the next bullet to use, if any bullet is available.

### `register_prefix(padding_inline: int, bullet: str)` method

Register the given prefix.

* **Parameters:**
  * **padding_inline** – the number of characters used for padding_inline
  * **bullet** – an optional bullet.

### `remove_last_prefix()` method

Remove the last prefix from the list.

### `rest` property

Return the prefix used for new lines within a block.

### `unconsumed_bullet` property

Yield any yet unconsumed bullet.
```

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

### Custom HTML Tag Handling in Inscriptis

Source: https://context7.com/weblyzard/inscriptis/llms.txt

Demonstrates how to define custom handlers for HTML tags like <em> and <b> to control their output format. Requires defining handler functions and a CustomHtmlTagHandlerMapping.

```python
from inscriptis import Inscriptis
from inscriptis.model.config import ParserConfig
from inscriptis.html_tag_handler import CustomHtmlTagHandlerMapping
from inscriptis.model.html_document import HtmlDocumentState

def handle_start_b(state: HtmlDocumentState, attrs: dict) -> None:
    state.tags[-1].write("**")

def handle_end_b(state: HtmlDocumentState) -> None:
    state.tags[-1].write("**")

def handle_start_em(state: HtmlDocumentState, attrs: dict) -> None:
    state.tags[-1].write("_")

def handle_end_em(state: HtmlDocumentState) -> None:
    state.tags[-1].write("_")

mapping = CustomHtmlTagHandlerMapping(
    start_tag_mapping={"b": handle_start_b, "em": handle_start_em},
    end_tag_mapping={"b": handle_end_b,   "em": handle_end_em},
)

config = ParserConfig(custom_html_tag_handler_mapping=mapping)
html = "Welcome to <b>Chur</b>, the <em>oldest</em> city."
parser = Inscriptis(html, config=config)
print(parser.get_text())
```

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

### Configure HtmlElement Properties for Tag Rendering in Inscriptis

Source: https://context7.com/weblyzard/inscriptis/llms.txt

Illustrates how to define custom rendering properties for HTML tags using `HtmlElement`. This allows control over display mode, margins, padding, prefixes, suffixes, whitespace handling, and alignment for specific tags.

```python
from inscriptis.html_properties import Display, WhiteSpace, HorizontalAlignment, VerticalAlignment
from inscriptis.model.html_element import HtmlElement
from inscriptis.model.config import ParserConfig
from inscriptis.css_profiles import CSS_PROFILES
from inscriptis import get_text

css = CSS_PROFILES["strict"].copy()

# Render <h1> with surrounding "===" markers
css["h1"] = HtmlElement(
    display=Display.block,
    prefix="=== ",
    suffix=" ===",
    margin_before=1,
    margin_after=1,
)

# Render <aside> content as indented block
css["aside"] = HtmlElement(
    display=Display.block,
    padding_inline=6,
    margin_before=1,
    margin_after=1,
)

# Hide <nav> elements entirely
css["nav"] = HtmlElement(display=Display.none)

# Preserve whitespace inside <code> like a <pre> block
css["code"] = HtmlElement(
    display=Display.inline,
    whitespace=WhiteSpace.pre,
)

html = "<h1>Title</h1><nav>skip me</nav><aside>Side note</aside>"
print(get_text(html, ParserConfig(css=css)))
```

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

### Convert HTML URL to Text via Command Line

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Convert an HTML page from a given URL to plain text and output it directly to the console using the inscript command-line client.

```bash
$ inscript https://www.fhgr.ch
```

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

### Low-level HTML Parsing with Inscriptis Engine

Source: https://context7.com/weblyzard/inscriptis/llms.txt

Demonstrates using the `Inscriptis` class for low-level HTML parsing when you manage the lxml HTML tree. It accepts a pre-parsed tree and `ParserConfig` to extract text or annotations.

```python
from lxml.html import fromstring
from inscriptis.html_engine import Inscriptis
from inscriptis.model.config import ParserConfig
from inscriptis.css_profiles import CSS_PROFILES

html = "<html><body><h2>Section</h2><p>First <b>paragraph</b>.</p></body></html>"

html_tree = fromstring(html)
config = ParserConfig(css=CSS_PROFILES["strict"])

parser = Inscriptis(html_tree, config)

# Get plain text
text = parser.get_text()
print(text)
```

```python
# Get raw Annotation objects (requires annotation_rules in config)
from inscriptis.model.config import ParserConfig
config_ann = ParserConfig(annotation_rules={"h2": ["section"], "b": ["bold"]})
parser2 = Inscriptis(fromstring(html), config_ann)
_ = parser2.get_text()
for ann in parser2.get_annotations():
    print(ann)   # Annotation(start=0, end=7, metadata='section'), etc.
```

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

### Configure Parser with Strict CSS and Disabled Links

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/api.md

Use this configuration to enable the strict CSS profile and prevent links from being displayed in the output. Ensure necessary imports are included.

```Python
from inscriptis import get_text
from inscriptis.css_profiles import CSS_PROFILES
from inscriptis.model.config import ParserConfig

css_profile = CSS_PROFILES['strict'].copy()
config = ParserConfig(css=css_profile, display_links=False)
text = get_text('fi<span>r</span>st <a href="/first">link</a>', config)
print(text)
```

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

### Convert HTML to Plain Text with Inscriptis

Source: https://context7.com/weblyzard/inscriptis/llms.txt

Use `get_text` to convert HTML to plain text. It handles complex layouts like tables and lists. You can customize the output using `ParserConfig` for CSS profiles, link display, and more.

```python
import urllib.request
from inscriptis import get_text
from inscriptis.css_profiles import CSS_PROFILES
from inscriptis.model.config import ParserConfig

# Basic usage — convert a live web page
html = urllib.request.urlopen("https://en.wikipedia.org/wiki/Chur").read().decode("utf-8")
text = get_text(html)
print(text[:500])

# With custom config: strict (Firefox-like) CSS, show links, show image alt text
config = ParserConfig(
    css=CSS_PROFILES["strict"],
    display_links=True,
    display_images=True,
    deduplicate_captions=True,
    table_cell_separator="   ",
)
text = get_text(html, config)

# From a local string — handles nested tables, lists, pre blocks
html_snippet = """
<h1>Cities</h1>
<ul>
  <li>Chur</li>
  <li>Zurich</li>
</ul>
<table>
  <tr><th>City</th><th>Population</th></tr>
  <tr><td>Chur</td><td>38,000</td></tr>
</table>
"""
print(get_text(html_snippet))
```

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

### Docker Run Command

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Command to run the Inscriptis Docker container.

```bash
$ docker run -n inscriptis ghcr.io/weblyzard/inscriptis:latest
```

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

### Convert HTML File to Text and Save to File

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Convert an HTML file to plain text and save the output to a specified file using the inscript command-line client.

```bash
$ inscript fhgr.html -o fhgr.txt
```

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

### Lynx Nested Table Rendering

Source: https://github.com/weblyzard/inscriptis/blob/master/RENDERING.md

This output illustrates how the Lynx text-based browser renders the same nested table structure. It provides a comparison point for Inscriptis's text-based rendering.

```text
                                     Single

First

   red      green
       blue
   red      green

Second

       blue
   red      green
       blue

                                     Nested

   red      green
       blue
   red      green
       blue
   red      green
       blue
       blue
   red      green
       blue
       blue
   red      green
       blue
   red      green
       blue
   red      green
       blue
   red      green
       blue
   red      green
       blue
   red      green
       blue
       blue
   red      green
       blue
```

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

### Optimize Memory Consumption on Unix Systems

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Manually force lxml to release allocated memory on Unix systems to mitigate increased memory consumption in memory-intensive web services.

```python
import ctypes
def trim_memory() -> int:
```

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

### Transform HTML Tree to Text

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/api.md

Demonstrates how to use the `Inscriptis` class to parse an lxml HTML tree and extract its text representation.

```python
from lxml.html import fromstring
from inscriptis.html_engine import Inscriptis

html_content = "<html><body><h1>Test</h1></body></html>"

# create an HTML tree from the HTML content.
html_tree = fromstring(html_content)

# transform the HTML tree to text.
parser = Inscriptis(html_tree)
text = parser.get_text()
```

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

### Table Class Methods

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/api.md

Methods for managing HTML tables, including adding rows and cells.

```APIDOC
## Table Class Methods

### `add_cell(table_cell: TableCell)` method

Add a new TableCell to the table’s last row.

* **NOTE:** If no row exists yet, a new row is created.

### `add_row()` method

Add an empty TableRow to the table.
```

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

### Inspect and Customize CSS Profiles in Inscriptis

Source: https://context7.com/weblyzard/inscriptis/llms.txt

Shows how to access, inspect, and derive custom CSS profiles from Inscriptis's built-in profiles ('strict' and 'relaxed'). Useful for fine-tuning text extraction by modifying tag rendering properties.

```python
from inscriptis.css_profiles import CSS_PROFILES, STRICT_CSS_PROFILE, RELAXED_CSS_PROFILE
from inscriptis.model.html_element import HtmlElement
from inscriptis.html_properties import Display, WhiteSpace

# Inspect available profiles
print(list(CSS_PROFILES.keys()))   # ['strict', 'relaxed']

# Use the strict profile directly
strict = CSS_PROFILES["strict"]
print(strict["p"])   # <p display=Display.block, margin_before=1, margin_after=1, ...>

# Derive a custom profile from the relaxed baseline
custom = CSS_PROFILES["relaxed"].copy()
custom["blockquote"] = HtmlElement(
    display=Display.block,
    prefix="> ",
    margin_before=1,
    margin_after=1,
)
custom["code"] = HtmlElement(display=Display.inline, prefix="`", suffix="`")

from inscriptis import get_text
from inscriptis.model.config import ParserConfig

html = "<blockquote>Famous quote</blockquote> and <code>print()</code>"
print(get_text(html, ParserConfig(css=custom)))
```

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

### Surface postprocessor output format

Source: https://github.com/weblyzard/inscriptis/blob/master/docs/README.rst

The 'surface' postprocessor outputs a list of mappings between annotation surface forms and their labels.

```text
[
   ['heading', 'Chur'], 
   ['emphasis': 'Chur']
]
```

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

### Convert HTML from Stdin to Text File

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Convert HTML content provided via standard input (stdin) to plain text and save the output to a file. This is useful for piping HTML data to the inscript client.

```bash
$ echo "<body><p>Make it so!</p></body>" | inscript -o output.txt
```

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

### Parse HTML with Custom Link and Anchor Display

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Configure Inscriptis to display inline links and anchor URLs. Uses the strict CSS rendering profile.

```python
from lxml.html import fromstring

from inscriptis import Inscriptis
from inscriptis.css_profiles import CSS_PROFILES
from inscriptis.model.config import ParserConfig

# uses the strict CSS rendering profile and fine-tune link handling.
css = CSS_PROFILES['strict']
config = ParserConfig(css=css, display_links=True, 
                      display_anchors=True)

html_tree = fromstring(html)
parser = Inscriptis(html_tree, config)
text = parser.get_text()
```

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

### Inscriptis with Strict CSS Profile for Whitespace Handling

Source: https://github.com/weblyzard/inscriptis/blob/master/README.rst

Python code demonstrating how to configure Inscriptis to use the 'strict' CSS profile for Firefox-like whitespace handling.

```python
from lxml.html import fromstring
           
from inscriptis import Inscriptis
from inscriptis.css_profiles import CSS_PROFILES
from inscriptis.model.config import ParserConfig
           
# create a ParserConfig that uses the strict CSS rendering profile
css = CSS_PROFILES['strict']
config = ParserConfig(css=css)
           
html_tree = fromstring(html)
parser = Inscriptis(html_tree, config)
text = parser.get_text()
```