rfc3986

https://rfc3986.readthedocs.io/en/latest/
Admin
rfc3986 is a Python implementation of RFC 3986 for parsing, validating, and building URIs with...
Tokens:13,723
Snippets:130
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### URIBuilder Usage Examples

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Examples demonstrating how to use the URIBuilder to construct URIs by adding various components like scheme, host, path, and credentials.

```APIDOC
## URIBuilder Examples

### Description
Examples demonstrating how to use the URIBuilder to construct URIs by adding various components like scheme, host, and path.

### Request Example
```python
from rfc3986 import URIBuilder

# Example 1: Basic URI construction
uri_string_1 = URIBuilder().add_scheme('https').add_host('github.com').add_path('sigmavirus24/rfc3986').finalize().unsplit()
print(uri_string_1)
# Expected output: 'https://github.com/sigmavirus24/rfc3986'

# Example 2: URI construction with credentials
uri_string_2 = URIBuilder().add_scheme('https').add_host('github.com').add_path('sigmavirus24/rfc3986').add_credentials('sigmavirus24', 'not-re@l').finalize().unsplit()
print(uri_string_2)
# Expected output: 'https://sigmavirus24:not-re%40l@github.com/sigmavirus24/rfc3986'
```

### Method
N/A (Illustrative examples)

### Endpoint
N/A (Illustrative examples)

### Parameters
N/A (Illustrative examples)

### Request Body
N/A (Illustrative examples)

### Response
N/A (Illustrative examples)
```

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

### Install rfc3986 using pip

Source: https://rfc3986.readthedocs.io/en/latest/index.html

Use pip to install the rfc3986 library. This command installs the package for the current Python environment.

```bash
pip install rfc3986
```

```bash
python -m pip install rfc3986
```

```bash
python3.6 -m pip install rfc3986
```

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

### Build a basic URL from scratch

Source: https://rfc3986.readthedocs.io/en/latest/user/building.html

Use URIBuilder to construct a URL with a scheme and host. Call finalize() to get a URIReference and unsplit() to get the string representation.

```python
from rfc3986 import builder
print(builder.URIBuilder().add_scheme(
    'https'
).add_host(
    'github.com'
).finalize().unsplit())
```

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

### URIBuilder.add_path()

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds a path to the URI builder. If the path does not start with a '/', it will be prepended with one.

```APIDOC
## URIBuilder.add_path()

### Description
Add a path to the URI.

### Method
Instance Method

### Endpoint
N/A (Instance Method)

### Parameters
- **path** (string) - Required - The path to add to the URI (e.g., '/users', 'checkout.php').

### Request Example
```python
from rfc3986.builder import URIBuilder

builder = URIBuilder()
new_builder_relative = builder.add_path('sigmavirus24/rfc3985')
new_builder_absolute = builder.add_path('/checkout.php')
```

### Response
#### Success Response (200)
- **URIBuilder instance** - A new URIBuilder instance with the path added.

#### Response Example
```json
{
  "scheme": null,
  "userinfo": null,
  "host": null,
  "port": null,
  "path": "/sigmavirus24/rfc3986",
  "query": null,
  "fragment": null
}
```
```

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

### Add Path to URI Builder

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds a path to the URI. If the path does not start with a '/', it will be prepended with one.

```python
>>> URIBuilder().add_path('sigmavirus24/rfc3985')
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path='/sigmavirus24/rfc3986', query=None, fragment=None)
```

```python
>>> URIBuilder().add_path('/checkout.php')
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path='/checkout.php', query=None, fragment=None)
```

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

### Replace components of an existing URI

Source: https://rfc3986.readthedocs.io/en/latest/user/building.html

Create a URIBuilder from an existing URI string or URIReference to modify its components. This example replaces the scheme of a given URI.

```python
from rfc3986 import builder
print(builder.URIBuilder.from_uri("http://github.com").add_scheme(
    'https'
).finalize().unsplit())
```

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

### Configure and Validate URI with Validator Class

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/validators.html

Demonstrates how to instantiate a Validator, configure it with requirements like presence of scheme, host, and path, and allowed schemes and hosts. It then shows how to validate a URI and the expected exception for an invalid URI.

```python
>>> from rfc3986 import api, validators
>>> uri = api.uri_reference('https://github.com/')
>>> validator = validators.Validator().require_presence_of(
...    'scheme', 'host', 'path',
... ).allow_schemes(
...    'http', 'https',
... ).allow_hosts(
...    '127.0.0.1', 'github.com',
... )
>>> validator.validate(uri)
>>> invalid_uri = rfc3986.uri_reference('imap://mail.google.com')
>>> validator.validate(invalid_uri)
Traceback (most recent call last):
...r
rfc3986.exceptions.MissingComponentError: ('path was required but
missing', URIReference(scheme=u'imap', authority=u'mail.google.com',
path=None, query=None, fragment=None), ['path'])
```

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

### Build a basic URL with URIBuilder

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Construct a simple URL by adding a scheme, host, and path using URIBuilder.

```python
URIBuilder().add_scheme('https').add_host('github.com').add_path('sigmavirus24/rfc3986').finalize().unsplit()
```

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

### Build a URL with credentials using URIBuilder

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Construct a URL including username and password, ensuring special characters in credentials are properly encoded.

```python
URIBuilder().add_scheme('https').add_host('github.com').add_path('sigmavirus24/rfc3986').add_credentials('sigmavirus24', 'not-re@l').finalize().unsplit()
```

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

### URIBuilder.from_uri()

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Initializes a URI builder instance from an existing URI reference, either as a string or a URIReference object.

```APIDOC
## URIBuilder.from_uri()

### Description
Initialize the URI builder from another URI. Takes the given URI reference and creates a new URI builder instance populated with the values from the reference. If given a string it will try to convert it to a reference before constructing the builder.

### Method
Class Method

### Endpoint
N/A (Class Method)

### Parameters
- **reference** (string or URIReference) - Required - The URI reference to initialize the builder from.

### Request Example
```python
from rfc3986.builder import URIBuilder

uri_string = "https://www.example.com/path?query=value#fragment"
builder = URIBuilder.from_uri(uri_string)
```

### Response
#### Success Response (200)
- **URIBuilder instance** - A new URIBuilder instance populated with values from the provided reference.

#### Response Example
```json
{
  "scheme": "https",
  "userinfo": null,
  "host": "www.example.com",
  "port": null,
  "path": "/path",
  "query": "query=value",
  "fragment": "fragment"
}
```
```

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

### Add Pre-formatted Query String

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds a query string that is already formatted to the URI builder. Ensure the string is correctly encoded.

```python
>>> URIBuilder().add_query('a=b&c=d')
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path=None, query='a=b&c=d', fragment=None)
```

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

### Add Credentials to URI Builder

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds username and password to the userinfo part of the URI. If the password is None, only the username is included.

```python
>>> URIBuilder().add_credentials('root', 's3crete')
URIBuilder(scheme=None, userinfo='root:s3crete', host=None,
        port=None, path=None, query=None, fragment=None)
```

```python
>>> URIBuilder().add_credentials('root', None)
URIBuilder(scheme=None, userinfo='root', host=None,
        port=None, path=None, query=None, fragment=None)
```

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

### URIBuilder Class Initialization

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

The URIBuilder class is used to construct URI references. It is recommended to instantiate it without arguments and use its methods to populate fields.

```APIDOC
## URIBuilder Class

### Description
Object to aid in building up a URI Reference from parts. It is recommended that this object is not provided with arguments during instantiation. Instead, use the available methods to populate the fields.

### Method
Constructor

### Parameters
- **scheme** (string) - Optional - The scheme of the URI.
- **userinfo** (string) - Optional - The userinfo of the URI.
- **host** (string) - Optional - The host of the URI.
- **port** (string) - Optional - The port of the URI.
- **path** (string) - Optional - The path of the URI.
- **query** (string) - Optional - The query string of the URI.
- **fragment** (string) - Optional - The fragment of the URI.

### Request Example
```python
from rfc3986.builder import URIBuilder

builder = URIBuilder()
```

### Response
#### Success Response (200)
- **URIBuilder instance** - An instance of the URIBuilder class.

#### Response Example
```json
{
  "scheme": null,
  "userinfo": null,
  "host": null,
  "port": null,
  "path": null,
  "query": null,
  "fragment": null
}
```
```

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

### Modify URL components with copy_with

Source: https://rfc3986.readthedocs.io/en/latest/user/parsing.html

Create a new URL instance with modified components by using the `copy_with()` method. This method does not alter the original URL instance.

```python
print(url.copy_with(
    userinfo='username:password',
    port='443',
).unsplit())
```

```python
print(url.copy_with(
    scheme='ssh',
    userinfo='git',
).unsplit())
```

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

### URIBuilder.add_host()

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds a hostname to the URI builder.

```APIDOC
## URIBuilder.add_host()

### Description
Add hostname to the URI.

### Method
Instance Method

### Endpoint
N/A (Instance Method)

### Parameters
- **host** (string) - Required - The hostname to add to the URI (e.g., 'google.com').

### Request Example
```python
from rfc3986.builder import URIBuilder

builder = URIBuilder()
new_builder = builder.add_host('google.com')
```

### Response
#### Success Response (200)
- **URIBuilder instance** - A new URIBuilder instance with the host added.

#### Response Example
```json
{
  "scheme": null,
  "userinfo": null,
  "host": "google.com",
  "port": null,
  "path": null,
  "query": null,
  "fragment": null
}
```
```

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

### Build multiple URIs from a base instance

Source: https://rfc3986.readthedocs.io/en/latest/user/building.html

Demonstrates the immutability of URIBuilder. Each method call returns a new instance, allowing multiple distinct URIs to be built from a single base builder.

```python
from rfc3986 import builder
github_builder = builder.URIBuilder().add_scheme(
    'https'
).add_host(
    'api.github.com'
)
print(github_builder.add_path(
    '/users/sigmavirus24'
).finalize().unsplit())
print(github_builder.add_path(
    '/repos/sigmavirus24/rfc3986'
).finalize().unsplit())
```

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

### Validating Component Presence

Source: https://rfc3986.readthedocs.io/en/latest/user/validating.html

Demonstrates default behavior where components are not required, followed by enforcing mandatory components.

```python
>>> from rfc3986 import validators, uri_reference
>>> user_url = 'https://github.com/sigmavirus24/rfc3986'
>>> validator = validators.Validator().allow_schemes(
...     'https',
... ).allow_hosts(
...     'github.com',
... ).forbid_use_of_password()
>>> validator.validate(uri_reference('//github.com'))
>>> validator.validate(uri_reference('https:/'))
```

```python
>>> from rfc3986 import validators, uri_reference
>>> user_url = 'https://github.com/sigmavirus24/rfc3986'
>>> validator = validators.Validator().allow_schemes(
...     'https',
... ).allow_hosts(
...     'github.com',
... ).forbid_use_of_password(
... ).require_presence_of(
...     'scheme', 'host',
... )
>>> validator.validate(uri_reference('//github.com'))
Traceback (most recent call last):
   ...
rfc3986.exceptions.MissingComponentError
>>> validator.validate(uri_reference('https:/'))
Traceback (most recent call last):
   ...
rfc3986.exceptions.MissingComponentError
>>> validator.validate(uri_reference('https://github.com'))
>>> validator.validate(uri_reference(
...     'https://github.com/sigmavirus24/rfc3986'
... ))
```

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

### URIBuilder.add_credentials()

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds user credentials (username and password) to the userinfo part of the URI.

```APIDOC
## URIBuilder.add_credentials()

### Description
Add credentials as the userinfo portion of the URI.

### Method
Instance Method

### Endpoint
N/A (Instance Method)

### Parameters
- **username** (string) - Required - The username for authentication.
- **password** (string) - Optional - The password for authentication. If None, only the username is included.

### Request Example
```python
from rfc3986.builder import URIBuilder

builder = URIBuilder()
new_builder_with_password = builder.add_credentials('root', 's3crete')
new_builder_without_password = builder.add_credentials('root', None)
```

### Response
#### Success Response (200)
- **URIBuilder instance** - A new URIBuilder instance with the userinfo added.

#### Response Example
```json
{
  "scheme": null,
  "userinfo": "root:s3crete",
  "host": null,
  "port": null,
  "path": null,
  "query": null,
  "fragment": null
}
```
```

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

### URIBuilder.add_query()

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds a pre-formatted query string to the URI builder.

```APIDOC
## URIBuilder.add_query()

### Description
Add a pre-formated query string to the URI.

### Method
Instance Method

### Endpoint
N/A (Instance Method)

### Parameters
- **query** (string) - Required - The pre-formatted query string (e.g., 'a=b&c=d').

### Request Example
```python
from rfc3986.builder import URIBuilder

builder = URIBuilder().add_query('a=b&c=d')
```

### Response
#### Success Response (200)
- **URIBuilder instance** - A new URIBuilder instance with the query string added.

#### Response Example
```json
{
  "scheme": null,
  "userinfo": null,
  "host": null,
  "port": null,
  "path": null,
  "query": "a=b&c=d",
  "fragment": null
}
```
```

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

### URIBuilder.geturl() Method

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Documentation for the geturl() method of the URIBuilder class, which generates the final URL from the builder.

```APIDOC
## URIBuilder.geturl()

### Description
Generate the URL from this builder. This is an alternative to calling `finalize()` and keeping the `rfc3986.uri.URIReference` around.

### Method
`geturl()`

### Endpoint
N/A (Method of a class)

### Parameters
None

### Request Body
None

### Request Example
```python
from rfc3986 import URIBuilder

builder = URIBuilder().add_scheme('https').add_host('example.com').add_path('resource')
url = builder.geturl()
print(url)
# Expected output: 'https://example.com/resource'
```

### Response
- **url** (string) - The generated URL string.

### Response Example
```json
{
  "url": "https://example.com/resource"
}
```

### New in version
1.5.0
```

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

### Add Host to URI Builder

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds a hostname to the URI builder. This is a straightforward addition of the host string.

```python
>>> URIBuilder().add_host('google.com')
URIBuilder(scheme=None, userinfo=None, host='google.com',
        port=None, path=None, query=None, fragment=None)
```

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

### Allowing Trusted Domains and Schemes

Source: https://rfc3986.readthedocs.io/en/latest/user/validating.html

Configure a validator to restrict URIs to specific schemes and hostnames.

```python
>>> from rfc3986 import validators, uri_reference
>>> user_url = 'https://github.com/sigmavirus24/rfc3986'
>>> validator = validators.Validator().allow_schemes(
...     'https',
... ).allow_hosts(
...     'github.com',
... )
>>> validator.validate(uri_reference(
...     'https://github.com/sigmavirus24/rfc3986'
... ))
>>> validator.validate(uri_reference(
...     'https://github.com/'
... ))
>>> validator.validate(uri_reference(
...     'http://example.com'
... ))
Traceback (most recent call last):
   ...
rfc3986.exceptions.UnpermittedComponentError
```

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

### URIBuilder.add_query_from()

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds query parameters to the URI builder from a dictionary or a list of tuples. Values with spaces are automatically encoded with a '+'.

```APIDOC
## URIBuilder.add_query_from()

### Description
Generate and add a query from a dictionary or list of tuples.

### Method
Instance Method

### Endpoint
N/A (Instance Method)

### Parameters
- **query_items** (dict or list of tuples) - Required - A dictionary or list of (key, value) tuples representing the query parameters.

### Request Example
```python
from rfc3986.builder import URIBuilder

builder_dict = URIBuilder().add_query_from({'a': 'b c'})
builder_list = URIBuilder().add_query_from([('a', 'b c')])
```

### Response
#### Success Response (200)
- **URIBuilder instance** - A new URIBuilder instance with the query added.

#### Response Example
```json
{
  "scheme": null,
  "userinfo": null,
  "host": null,
  "port": null,
  "path": null,
  "query": "a=b+c",
  "fragment": null
}
```
```

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

### Add URL-safe credentials to a URI

Source: https://rfc3986.readthedocs.io/en/latest/user/building.html

The add_credentials method handles URL-encoding of username and password, ensuring they are safe for use in the URI's authority component.

```python
from rfc3986 import builder
print(builder.URIBuilder().add_scheme(
    'https'
).add_host(
    'api.github.com'
).add_credentials(
    username='us3r',
    password='p@ssw0rd',
).finalize().unsplit())
```

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

### Extend Query with New Items

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Extends the existing query string with new parameters from a dictionary or list of tuples. Existing parameters are preserved.

```python
>>> URIBuilder(query='a=b+c').extend_query_with({'a': 'b c'})
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path=None, query='a=b+c&a=b+c', fragment=None)
```

```python
>>> URIBuilder(query='a=b+c').extend_query_with([('a', 'b c')])
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path=None, query='a=b+c&a=b+c', fragment=None)
```

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

### Add Query from Dictionary or List

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds query parameters to the URI from a dictionary or a list of tuples. Spaces in values are encoded as '+'.

```python
>>> URIBuilder().add_query_from({'a': 'b c'})
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path=None, query='a=b+c', fragment=None)
```

```python
>>> URIBuilder().add_query_from([('a', 'b c')])
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path=None, query='a=b+c', fragment=None)
```

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

### Parse a URI reference with uri_reference

Source: https://rfc3986.readthedocs.io/en/latest/user/parsing.html

Use `rfc3986.uri_reference()` to parse a URI reference. This is recommended when not replacing `urllib.parse`.

```python
uri = rfc3986.uri_reference('https://github.com/sigmavirus24/rfc3986')
```

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

### URIBuilder.extend_query_with()

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Extends the existing query string of the URI builder with new query items from a dictionary or list of tuples.

```APIDOC
## URIBuilder.extend_query_with()

### Description
Extend the existing query string with the new query items.

### Method
Instance Method

### Endpoint
N/A (Instance Method)

### Parameters
- **query_items** (dict or list of tuples) - Required - A dictionary or list of (key, value) tuples to append to the existing query string.

### Request Example
```python
from rfc3986.builder import URIBuilder

builder_dict = URIBuilder(query='a=b+c').extend_query_with({'a': 'b c'})
builder_list = URIBuilder(query='a=b+c').extend_query_with([('a', 'b c')])
```

### Response
#### Success Response (200)
- **URIBuilder instance** - A new URIBuilder instance with the query extended.

#### Response Example
```json
{
  "scheme": null,
  "userinfo": null,
  "host": null,
  "port": null,
  "path": null,
  "query": "a=b+c&a=b+c",
  "fragment": null
}
```
```

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

### Add query parameters from a list of tuples

Source: https://rfc3986.readthedocs.io/en/latest/user/building.html

Use add_query_from to add multiple query parameters to a URI from a list of key-value tuples. Parameters are automatically URL-encoded.

```python
from rfc3986 import builder
print(builder.URIBuilder().add_scheme(
    'https'
).add_host(
    'search.example.com'
).add_path(
    '_search'
).add_query_from(
    [('q', 'repo:sigmavirus24/rfc3986'), ('sort', 'created_at:asc')]
).finalize().unsplit())
```

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

### Append query parameters to an existing URI

Source: https://rfc3986.readthedocs.io/en/latest/user/building.html

Extend an existing URI's query string with new parameters using extend_query_with. This is useful when merging query parameters.

```python
from rfc3986 import builder
print(builder.URIBuilder().from_uri(
   'https://search.example.com/_search?q=repo%3Asigmavirus24%2Frfc3986'
).extend_query_with(
    [('sort', 'created_at:asc')]
).finalize().unsplit())
```

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

### Parse a URL with urlparse

Source: https://rfc3986.readthedocs.io/en/latest/user/parsing.html

Use `rfc3986.urlparse()` to parse a URL. This function is suitable for completely replacing `urllib.parse.urlparse()`.

```python
url = rfc3986.urlparse('https://github.com/sigmavirus24/rfc3986')
```

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

### URIBuilder.add_port()

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds a port number to the URI builder.

```APIDOC
## URIBuilder.add_port()

### Description
Add port to the URI.

### Method
Instance Method

### Endpoint
N/A (Instance Method)

### Parameters
- **port** (integer or string) - Required - The port number to add to the URI (e.g., 80, 443).

### Request Example
```python
from rfc3986.builder import URIBuilder

builder = URIBuilder()
new_builder_http = builder.add_port(80)
new_builder_https = builder.add_port(443)
```

### Response
#### Success Response (200)
- **URIBuilder instance** - A new URIBuilder instance with the port added.

#### Response Example
```json
{
  "scheme": null,
  "userinfo": null,
  "host": null,
  "port": "80",
  "path": null,
  "query": null,
  "fragment": null
}
```
```

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

### uri_reference

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/api.html

Parses a URI string into a URIReference object. This is a convenience function.

```APIDOC
## uri_reference

### Description
Parses a URI string into a URIReference.
This is a convenience function. You could achieve the same end by using `URIReference.from_string(uri)`.

### Method
POST

### Endpoint
/websites/rfc3986_readthedocs_io_en/api/uri_reference

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **uri** (str) - Required - The URI which needs to be parsed into a reference.
- **encoding** (str) - Optional - The encoding of the string provided.

### Request Example
{
  "uri": "mailto:user@example.com",
  "encoding": "utf-8"
}

### Response
#### Success Response (200)
- **URIReference** (object) - A URIReference object representing the parsed URI.

#### Response Example
{
  "scheme": "mailto",
  "path": "user@example.com"
}
```

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

### Access URL components

Source: https://rfc3986.readthedocs.io/en/latest/user/parsing.html

Access individual components of a parsed URL instance directly.

```python
print(url.scheme)
```

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

### Add Port to URI Builder

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds a port number to the URI builder. The port is stored as a string.

```python
>>> URIBuilder().add_port(80)
URIBuilder(scheme=None, userinfo=None, host=None, port='80',
        path=None, query=None, fragment=None)
```

```python
>>> URIBuilder().add_port(443)
URIBuilder(scheme=None, userinfo=None, host=None, port='443',
        path=None, query=None, fragment=None)
```

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

### RFC 3986 Regular Expressions

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/miscellaneous.html

This section lists the compiled regular expressions available for parsing URI components.

```APIDOC
## RFC 3986 Regular Expressions

This section details the compiled regular expressions used for parsing URI components according to RFC 3986.

### RELATIVE_PART_RE

Regular expression to parse the relative URI when resolving URIs.

### HIER_PART_RE

The hierarchical part of a URI. This regular expression is used when resolving relative URIs. See **RFC 3986#section-3**.

### URI_MATCHER

Compiled version of `rfc3986.abnf_regexp.URL_PARSING_RE`.

### SUBAUTHORITY_MATCHER

Compiled compilation of `rfc3986.abnf_regexp.USERINFO_RE`, `rfc3986.abnf_regexp.HOST_PATTERN`, `rfc3986.abnf_regexp.PORT_RE`.

### SCHEME_MATCHER

Compiled version of `rfc3986.abnf_regexp.SCHEME_RE`.

### IPv4_MATCHER

Compiled version of `rfc3986.abnf_regexp.IPv4_RE`.

### PATH_MATCHER

Compiled version of `rfc3986.abnf_regexp.PATH_RE`.

### QUERY_MATCHER

Compiled version of `rfc3986.abnf_regexp.QUERY_RE`.

### RELATIVE_REF_MATCHER

Compiled compilation of `rfc3986.abnf_regexp.SCHEME_RE`, `rfc3986.abnf_regexp.HIER_PART_RE`, `rfc3986.abnf_regexp.QUERY_RE`.
```

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

### URIBuilder.extend_path()

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Extends the existing path of the URI builder with a new path segment. Handles leading/trailing slashes appropriately.

```APIDOC
## URIBuilder.extend_path()

### Description
Extend the existing path value with the provided value.

### Method
Instance Method

### Endpoint
N/A (Instance Method)

### Parameters
- **path** (string) - Required - The path segment to append to the existing path.

### Request Example
```python
from rfc3986.builder import URIBuilder

builder = URIBuilder(path="/users")
new_builder = builder.extend_path("/sigmavirus24")
```

### Response
#### Success Response (200)
- **URIBuilder instance** - A new URIBuilder instance with the path extended.

#### Response Example
```json
{
  "scheme": null,
  "userinfo": null,
  "host": null,
  "port": null,
  "path": "/users/sigmavirus24",
  "query": null,
  "fragment": null
}
```
```

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

### URIBuilder.add_fragment()

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds a fragment identifier to the URI builder.

```APIDOC
## URIBuilder.add_fragment()

### Description
Add a fragment to the URI.

### Method
Instance Method

### Endpoint
N/A (Instance Method)

### Parameters
- **fragment** (string) - Required - The fragment identifier to add to the URI (e.g., 'section-2.6.1').

### Request Example
```python
from rfc3986.builder import URIBuilder

builder = URIBuilder().add_fragment('section-2.6.1')
```

### Response
#### Success Response (200)
- **URIBuilder instance** - A new URIBuilder instance with the fragment added.

#### Response Example
```json
{
  "scheme": null,
  "userinfo": null,
  "host": null,
  "port": null,
  "path": null,
  "query": null,
  "fragment": "section-2.6.1"
}
```
```

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

### Finalize URI Builder to URIReference

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Creates a URIReference object from the current state of the URIBuilder. This is the final step in constructing a URI.

```python
>>> URIBuilder().add_scheme('https').add_host('github.com'
```

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

### URIBuilder.finalize()

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Creates a URIReference object from the current state of the URI builder.

```APIDOC
## URIBuilder.finalize()

### Description
Create a URIReference from our builder.

### Method
Instance Method

### Endpoint
N/A (Instance Method)

### Parameters
None

### Request Example
```python
from rfc3986.builder import URIBuilder

builder = URIBuilder().add_scheme('https').add_host('github.com')
uri_reference = builder.finalize()
```

### Response
#### Success Response (200)
- **URIReference object** - A URIReference object representing the built URI.

#### Response Example
```python
# Assuming the builder was configured with scheme='https' and host='github.com'
# The output would be a URIReference object, which can be represented as a string:
"https://github.com"
```
```

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

### URIBuilder.add_scheme()

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds a scheme to the URI builder. This method returns a new URIBuilder instance with the scheme added.

```APIDOC
## URIBuilder.add_scheme()

### Description
Add a scheme to our builder object. After normalizing, this will generate a new URIBuilder instance with the specified scheme and all other attributes the same.

### Method
Instance Method

### Endpoint
N/A (Instance Method)

### Parameters
- **scheme** (string) - Required - The scheme to add to the URI (e.g., 'http', 'https').

### Request Example
```python
from rfc3986.builder import URIBuilder

builder = URIBuilder()
new_builder = builder.add_scheme('HTTPS')
```

### Response
#### Success Response (200)
- **URIBuilder instance** - A new URIBuilder instance with the scheme added.

#### Response Example
```json
{
  "scheme": "https",
  "userinfo": null,
  "host": null,
  "port": null,
  "path": null,
  "query": null,
  "fragment": null
}
```
```

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

### Add Scheme to URI Builder

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Use this method to add a scheme to the URI builder. The scheme is normalized to lowercase.

```python
>>> URIBuilder().add_scheme('HTTPS')
URIBuilder(scheme='https', userinfo=None, host=None, port=None,
        path=None, query=None, fragment=None)
```

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

### Validator Methods

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/validators.html

Methods for configuring the Validator instance to enforce specific validation rules.

```APIDOC
## Validator Methods

### `allow_schemes(*schemes)`

#### Description
Require the scheme to be one of the provided schemes.

#### New in version
1.0

#### Parameters
* **schemes** (list of str) - Schemes, without `://` that are allowed.

#### Returns
* **Validator** - The validator instance.

### `allow_hosts(*hosts)`

#### Description
Require the host to be one of the provided hosts.

#### New in version
1.0

#### Parameters
* **hosts** (list of str) - Hosts that are allowed.

#### Returns
* **Validator** - The validator instance.

### `allow_ports(*ports)`

#### Description
Require the port to be one of the provided ports.

#### New in version
1.0

#### Parameters
* **ports** (list of int) - Ports that are allowed.

#### Returns
* **Validator** - The validator instance.

### `allow_use_of_password()`

#### Description
Allow passwords to be present in the URI.

#### New in version
1.0

#### Returns
* **Validator** - The validator instance.

### `check_validity_of(*components)`

#### Description
Check the validity of the components provided. This can be specified repeatedly.

#### New in version
1.1

#### Parameters
* **components** (list of str) - Names of components from `Validator.COMPONENT_NAMES`.

#### Returns
* **Validator** - The validator instance.

### `forbid_use_of_password()`

#### Description
Prevent passwords from being included in the URI.

#### New in version
1.0

#### Returns
* **Validator** - The validator instance.

### `require_presence_of(*components)`

#### Description
Require the components provided. This can be specified repeatedly.

#### New in version
1.0

#### Parameters
* **components** (list of str) - Names of components from `Validator.COMPONENT_NAMES`.

#### Returns
* **Validator** - The validator instance.

### `validate(uri)`

#### Description
Check a URI for conditions specified on this validator.

#### New in version
1.0

#### Parameters
* **uri** (URIReference) - Parsed URI to validate.

#### Raises
* **MissingComponentError** – When a required component is missing.
* **UnpermittedComponentError** – When a component is not one of those allowed.
* **PasswordForbidden** – When a password is present in the userinfo component but is not permitted by configuration.
* **InvalidComponentsError** – When a component was found to be invalid.
```

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

### Validate URI Components with rfc3986 Validator

Source: https://rfc3986.readthedocs.io/en/latest/user/validating.html

Use `rfc3986.validators.Validator` to check URI components. Configure allowed schemes, hosts, forbidden elements, and required components. The `validate` method raises `InvalidComponentsError` for invalid URIs.

```python
>>> from rfc3986 import validators, uri_reference
>>> valid_uri = uri_reference('https://github.com/')
>>> validator = validators.Validator().allow_schemes(
...     'https',
... ).allow_hosts(
...     'github.com',
... ).forbid_use_of_password(
... ).require_presence_of(
...     'scheme', 'host',
... ).check_validity_of(
...     'scheme', 'host', 'path',
... )
>>> validator.validate(valid_uri)
>>> invalid_uri = valid_uri.copy_with(path='/#invalid/path')
>>> validator.validate(invalid_uri)
Traceback (most recent call last):
   ... 
rfc3986.exceptions.InvalidComponentsError
```

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

### Parse SSH URL with double slash prefix

Source: https://rfc3986.readthedocs.io/en/latest/user/parsing.html

Adding a double slash prefix `//` to an SSH URL allows `rfc3986.uri_reference()` to better distinguish the authority and path components, though strict RFC 3986 conformance may still lead to unexpected results for non-standard URIs.

```python
>>> rfc3986.uri_reference('//git@github.com:sigmavirus24/rfc3986')
URIReference(scheme=None, authority=u'git@github.com:sigmavirus24',
path=u'/rfc3986', query=None, fragment=None)
```

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

### IRIReference Methods

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/iri.html

Methods available on the IRIReference class for parsing, encoding, and manipulating IRI components.

```APIDOC
## IRIReference.from_string

### Description
Parse an IRI reference from the given unicode IRI string.

### Parameters
#### Path Parameters
- **iri_string** (str) - Required - Unicode IRI to be parsed into a reference.
- **encoding** (str) - Optional - The encoding of the string provided (default: 'utf-8')

### Response
- **Returns** (IRIReference) - An IRIReference object or subclass thereof.

## IRIReference.encode

### Description
Encode an IRIReference into a URIReference instance.

### Parameters
#### Path Parameters
- **idna_encoder** (function) - Optional - Function that encodes each part of the host component.

### Response
- **Returns** (uri.URIReference) - A URI reference.

## IRIReference.unsplit

### Description
Create a URI string from the components.

### Response
- **Returns** (str) - The URI Reference reconstituted as a string.

## IRIReference.resolve_with

### Description
Use an absolute URI Reference to resolve this relative reference.

### Parameters
#### Path Parameters
- **base_uri** (str or URIReference) - Required - An absolute URI used to resolve the reference.
- **strict** (bool) - Optional - Whether to use strict resolution (default: False).

### Response
- **Returns** (URIReference) - A new URIReference which is the result of resolving this reference.

## IRIReference.copy_with

### Description
Create a copy of this reference with the new components.

### Parameters
#### Path Parameters
- **scheme** (str) - Optional - The scheme to use for the new reference.
- **authority** (str) - Optional - The authority to use for the new reference.
- **path** (str) - Optional - The path to use for the new reference.
- **query** (str) - Optional - The query to use for the new reference.
- **fragment** (str) - Optional - The fragment to use for the new reference.

### Response
- **Returns** (URIReference) - New URIReference with provided components.

## IRIReference.is_absolute

### Description
Determine if this URI Reference is an absolute URI.

### Response
- **Returns** (bool) - True if it is an absolute URI, False otherwise.

## IRIReference.authority_info

### Description
Return a dictionary with the userinfo, host, and port.

### Response
- **Returns** (dict) - {'userinfo': 'username:password', 'host': 'www.example.com', 'port': '80'}
```

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

### Modify URI reference components

Source: https://rfc3986.readthedocs.io/en/latest/user/parsing.html

Modify components of a URI reference using `copy_with()` and reconstruct the URI with `unsplit()`.

```python
print(uri.copy_with(
    authority='username:password@github.com:443',
    path='/sigmavirus24/github3.py',
).unsplit())
```

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

### URIReference Class Methods

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/uri.html

Methods for parsing, manipulating, and querying URIReference objects.

```APIDOC
## URIReference.from_string

### Description
Parses a URI reference from a given unicode URI string.

### Parameters
#### Query Parameters
- **uri_string** (str) - Required - Unicode URI to be parsed into a reference.
- **encoding** (str) - Optional - The encoding of the string provided (default: 'utf-8').

### Response
- **Returns** (URIReference) - A new URIReference object.

---

## URIReference.unsplit

### Description
Reconstitutes the URI components back into a single URI string.

### Response
- **Returns** (str) - The URI Reference as a string.

---

## URIReference.resolve_with

### Description
Resolves a relative URI reference against a base absolute URI.

### Parameters
#### Query Parameters
- **base_uri** (str/URIReference) - Required - An absolute URI used to resolve the relative reference.
- **strict** (bool) - Optional - Whether to use strict resolution.

### Response
- **Returns** (URIReference) - A new resolved URIReference object.

---

## URIReference.normalize

### Description
Normalizes the URI reference according to RFC 3986 Section 6.2.2.

### Response
- **Returns** (URIReference) - A new normalized URIReference object.

---

## URIReference.authority_info

### Description
Parses the authority component into its sub-components: userinfo, host, and port.

### Response
- **Returns** (dict) - A dictionary containing 'userinfo', 'host', and 'port'.
```

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

### urlparse

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/api.html

Parses a given URI and returns a ParseResult object. This function is a partial replacement for the standard library's urlparse.

```APIDOC
## urlparse

### Description
Parses a given URI and return a ParseResult.
This is a partial replacement of the standard library’s urlparse function.

### Method
POST

### Endpoint
/websites/rfc3986_readthedocs_io_en/api/urlparse

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **uri** (str) - Required - The URI to be parsed.
- **encoding** (str) - Optional - The encoding of the string provided.

### Request Example
{
  "uri": "http://example.com/path?query=value#fragment",
  "encoding": "utf-8"
}

### Response
#### Success Response (200)
- **ParseResult** (object) - A parsed URI object with attributes like scheme, netloc, path, params, query, and fragment.

#### Response Example
{
  "scheme": "http",
  "netloc": "example.com",
  "path": "/path",
  "params": "",
  "query": "query=value",
  "fragment": "fragment"
}
```

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

### URIReference.is_valid

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/uri.html

Determines if the entire URI is valid based on specified component requirements. Deprecated since version 1.1.0.

```APIDOC
## URIReference.is_valid

### Description
Determine if the URI is valid.
Deprecated since version 1.1.0: Use the `Validator` object instead.

### Method
(Implicitly a method of URIReference class, likely called on an instance)

### Parameters
#### Query Parameters
- **require_scheme** (bool) - Optional - Set to `True` if you wish to require the presence of the scheme component.
- **require_authority** (bool) - Optional - Set to `True` if you wish to require the presence of the authority component.
- **require_path** (bool) - Optional - Set to `True` if you wish to require the presence of the path component.
- **require_query** (bool) - Optional - Set to `True` if you wish to require the presence of the query component.
- **require_fragment** (bool) - Optional - Set to `True` if you wish to require the presence of the fragment component.

### Response
#### Success Response (200)
- **return_value** (bool) - `True` if the URI is valid. `False` otherwise.

### Response Example
```json
true
```
```

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

### Extend Path in URI Builder

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Extends the existing path with a new path segment. Handles trailing slashes appropriately to ensure correct path concatenation.

```python
>>> URIBuilder(path="/users").extend_path("/sigmavirus24")
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path='/users/sigmavirus24', query=None, fragment=None)
```

```python
>>> URIBuilder(path="/users/").extend_path("/sigmavirus24")
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path='/users/sigmavirus24', query=None, fragment=None)
```

```python
>>> URIBuilder(path="/users/").extend_path("sigmavirus24")
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path='/users/sigmavirus24', query=None, fragment=None)
```

```python
>>> URIBuilder(path="/users").extend_path("sigmavirus24")
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path='/users/sigmavirus24', query=None, fragment=None)
```

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

### Add a fragment to a URI

Source: https://rfc3986.readthedocs.io/en/latest/user/building.html

Use add_fragment to append a fragment identifier to a URI, allowing direct linking to specific sections of a resource.

```python
from rfc3986 import builder
print(builder.URIBuilder().add_scheme(
    'https'
).add_host(
    'tools.ietf.org'
).add_path(
    '/html/rfc3986'
).add_fragment(
    'section-3.5'
).finalize().unsplit())
```

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

### Remove a component from a URI

Source: https://rfc3986.readthedocs.io/en/latest/user/parsing.html

Remove a specific component from a URI by passing `None` to the `copy_with()` method. This works for both URI References and Parse Results.

```python
print(uri.copy_with(path=None).unsplit())
```

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

### normalize_uri

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/api.html

Normalizes the given URI. This is a convenience function.

```APIDOC
## normalize_uri

### Description
Normalize the given URI.
This is a convenience function. You could use either `uri_reference(uri).normalize().unsplit()` or `URIReference.from_string(uri).normalize().unsplit()` instead.

### Method
POST

### Endpoint
/websites/rfc3986_readthedocs_io_en/api/normalize_uri

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **uri** (str) - Required - The URI to be normalized.
- **encoding** (str) - Optional - The encoding of the string provided.

### Request Example
{
  "uri": "HTTP://Example.com/path/.././to/resource",
  "encoding": "utf-8"
}

### Response
#### Success Response (200)
- **str** - The normalized URI string.

#### Response Example
{
  "normalized_uri": "http://example.com/to/resource"
}
```

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

### URIReference.path_is_valid

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/uri.html

Determines if the path component of the URI is valid. Deprecated since version 1.1.0.

```APIDOC
## URIReference.path_is_valid

### Description
Determine if the path component is valid.
Deprecated since version 1.1.0: Use the `Validator` object instead.

### Method
(Implicitly a method of URIReference class, likely called on an instance)

### Parameters
#### Query Parameters
- **require** (bool) - Optional - Set to `True` to require the presence of this component.

### Response
#### Success Response (200)
- **return_value** (bool) - `True` if the path is valid. `False` otherwise.

### Response Example
```json
true
```
```

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

### Add Fragment to URI Builder

Source: https://rfc3986.readthedocs.io/en/latest/api-ref/builder.html

Adds a fragment identifier to the URI. This is typically used to point to a specific section of a resource.

```python
>>> URIBuilder().add_fragment('section-2.6.1')
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path=None, query=None, fragment='section-2.6.1')
```
Tokens:
Raw