Metadata-Version: 2.4
Name: w3c-nu-validator
Version: 0.1.0
Summary: CLI tool to validate deployed URLs via the W3C Nu HTML Checker (JSON output).
Author: Rob Shelford
License: MIT License
        
        Copyright (c) 2026 Robert John Shelford
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/yenmangu/w3c-validator
Project-URL: Repository, https://github.com/yenmangu/w3c-validator
Project-URL: Issues, https://github.com/yenmangu/w3c-validator/issues
Keywords: w3c,html,validator,nu,accessibility,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Text Processing :: Markup :: HTML
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: license-file

# w3c-nu-validator

A lightweight Python CLI tool for validating **deployed URLs** using the
**W3C Nu HTML Checker HTTP API** (JSON output).

This tool is designed to validate the HTML that users and assessors actually see
in production, rather than local templates or development builds.

---

## Why this exists

Manual HTML validation via copy-pasting URLs into the W3C validator is:

- slow
- repetitive
- error-prone
- difficult to repeat consistently across many pages

This tool allows you to:

- validate many deployed URLs in one run
- capture a complete, site-wide validation report
- fix issues systematically instead of page-by-page

---

## Features

- Validate one or more deployed URLs
- Read URLs from a file (one per line)
- De-duplicate URLs automatically
- Write a full validation report to disk
- Return a meaningful exit code (useful for scripts / CI)
- Uses the official W3C Nu Validator HTTP interface

---

## Installation

### From PyPI

```bash
pip install w3c-nu-validator
```

This installs the `w3c-validator` command.

---

### Editable Install

Clone the repository and install it into a virtual environment.

```bash
pip install -e .
```

Or install from another project in editable mode:

```bash
pip install -e /path/to/w3c-nu-validator
```

---

## Usage

### Validate one or more URLs

```bash
w3c-validator https://example.com https://example.com/about/
```

---

### Read URLs from a file

```bash
w3c-validator -r urls.txt
```

File rules:

- one URL per line
- blank lines are ignored
- lines starting with # are ignored

Example `urls.txt`:

> [!NOTE]
> Lines beginning with hash `#` marks are treated as comments and thus ignored.

```text
# Home page
https://example.com/

# Resource list
https://example.com/resources/
```

---

### Write a full report to a file

```bash
w3c-validator -r urls.txt -o report.txt
```

The report includes:

- a delimiter per URL
- error / info counts
- full error messages with HTML extracts

---

## Exit codes

| Code | Meaning                                             |
| ---: | --------------------------------------------------- |
|    0 | No validation errors found                          |
|    1 | One or more URLs contain validation errors          |
|    2 | Invalid input (missing URLs, unreadable file, etc.) |

This allows quick pass/fail checks:

```bash
w3c-validator -r urls.txt
echo $?
```

---

## Requirements

- Python 3.10+
- `requests`

---

## Licence

MIT Licence.

This project is provided as-is, without warranty.
See the `LICENSE` file for details.
