### Getting Started and Navigation

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/FILES-MANIFEST.txt

Entry points and navigation guides for new users and for exploring the documentation.

```APIDOC
## Getting Started and Navigation

Guides for quickly understanding and navigating the project documentation.

### Entry Points:
- `README.md`: The primary starting point for quick information.
- `REFERENCE-INDEX.md`: The master index for all documentation, including a function table.
```

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

### Install and Use url-normalize with Uv Tool

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/cli-reference.md

Install url-normalize globally as a tool using uv and then execute it directly.

```bash
# Install as a tool (globally available)
uv tool install url-normalize

# Use via uv
uvx url-normalize "example.com"
```

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

### Install url-normalize as a CLI Tool

Source: https://github.com/niksite/url-normalize/blob/master/README.md

Install the url-normalize standalone CLI tool using uv.

```sh
uv tool install url-normalize
```

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

### Install url-normalize Python Library

Source: https://github.com/niksite/url-normalize/blob/master/README.md

Install the url-normalize library using pip.

```sh
pip install url-normalize
```

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

### Verify url-normalize Installation

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/cli-reference.md

Verifies the installation of the url-normalize package by running a basic CLI command. This helps confirm that the package is correctly installed and accessible.

```bash
python -m url_normalize.cli "example.com"
```

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

### Configuration Documentation

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/FILES-MANIFEST.txt

Guides users on how to configure the url-normalize project, including types and CLI options.

```APIDOC
## Configuration

This section covers the configuration options available for the url-normalize project.

### Configuration Files:
- `configuration.md`: Details on parameter options and settings.
- `types.md`: Defines the type definitions used within the project, including the `URL` type and constants.
- `cli-reference.md`: Comprehensive reference for command-line interface arguments and usage examples.
```

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

### Display Version

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/cli-reference.md

Display the installed version of the url-normalize CLI and exit.

```bash
url-normalize --version
# Output: url-normalize 3.0.0
```

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

### Example Error Output

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/cli-reference.md

Demonstrates an example of error output and exit code when normalization fails due to invalid input.

```bash
$ url-normalize -c invalid-charset "example.com"
# (stderr) Error normalizing URL: ...
# (exit code) 1
```

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

### Check CLI Version

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/cli-reference.md

Displays the installed version of the url-normalize CLI. This command is useful for verifying the installation and checking compatibility.

```bash
url-normalize --version
```

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

### CLI Normalization with Domain Injection

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/REFERENCE-INDEX.md

Demonstrates how to provide a default domain using the '-d' or '--default-domain' option for URLs that start with a path.

```bash
# With domain injection
url-normalize -d example.com "/path"
```

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

### Domain Normalization Examples

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-param-allowlist.md

Demonstrates how `get_allowed_params` normalizes domain names by removing 'www.' prefixes, ignoring ports, and performing case-insensitive lookups.

```python
# www prefix is removed
result = get_allowed_params("www.google.com")
print(result)
# Output: {"q", "ie"}  (same as "google.com")

# Port is ignored
result = get_allowed_params("google.com:8080")
print(result)
# Output: {"q", "ie"}

# Case-insensitive
result = get_allowed_params("GOOGLE.COM")
print(result)
# Output: {"q", "ie"}
```

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

### Public API Import Example

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/module-structure.md

Shows how to import the main public functions, url_humanize and url_normalize, from the url_normalize package for use in other Python modules.

```python
from url_normalize import url_humanize, url_normalize
```

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

### Reconstruct URL with Authentication and Custom Port

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-tools.md

This example demonstrates reconstructing a URL that includes user authentication credentials and a non-standard port. The `userinfo` should be formatted as 'user:pass@' and the `port` as a string.

```python
url_obj = URL(
    scheme='https',
    userinfo='user:pass@',
    host='example.com',
    port='8080',
    path='/admin',
    query='',
    fragment=''
)
result = reconstruct_url(url_obj)
print(result)
# Output: https://user:pass@example.com:8080/admin
```

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

### Get Allowed Parameters with Custom List

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-param-allowlist.md

Applies a custom allowlist provided as a list to all domains. This overrides any default or domain-specific configurations.

```python
result = get_allowed_params("example.com", allowlist=["id", "page"])
print(result)
# Output: {"id", "page"}
```

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

### Handle Absolute File Path URL

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-helper-functions.md

Returns absolute file paths starting with '/' unchanged. These are treated as local file system paths, not network URLs.

```python
provide_url_scheme("/path/to/file")
# Output: "/path/to/file" (unchanged, treated as file path)
```

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

### Filter URL Parameters

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/cli-reference.md

Demonstrates how to use the `-f` flag to filter URL parameters based on a domain's allowlist. This example shows which parameters are kept for google.com.

```bash
# Check what parameters are kept for a domain
url-normalize -f "google.com?q=test&utm=bad&ie=utf8"
# Output: https://google.com?q=test&ie=utf8
# (google.com default allowlist has "q" and "ie")
```

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

### Deconstruct URL Usage Example

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-tools.md

Demonstrates how to parse a URL string into its constituent components using the deconstruct_url function and access them via the URL NamedTuple.

```python
from url_normalize.tools import deconstruct_url, URL

url_obj = deconstruct_url("https://user:pass@example.com:8080/path?key=value#section")
print(url_obj.scheme)      # "https"
print(url_obj.userinfo)    # "user:pass@"
print(url_obj.host)        # "example.com"
print(url_obj.port)        # "8080"
print(url_obj.path)        # "/path"
print(url_obj.query)       # "key=value"
print(url_obj.fragment)    # "section"
```

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

### Import Parameter Filtering Functions

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/types.md

Imports functions for parameter filtering, including getting allowed parameters and processing query parameters.

```python
# Parameter filtering
from url_normalize.param_allowlist import get_allowed_params, DEFAULT_ALLOWLIST, process_query_param
```

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

### Get Library Version

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/types.md

Access the library's version at runtime using the __version__ attribute. This snippet shows how to import and print the version.

```python
from url_normalize import __version__

print(__version__)
# Output: "3.0.0"
```

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

### Handle Scheme-Relative URL

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-helper-functions.md

Returns scheme-relative URLs unchanged. These URLs start with '//' and rely on the current page's scheme.

```python
provide_url_scheme("//cdn.example.com/script.js")
# Output: "//cdn.example.com/script.js" (unchanged)
```

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

### provide_url_domain()

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-helper-functions.md

Adds a default domain to absolute paths to convert them into complete URLs. It processes URLs starting with '/' (but not '//') by prepending '//' and the default domain. Other URL types or inputs are returned unchanged.

```APIDOC
## provide_url_domain()

### Description
Adds a default domain to absolute paths to convert them into complete URLs. It processes URLs starting with '/' (but not '//') by prepending '//' and the default domain. Other URL types or inputs are returned unchanged.

### Signature
```python
def provide_url_domain(url: str, default_domain: str | None = None) -> str
```

### Parameters
#### Path Parameters
- **url** (str) - Required - The URL or path to process.
- **default_domain** (str | None) - Optional - The domain to prepend to absolute paths. If None or empty, no modification is made.

### Return Type
`str` — The URL with a domain added if applicable, otherwise the original URL.

### Behavior
1. **No-op conditions**: Returns the URL unchanged if:
   - `default_domain` is None or empty
   - `url` is None, empty, or is "-" (stdin/stdout indicator)
2. **Absolute path detection**: Only processes URLs starting with "/" (but not "//").
3. **Domain injection**: Prepends "//" + domain to the URL (creating a scheme-relative URL).
4. **Non-matching URLs**: All other URL types (absolute URLs, relative paths) are returned unchanged.

### Examples
#### Absolute path with domain
```python
from url_normalize.provide_url_domain import provide_url_domain

provide_url_domain("/path/to/resource", default_domain="example.com")
# Output: "//example.com/path/to/resource"

provide_url_domain("/images/logo.png", default_domain="cdn.example.com")
# Output: "//cdn.example.com/images/logo.png"
```

#### Scheme-relative URLs (unchanged)
```python
provide_url_domain("//example.com/path", default_domain="other.com")
# Output: "//example.com/path" (already has domain)
```

#### Relative paths (unchanged)
```python
provide_url_domain("path/to/resource", default_domain="example.com")
# Output: "path/to/resource" (relative path, unchanged)
```

#### Empty or None inputs
```python
provide_url_domain("/path", default_domain=None)
# Output: "/path"

provide_url_domain("", default_domain="example.com")
# Output: ""

provide_url_domain("-", default_domain="example.com")
# Output: "-"
```

### Use Cases
This function is typically used to resolve relative URLs found in web content to absolute URLs for consistent processing:

```python
from url_normalize import url_normalize

# Normalize a relative URL found on example.com
result = url_normalize("/products/item", default_domain="example.com")
# Output: https://example.com/products/item

# Normalize multiple relative URLs from the same page
base_domain = "example.com"
urls = ["/products", "/about", "/contact"]
normalized = [url_normalize(url, default_domain=base_domain) for url in urls]
```
```

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

### Get Allowed Parameters with Custom Dictionary

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-param-allowlist.md

Uses a custom dictionary to define domain-specific allowlists. If the queried domain is not found in the dictionary, an empty set is returned.

```python
allowlist = {"google.com": ["q"], "bing.com": ["q"]}
result = get_allowed_params("google.com", allowlist=allowlist)
print(result)
# Output: {"q"}

result = get_allowed_params("example.com", allowlist=allowlist)
print(result)
# Output: set()  (domain not in allowlist)
```

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

### Create and Access URL Instance Fields

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/types.md

Demonstrates how to create a URL instance with specific components and access individual fields using attribute notation. Useful for initializing URL objects with known values.

```python
from url_normalize.tools import URL, reconstruct_url

url_obj = URL(
    scheme='https',
    userinfo='user:pass@',
    host='example.com',
    port='8080',
    path='/api/v1/resource',
    query='key=value&sort=asc',
    fragment='section'
)

print(url_obj.scheme)
# Output: 'https'

print(url_obj.host)
# Output: 'example.com'
```

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

### Absolute Path with Domain

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/cli-reference.md

Construct a full URL by providing a domain and an absolute path.

```bash
$ url-normalize -d example.com "/images/logo.png"
# Output: https://example.com/images/logo.png
```

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

### Basic CLI Normalization

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/REFERENCE-INDEX.md

Demonstrates basic URL normalization using the command-line interface. It automatically applies a default scheme.

```bash
# Basic normalization
url-normalize "WWW.EXAMPLE.COM"
# Output: https://www.example.com/
```

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

### Complete URL Normalization Configuration

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/configuration.md

Demonstrates comprehensive URL normalization with multiple configuration options including charset, default scheme, default domain, parameter filtering, and a custom parameter allowlist.

```python
url_normalize(
    "/search?query=test&utm_source=google",
    charset="utf-8",
    default_scheme="https",
    default_domain="example.com",
    filter_params=True,
    param_allowlist=["query"]
)
# Output: "https://example.com/search?query=test"
```

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

### Basic Syntax of url-normalize

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/cli-reference.md

The basic command structure for the url-normalize CLI tool.

```bash
url-normalize [OPTIONS] URL
```

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

### Handle Relative Paths

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-helper-functions.md

Relative paths that do not start with a single slash are returned unchanged. This function only targets absolute paths for domain injection.

```python
provide_url_domain("path/to/resource", default_domain="example.com")
# Output: "path/to/resource" (relative path, unchanged)
```

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

### Handle No Host or Missing Domain

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-param-allowlist.md

Illustrates the behavior of `get_allowed_params` when no host is provided or when the domain is not found in any configured allowlist, both resulting in an empty set.

```python
result = get_allowed_params(None, allowlist=["id"])
print(result)
# Output: set()  (no host provided)

result = get_allowed_params("unknown.com")
print(result)
# Output: set()  (domain not in default allowlist)
```

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

### CLI Normalization with Parameter Filtering

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/REFERENCE-INDEX.md

Illustrates parameter filtering using the '-f' or '--filter-params' flag and specifying allowed parameters with '-p' or '--param-allowlist'.

```bash
# Parameter filtering
url-normalize -f -p "id,page" "example.com?id=1&page=2&utm=bad"
```

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

### Get Default Allowed Parameters for Google

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-param-allowlist.md

Retrieves the default allowed query parameters for 'google.com' using the `get_allowed_params` function. Requires importing the function from `url_normalize.param_allowlist`.

```python
from url_normalize.param_allowlist import get_allowed_params

result = get_allowed_params("google.com")
print(result)
# Output: {"q", "ie"}
```

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

### CLI Normalization with Custom Scheme

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/REFERENCE-INDEX.md

Shows how to specify a custom default scheme for URLs that lack one using the '-s' or '--default-scheme' option.

```bash
# Custom scheme
url-normalize -s http "example.com"
```

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

### Import Helper Functions for URL Scheme and Domain Provision

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/types.md

Imports helper functions for providing URL schemes and domains, along with associated constants.

```python
# Helper functions
from url_normalize.provide_url_scheme import provide_url_scheme, AUTHORITY_SCHEMES
from url_normalize.provide_url_domain import provide_url_domain
from url_normalize.generic_url_cleanup import generic_url_cleanup
```

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

### Parameter Filtering (Default Allowlist)

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/cli-reference.md

Filter URL parameters based on a default allowlist for specific domains like google.com.

```bash
$ url-normalize -f "google.com?q=test&utm_source=campaign"
# Output: https://google.com?q=test
# (Default allowlist for google.com includes "q" and "ie")
```

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

### Import Helper Functions

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/module-structure.md

Imports utility functions for providing URL schemes, domains, generic cleanup, and parameter allowlisting.

```python
from url_normalize.provide_url_scheme import provide_url_scheme, AUTHORITY_SCHEMES
```

```python
from url_normalize.provide_url_domain import provide_url_domain
```

```python
from url_normalize.generic_url_cleanup import generic_url_cleanup
```

```python
from url_normalize.param_allowlist import get_allowed_params, DEFAULT_ALLOWLIST
```

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

### Add Default Domain to Absolute Path

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-helper-functions.md

Use this function to prepend a default domain to URLs that start with a single slash, converting them into scheme-relative URLs. It is useful for resolving relative paths found in web content to absolute URLs.

```python
from url_normalize.provide_url_domain import provide_url_domain

provide_url_domain("/path/to/resource", default_domain="example.com")
# Output: "//example.com/path/to/resource"

provide_url_domain("/images/logo.png", default_domain="cdn.example.com")
# Output: "//cdn.example.com/images/logo.png"
```

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

### Provide URL Scheme for Basic URL

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-helper-functions.md

Prepends the default scheme ('https') to a URL that lacks one. Use this when a URL is provided without a scheme and requires one for proper resolution.

```python
from url_normalize.provide_url_scheme import provide_url_scheme

provide_url_scheme("www.example.com")
# Output: "https://www.example.com"
```

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

### Provide URL Scheme with Custom Default

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-helper-functions.md

Prepends a custom default scheme ('http') to a URL that lacks one. Useful for scenarios where 'http' is the preferred default over 'https'.

```python
provide_url_scheme("www.example.com", default_scheme="http")
# Output: "http://www.example.com"
```

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

### Basic URL Normalization and Humanization

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/REFERENCE-INDEX.md

Demonstrates normalizing a URL to a standard format and humanizing a URL for display by converting punycode and percent-encoding.

```python
from url_normalize import url_normalize, url_humanize

# Normalize a URL
normalized = url_normalize("WWW.EXAMPLE.COM/path")
# Output: "https://www.example.com/path"

# Humanize for display
humanized = url_humanize("https://xn--e1afmkfd.xn--80akhbyknj4f/")
# Output: "https://пример.испытание/"
```

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

### CLI Normalization with Humanize Display

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/REFERENCE-INDEX.md

Shows how to output a human-readable form of a normalized URL, particularly useful for internationalized domain names (IDNs), using the '-H' or '--humanize' flag.

```bash
# Humanize display form
url-normalize -H "https://xn--e1afmkfd.xn--80akhbyknj4f/"
```

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

### CLI Tool

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/COMPLETION-SUMMARY.txt

Command-line interface for normalizing and humanizing URLs.

```APIDOC
## url-normalize CLI

### Description
A command-line tool to normalize and humanize URLs directly from the terminal.

### Usage
`url-normalize [OPTIONS] [URL]`

### Options
- `-v`, `--version`: Show program's version number and exit.
- `-c`, `--config FILE`: Load configuration from a file.
- `-s`, `--scheme`: Normalize only the scheme.
- `-d`, `--domain`: Normalize only the domain.
- `-f`, `--fragment`: Normalize only the fragment.
- `-p`, `--path`: Normalize only the path.
- `-H`, `--humanize`: Humanize the URL after normalization.

### Examples
(See `cli-reference.md` for 10 practical examples covering various use cases and options)

### Exit Codes
(See `cli-reference.md` for details on exit codes)

### Output Specifications
(See `cli-reference.md` for output format details)
```

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

### Unpack URL Components into Variables

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/types.md

Demonstrates unpacking all components of a URL instance into separate variables. This is a convenient way to assign all parsed URL parts to individual names for further processing.

```python
scheme, userinfo, host, port, path, query, fragment = url_obj
```

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

### URL Normalization with Query Parameter Filtering via CLI

Source: https://github.com/niksite/url-normalize/blob/master/README.md

Filter query parameters from URLs using the CLI tool. Use the -f flag for filtering and -p for specifying an allowlist.

```bash
# With query parameter filtering
$ url-normalize -f "www.google.com/search?q=test&utm_source=test"
# Output: https://www.google.com/search?q=test

# With custom allowlist
$ url-normalize -f -p page,id "example.com?page=1&id=123&ref=test"
# Output: https://example.com/?page=1&id=123
```

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

### Humanizing URLs via CLI

Source: https://github.com/niksite/url-normalize/blob/master/README.md

Convert normalized URLs to a human-readable format from the command line using the -H flag.

```bash
# Human-readable display form
$ url-normalize -H "https://xn--e1afmkfd.xn--80akhbyknj4f/%D0%A1%D0%BB%D1%83%D0%B6%D0%B5%D0%B1%D0%BD%D0%B0%D1%8F"
# Output: https://пример.испытание/Служебная
```

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

### Architecture and Implementation

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/FILES-MANIFEST.txt

Information regarding the project's architecture, module structure, and internal workings.

```APIDOC
## Architecture and Implementation

This section provides insights into the internal structure and implementation details of the url-normalize project.

### Key Documents:
- `module-structure.md`: An overview of the project's module structure and organization.
- `api-reference-normalization-functions.md`: Detailed documentation for internal normalization functions.
```

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

### Basic URL Normalization

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/cli-reference.md

Normalize a domain name to a standard URL format with a default scheme.

```bash
$ url-normalize "WWW.EXAMPLE.COM"
# Output: https://www.example.com/
```

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

### Custom Parameter Allowlist

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/cli-reference.md

Specify a custom list of parameters to keep in the normalized URL.

```bash
$ url-normalize -f -p "id,page" "example.com?id=123&page=2&session=abc"
# Output: https://example.com?id=123&page=2
```

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

### URL Normalization with Default Domain and Scheme via CLI

Source: https://github.com/niksite/url-normalize/blob/master/README.md

Specify default domain and scheme options when normalizing URLs from the command line using -d and -s flags.

```bash
# With default domain for absolute paths
$ url-normalize -d example.com "/images/logo.png"
# Output: https://example.com/images/logo.png

# With default domain and custom scheme
$ url-normalize -d example.com -s http "/images/logo.png"
# Output: http://example.com/images/logo.png
```

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

### Handle Non-UTF-8 Output

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/cli-reference.md

Demonstrates how the CLI displays a URL when UTF-8 output is not available on the terminal. This is relevant for environments with limited character encoding support.

```bash
url-normalize -H "https://xn--e1afmkfd.xn--80akhbyknj4f/"
# Output: https://пример.испытание/
# (if UTF-8 output is not available)
```

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

### URL Normalization via uvx

Source: https://github.com/niksite/url-normalize/blob/master/README.md

Process URLs using url-normalize through the uvx command.

```bash
# Via uv tool/uvx
$ uvx url-normalize www.foo.com:80/foo
# Output: https://www.foo.com:80/foo
```

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

### Import Main API Types

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/types.md

Imports the URL type for advanced usage and the main url_normalize and url_humanize functions.

```python
# URL type (for advanced usage)
from url_normalize.tools import URL

# Main functions (typically all you need)
from url_normalize import url_normalize, url_humanize
```

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

### Custom Parameter Allowlist (List)

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/configuration.md

Applies a custom list of allowed parameters to all domains during URL normalization.

```python
url_normalize(
    "example.com?id=123&page=1&session=xyz",
    filter_params=True,
    param_allowlist=["id", "page"]
)
# Output: "https://example.com?id=123&page=1"
```

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

### Basic URL Normalization with Default Scheme

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-url_normalize.md

Adds the default 'https' scheme and lowercases the host for a given URL string. Use this for standardizing URLs that might be missing a scheme.

```python
from url_normalize import url_normalize

# Adds https scheme and lowercases host
result = url_normalize("WWW.EXAMPLE.COM/path")
print(result)
# Output: https://www.example.com/path
```

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

### Modify URL Instance Using _replace()

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/types.md

Shows how to create a modified copy of an existing URL instance by changing specific fields using the _replace() method. This is essential for updating URL components immutably.

```python
from url_normalize.tools import deconstruct_url

url_obj = deconstruct_url("https://example.com/path")
# URL(scheme='https', userinfo='', host='example.com', port='',
#     path='/path', query='', fragment='')

# Change the path
modified = url_obj._replace(path='/new/path')
# URL(scheme='https', userinfo='', host='example.com', port='',
#     path='/new/path', query='', fragment='')
```

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

### tools.py - Exported Functions

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/module-structure.md

Provides utility functions for URL component handling, including parsing, assembling, and encoding/decoding strings.

```APIDOC
## tools.py - Exported Functions

### Description
This module contains essential tools for URL manipulation, including functions to deconstruct and reconstruct URLs, and to perform percent-encoding and decoding.

### Exported Functions

#### deconstruct_url
- **Signature**: `deconstruct_url(url: str) -> URL`
- **Description**: Parses a URL string into its constituent components.

#### reconstruct_url
- **Signature**: `reconstruct_url(url: URL) -> str`
- **Description**: Assembles URL components back into a URL string.

#### quote
- **Signature**: `quote(string: str, safe: str = "/") -> str`
- **Description**: Percent-encodes a string, making it safe for URL components. The `safe` parameter specifies characters that should not be encoded.

#### unquote
- **Signature**: `unquote(string: str, charset: str = "utf-8") -> str`
- **Description**: Percent-decodes a string and normalizes it using the specified charset.

#### force_unicode
- **Signature**: `force_unicode(string: str | bytes, charset: str = "utf-8") -> str`
- **Description**: Converts a string or bytes object to a Unicode string using the specified charset.
```

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

### Import CLI Main Function

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/module-structure.md

Imports the main function for the command-line interface tool. This allows the tool to be invoked directly.

```python
from url_normalize.cli import main
```

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

### Import Main API Functions

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/module-structure.md

Imports the primary functions for URL normalization and humanization from the main library package.

```python
from url_normalize import url_normalize, url_humanize
```

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

### Handle Empty or None Inputs

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-helper-functions.md

The function handles various empty or None inputs gracefully. If the default domain is None or empty, or if the URL is empty or a hyphen, the original URL is returned without modification.

```python
provide_url_domain("/path", default_domain=None)
# Output: "/path"

provide_url_domain("", default_domain="example.com")
# Output: ""

provide_url_domain("-", default_domain="example.com")
# Output: "-"
```

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

### Humanize URLs for Display

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/REFERENCE-INDEX.md

Convert Punycode domains and percent-encoded paths into human-readable formats. Requires `url_humanize` import.

```python
from url_normalize import url_humanize

# Punycode domain
url = "https://xn--e1afmkfd.xn--80akhbyknj4f/path"
display = url_humanize(url)
# Output: https://пример.испытание/path

# Percent-encoded path
url = "https://example.com/hello%20world"
display = url_humanize(url)
# Output: https://example.com/hello world
```

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

### url_normalize()

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/COMPLETION-SUMMARY.txt

The main entry point for normalizing URLs. It processes a URL through a pipeline of normalization steps, including scheme provision, cleanup, deconstruction, component normalization, and reconstruction.

```APIDOC
## url_normalize()

### Description
This is the main entry point function for normalizing URLs according to RFC 3986 and other standards. It orchestrates a series of normalization steps.

### Signature
```python
def url_normalize(url: str, 
                 default_scheme: str = 'https', 
                 default_domain: str | None = None, 
                 filter_params: bool = False, 
                 param_allowlist: set[str] | frozenset[str] | None = None, 
                 charset: str = 'utf-8') -> str
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| url | str | None | Yes | The URL string to normalize. |
| default_scheme | str | 'https' | No | The default scheme to use if none is provided in the URL. |
| default_domain | str | None | No | A default domain to inject if the URL lacks one. |
| filter_params | bool | False | No | Whether to filter query parameters based on the allowlist. |
| param_allowlist | set[str] | None | No | A set of allowed query parameter names. Uses default allowlists if None. |
| charset | str | 'utf-8' | No | The character encoding to use for processing. |

### Return Type
- str: The normalized URL string.

### Behavior
Performs the following pipeline:
1. Domain injection (if `default_domain` provided).
2. Scheme provision (if missing).
3. Generic cleanup (shebang, trailing chars).
4. URL deconstruction into 7 components.
5. Component normalization (order-dependent).
6. Port/path normalization (depends on scheme).
7. URL reconstruction.

### Examples
```python
from url_normalize import url_normalize

# Basic normalization
print(url_normalize('http://example.com/path/'))
# Output: http://example.com/path

# With default scheme and domain
print(url_normalize('example.com/resource', default_scheme='ftp', default_domain='ftp.example.com'))
# Output: ftp://ftp.example.com/resource

# With query parameter filtering
print(url_normalize('http://example.com?a=1&b=2&c=3', filter_params=True, param_allowlist={'a'}))
# Output: http://example.com?a=1
```
```

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

### Multiple Options Combined

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/cli-reference.md

Combine multiple normalization options, including custom scheme, domain, and parameter filtering.

```bash
$ url-normalize -s http -d api.example.com -f -p "key,token" "/endpoint?key=abc&token=xyz&debug=true"
# Output: http://api.example.com/endpoint?key=abc&token=xyz
```

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

### Helper Functions

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/COMPLETION-SUMMARY.txt

Provides utility functions for URL processing, including scheme/domain injection, cleanup, and parameter handling.

```APIDOC
## Helper Functions

### provide_url_scheme(url: str, default_scheme: str) -> str
Injects a default scheme if the URL is missing one.

### provide_url_domain(url: str, default_domain: str) -> str
Injects a default domain if the URL is missing one.

### generic_url_cleanup(url: str) -> str
Performs general cleanup on the URL string.

### get_allowed_params(domain: str) -> set[str]
Retrieves the set of allowed query parameters for a given domain.

### quote(string: str, safe: str = '') -> str
Percent-encodes a string.

### unquote(string: str) -> str
Decodes a percent-encoded string.

### force_unicode(bytes_or_str: bytes | str) -> str
Ensures the input is a Unicode string.

### process_query_param(param: str, allowlist: set[str] | None = None) -> str | None
Normalizes and filters a single query parameter.

### Examples
```python
from url_normalize import provide_url_scheme, quote

print(provide_url_scheme('example.com', 'https'))
# Output: https://example.com

print(quote('a string with spaces'))
# Output: a%20string%20with%20spaces
```
```

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

### Import Component Functions for URL Deconstruction/Reconstruction

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/types.md

Imports functions for deconstructing and reconstructing URLs from the tools module.

```python
# URL deconstruction/reconstruction
from url_normalize.tools import deconstruct_url, reconstruct_url
```

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

### provide_url_scheme()

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/REFERENCE-INDEX.md

Adds a default scheme to a URL if it is missing.

```APIDOC
## provide_url_scheme()

### Description
Adds a default scheme (e.g., 'http') to a URL if the scheme is not present.

### Purpose
Add default scheme if missing
```

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

### unquote()

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-tools.md

Percent-decodes a string and normalizes it to NFC Unicode form.

```APIDOC
## unquote()

Percent-decode a string and normalize it to NFC Unicode form.

### Signature

```python
def unquote(string: str, charset: str = "utf-8") -> str
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|----------|
| string | str | — | The percent-encoded string to decode. |
| charset | str | "utf-8" | Character encoding to use when interpreting decoded bytes. |

### Return Type

`str` — The decoded and normalized Unicode string.

### Behavior

The function performs three steps:

1. **Percent-decoding**: Uses `urllib.parse.unquote()` to convert percent-encoded sequences (e.g., %20) back to their corresponding bytes, then decodes using the specified charset.
2. **Force Unicode**: Ensures the result is a Python string (not bytes), using the `force_unicode()` helper.
3. **Unicode normalization**: Normalizes the string to NFC (Canonical Composition) form as required by RFC 3986, ensuring equivalent characters are represented identically.

### Examples

#### Basic percent-decoding

```python
from url_normalize.tools import unquote

result = unquote("Hello%20World")
print(result)
# Output: Hello World
```

#### Decoding Unicode (UTF-8 encoded)

```python
result = unquote("caf%C3%A9")
print(result)
# Output: café
# (UTF-8 bytes %C3%A9 decoded to the é character)
```

#### NFC normalization

```python
result = unquote("e%CC%81")  # e + combining acute accent
print(result)
# Output: é  # (normalized to precomposed form)
```
```

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

### url_normalize()

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-url_normalize.md

Normalize a URL string by standardizing scheme, host, port, path, query, and fragment components. Returns the same input if None or empty string is provided.

```APIDOC
## url_normalize()

### Description
Normalize a URL string by standardizing scheme, host, port, path, query, and fragment components. Returns the same input if None or empty string is provided.

### Signature
```python
def url_normalize(
    url: str | None,
    *,
    charset: str = "utf-8",
    default_scheme: str = "https",
    default_domain: str | None = None,
    filter_params: bool = False,
    param_allowlist: dict | list | None = None,
) -> str | None
```

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| url | str \| None | — | Yes | The URL to normalize. If None or empty, returns unchanged. |
| charset | str | "utf-8" | No | Target charset for the URL encoding. Used in IDN domain processing and percent-encoding. |
| default_scheme | str | "https" | No | Default scheme to prepend if the URL has no scheme (e.g., "www.example.com" becomes "https://www.example.com"). |
| default_domain | str \| None | None | No | Default domain to use for absolute paths starting with "/". For example, with default_domain="example.com", "/path" becomes "https://example.com/path". |
| filter_params | bool | False | No | When True, removes all query parameters except those in the allowlist. When False, all parameters are retained. |
| param_allowlist | dict \| list \| None | None | Specifies which query parameters to keep when filter_params is True. Can be a list (applied to all domains) or dict mapping domain names to parameter lists (e.g., {"example.com": ["id", "page"]}). Ignores this parameter when filter_params is False. |

### Return Type
`str | None` — The normalized URL as a string, or None if the input was None.

### Behavior
The function performs the following normalization steps:

1. **Default domain injection**: If URL is an absolute path and `default_domain` is provided, injects the domain.
2. **Default scheme injection**: If URL lacks a scheme, prepends `default_scheme://`.
3. **Generic cleanup**: Converts shebang URLs (#!) to query form and strips trailing spaces/ampersands.
4. **URL deconstruction**: Splits the URL into components (scheme, userinfo, host, port, path, query, fragment).
5. **Component normalization**:
   - **Scheme**: Lowercased
   - **Userinfo**: Empty userinfo patterns (@, :@) removed
   - **Host**: Lowercased, trailing dots stripped, IDN domains converted to ASCII using IDNA2008 with UTS46
   - **Port**: Default ports removed (e.g., :80 for http, :443 for https)
   - **Path**: Percent-encoded with uppercase hex, dot-segments removed (./ and ../ resolved), empty path converted to / for http/https/ftp/file schemes
   - **Query**: Percent-encoded, parameters filtered if requested
   - **Fragment**: Percent-encoded
6. **URL reconstruction**: Reassembles the normalized components into a complete URL.

### Examples
#### Basic normalization with default scheme
```python
from url_normalize import url_normalize

# Adds https scheme and lowercases host
result = url_normalize("WWW.EXAMPLE.COM/path")
print(result)
# Output: https://www.example.com/path
```

#### Custom default scheme
```python
result = url_normalize("www.example.com", default_scheme="http")
print(result)
# Output: http://www.example.com/
```

#### Default domain for absolute paths
```python
result = url_normalize("/images/logo.png", default_domain="example.com")
print(result)
# Output: https://example.com/images/logo.png
```

#### Query parameter filtering with custom allowlist
```python
result = url_normalize(
    "example.com?id=123&page=1&utm_source=campaign",
    filter_params=True,
    param_allowlist=["id", "page"]
)
print(result)
# Output: https://example.com?id=123&page=1
```

#### Domain-specific parameter filtering
```python
result = url_normalize(
    "google.com?q=test&utm_source=test",
    filter_params=True,
    param_allowlist={"google.com": ["q"]}
)
print(result)
# Output: https://google.com?q=test
```

#### IDN domain normalization
```python
result = url_normalize("HTTP://пример.испытание/path")
print(result)
# Output: http://xn--e1afmkfd.xn--80akhbyknj4f/path
```

#### Removing default ports and resolving path segments
```python
result = url_normalize("HTTP://example.com:80/foo/../bar/./baz?q=1#frag")
print(result)
# Output: http://example.com/bar/baz?q=1#frag
```

### Error Handling
The function does not raise exceptions for invalid URLs. It applies best-effort normalization:

- **Invalid ports**: Non-numeric port values are preserved as-is.
- **Malformed domains**: Domain normalization failures silently fall back to direct IDNA encoding.
- **Invalid userinfo**: Preserved in the output.
- **Invalid characters in components**: Percent-encoded according to RFC 3986.

### Source
`url_normalize/url_normalize.py:24-81`
```

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

### Handle Stdin/Stdout Indicator URL

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-helper-functions.md

Returns the '-' character unchanged, which is used to indicate standard input or standard output.

```python
provide_url_scheme("-")
# Output: "-" (stdin/stdout indicator, unchanged)
```

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

### Normalize Relative URL with Default Domain

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-helper-functions.md

Demonstrates normalizing a relative URL found on a specific domain to an absolute URL using `url_normalize` with a `default_domain`.

```python
from url_normalize import url_normalize

# Normalize a relative URL found on example.com
result = url_normalize("/products/item", default_domain="example.com")
# Output: https://example.com/products/item
```

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

### URL Normalization with Default Domain and Scheme

Source: https://github.com/niksite/url-normalize/blob/master/README.md

Set a default domain and scheme for URL normalization, useful for resolving relative URLs.

```python
# With default domain for absolute paths
print(url_normalize("/images/logo.png", default_domain="example.com"))
# Output: https://example.com/images/logo.png

# With default domain and custom scheme
print(url_normalize("/images/logo.png", default_scheme="http", default_domain="example.com"))
# Output: http://example.com/images/logo.png
```

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

### unquote()

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/REFERENCE-INDEX.md

Percent-decodes and normalizes a URL-encoded string.

```APIDOC
## unquote()

### Description
Performs percent-decoding and normalization on a string.

### Arguments
- **string** (str): The string to decode.
- **charset** (str, optional): The character set to use for decoding.

### Returns
- str: The decoded and normalized string.
```

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

### Define Default Query Parameter Allowlist

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/api-reference-param-allowlist.md

This dictionary defines the default query parameters that are preserved for common search engines and video platforms during URL normalization.

```python
DEFAULT_ALLOWLIST = {
    "google.com": ["q", "ie"],
    "baidu.com": ["wd", "ie"],
    "bing.com": ["q"],
    "youtube.com": ["v", "search_query"],
}
```

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

### Import URL Deconstruction and Reconstruction Functions

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/module-structure.md

Imports functions for breaking down a URL into its components and reassembling it from components.

```python
from url_normalize.tools import deconstruct_url, reconstruct_url
```

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

### Basic URL Normalization via CLI

Source: https://github.com/niksite/url-normalize/blob/master/README.md

Normalize URLs directly from the terminal using the url-normalize command. It defaults to using 'https' as the scheme.

```bash
$ url-normalize "www.foo.com:80/foo"
# Output: https://www.foo.com/foo

# With custom default scheme
$ url-normalize -s http "www.foo.com/foo"
# Output: http://www.foo.com/foo
```

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

### Import Individual Normalizer Functions

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/types.md

Imports individual functions for normalizing specific URL components like scheme, host, port, path, query, fragment, and userinfo.

```python
# Individual normalizers
from url_normalize.normalize_scheme import normalize_scheme, DEFAULT_SCHEME
from url_normalize.normalize_host import normalize_host, DEFAULT_CHARSET
from url_normalize.normalize_port import normalize_port, DEFAULT_PORT
from url_normalize.normalize_path import normalize_path
from url_normalize.normalize_query import normalize_query
from url_normalize.normalize_fragment import normalize_fragment
from url_normalize.normalize_userinfo import normalize_userinfo
```

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

### Parameter Filtering with Default Allowlist

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/configuration.md

Filters URL parameters based on a default allowlist. Only parameters present in the allowlist are retained.

```python
url_normalize(
    "google.com?q=test&utm_source=campaign",
    filter_params=True
)
# Output: "https://google.com?q=test"
# (uses default allowlist: google.com allows "q" and "ie")
```

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

### Humanize Unicode Characters

Source: https://github.com/niksite/url-normalize/blob/master/_autodocs/cli-reference.md

Decode Punycode domain names to their Unicode equivalents for human readability.

```bash
$ url-normalize -H "https://xn--e1afmkfd.xn--80akhbyknj4f/path"
# Output: https://пример.испытание/path
# (Punycode domain decoded to Unicode characters)
```