urlkit

Name	urlkit JSON
Version	0.2.2 JSON
	download
home_page	None
Summary	Working with URLs using urllib is a bit of a pain. urlkit makes everything much easier.
upload_time	2024-09-30 17:31:31
maintainer	None
docs_url	None
author	Dale Myers
requires_python	<4.0,>=3.9
license	MIT
keywords
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # urlkit

Working with URLs in Python sucks. Until now.

Previously, the way to work with URLs was with `urllib`. This was always difficult to remember, and very verbose. For example, let's take a URL and change one of the query parameters:

```python
from urllib.parse import urlparse, parse_qs, urlencode, urlunparse

url_string = "http://example.com/?foo=bar&baz=qux"
# Parse the URL into components
parsed_url = urlparse(url_string)

# Parse the query string into a dictionary
query_params = parse_qs(parsed_url.query)

# Modify the specified query parameter
query_params[param] = [new_value]

# Reconstruct the query string
new_query = urlencode(query_params, doseq=True)

# Rebuild the URL with the updated query string
new_url = urlunparse((
    parsed_url.scheme,     # Scheme (e.g., http)
    parsed_url.netloc,     # Network location (e.g., example.com)
    parsed_url.path,       # Path (e.g., /)
    parsed_url.params,     # Parameters (if any)
    new_query,             # New query string
    parsed_url.fragment    # Fragment (if any)
))
```

Now with `urlkit`:

```python
from urlkit.http_url import HttpUrl

url_string = "http://example.com/?foo=bar&baz=qux"
# Parse the URL
url = HttpUrl.parse(url_string)

# Set the parameter
url.query["foo"] = "Hello"

# Generate the new URL
new_url = str(url)
```

The goal for `urlkit` is for everything to be simpler and easier.

## URL Type Support

The types in the table are intended to have eventual functionality. It shows which are currently supported.

| Type   | Supported | Notes                                                                                                                 |
| ------ | --------- | --------------------------------------------------------------------------------------------------------------------- |
| HTTP   | ✅        | More or less complete support following [RFC 1738](https://datatracker.ietf.org/doc/html/rfc1738) as far as possible. |
| HTTPS  | ✅        | More or less complete support following [RFC 1738](https://datatracker.ietf.org/doc/html/rfc1738) as far as possible. |
| FTP    | ❌        |                                                                                                                       |
| File   | ❌        |                                                                                                                       |
| Mailto | ❌        |                                                                                                                       |
| Telnet | ❌        |                                                                                                                       |

## Example Usage:

#### Constructing URLs

```python
url = HttpUrl(scheme="http", host="example.com", port=12345, query={"search_text": "Hello World"})
str(url) # http://example.com:12345/?search_text=Hello%20World

url = HttpUrl(scheme="http", host="example.com", query={"search_text": "Hello World"}, query_options=QueryOptions(space_encoding=SpaceEncoding.PLUS))
str(url) # http://example.com:12345/?search_text=Hello+World

url = HttpUrl(scheme="http", host="example.com", query="some%20pre-encoded%20text")
str(url) # http://example.com/?some%20pre-encoded%20text
```

#### Parsing URLs

```python
# Parsing a HTTP(s) URL:
http_url = HttpUrl.parse("http://username:password@example.com/search?description=Some%20Text")
http_url.path # /search
http_url.query # {"description": "Some Text"}
http_url.password # password
```

#### Modifying URLs

```python
url = HttpUrl.parse("http://example.com/foo/bar") # http://example.com/foo/bar
url.path.append("baz") # http://example.com/foo/bar/baz
url.path.append("one/two") # http://example.com/foo/bar/baz/one/two
url.path.pop_last() # http://example.com/foo/bar/baz/one
url.path.pop_last() # http://example.com/foo/bar/baz
url.path.pop_last() # http://example.com/foo/bar
url.path.append(["baz", "one", "two"]) # http://example.com/foo/bar/baz/one/two
```

## Explicitly Non-Supported Features

#### Multiple Query Parameters With Same Key

URLs are old. They have a _lot_ of cruft, and it can make them difficult to work with. For example, many implementations, such as `urllib`, allow a query parameter to appear multiple times. So if you were to use the url `http://example.com/?param=1&param=2` and then tried to get the result for `param` you would get a list back: `["1", "2"]`. This can be nice. The downside though is that it means that every time you query for a parameter, even though they almost always appear just once, you get a list. i.e. `https://example.com/?param=1` returns `["1"]`.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "urlkit",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4.0,>=3.9",
    "maintainer_email": null,
    "keywords": null,
    "author": "Dale Myers",
    "author_email": "dale@myers.io",
    "download_url": "https://files.pythonhosted.org/packages/48/be/5a62eca908a94e39033f414af73ae8267d5ca1b4da873adedca36604176f/urlkit-0.2.2.tar.gz",
    "platform": null,
    "description": "# urlkit\n\nWorking with URLs in Python sucks. Until now.\n\nPreviously, the way to work with URLs was with `urllib`. This was always difficult to remember, and very verbose. For example, let's take a URL and change one of the query parameters:\n\n```python\nfrom urllib.parse import urlparse, parse_qs, urlencode, urlunparse\n\nurl_string = \"http://example.com/?foo=bar&baz=qux\"\n# Parse the URL into components\nparsed_url = urlparse(url_string)\n\n# Parse the query string into a dictionary\nquery_params = parse_qs(parsed_url.query)\n\n# Modify the specified query parameter\nquery_params[param] = [new_value]\n\n# Reconstruct the query string\nnew_query = urlencode(query_params, doseq=True)\n\n# Rebuild the URL with the updated query string\nnew_url = urlunparse((\n    parsed_url.scheme,     # Scheme (e.g., http)\n    parsed_url.netloc,     # Network location (e.g., example.com)\n    parsed_url.path,       # Path (e.g., /)\n    parsed_url.params,     # Parameters (if any)\n    new_query,             # New query string\n    parsed_url.fragment    # Fragment (if any)\n))\n```\n\nNow with `urlkit`:\n\n```python\nfrom urlkit.http_url import HttpUrl\n\nurl_string = \"http://example.com/?foo=bar&baz=qux\"\n# Parse the URL\nurl = HttpUrl.parse(url_string)\n\n# Set the parameter\nurl.query[\"foo\"] = \"Hello\"\n\n# Generate the new URL\nnew_url = str(url)\n```\n\nThe goal for `urlkit` is for everything to be simpler and easier.\n\n## URL Type Support\n\nThe types in the table are intended to have eventual functionality. It shows which are currently supported.\n\n| Type   | Supported | Notes                                                                                                                 |\n| ------ | --------- | --------------------------------------------------------------------------------------------------------------------- |\n| HTTP   | \u2705        | More or less complete support following [RFC 1738](https://datatracker.ietf.org/doc/html/rfc1738) as far as possible. |\n| HTTPS  | \u2705        | More or less complete support following [RFC 1738](https://datatracker.ietf.org/doc/html/rfc1738) as far as possible. |\n| FTP    | \u274c        |                                                                                                                       |\n| File   | \u274c        |                                                                                                                       |\n| Mailto | \u274c        |                                                                                                                       |\n| Telnet | \u274c        |                                                                                                                       |\n\n## Example Usage:\n\n#### Constructing URLs\n\n```python\nurl = HttpUrl(scheme=\"http\", host=\"example.com\", port=12345, query={\"search_text\": \"Hello World\"})\nstr(url) # http://example.com:12345/?search_text=Hello%20World\n\nurl = HttpUrl(scheme=\"http\", host=\"example.com\", query={\"search_text\": \"Hello World\"}, query_options=QueryOptions(space_encoding=SpaceEncoding.PLUS))\nstr(url) # http://example.com:12345/?search_text=Hello+World\n\nurl = HttpUrl(scheme=\"http\", host=\"example.com\", query=\"some%20pre-encoded%20text\")\nstr(url) # http://example.com/?some%20pre-encoded%20text\n```\n\n#### Parsing URLs\n\n```python\n# Parsing a HTTP(s) URL:\nhttp_url = HttpUrl.parse(\"http://username:password@example.com/search?description=Some%20Text\")\nhttp_url.path # /search\nhttp_url.query # {\"description\": \"Some Text\"}\nhttp_url.password # password\n```\n\n#### Modifying URLs\n\n```python\nurl = HttpUrl.parse(\"http://example.com/foo/bar\") # http://example.com/foo/bar\nurl.path.append(\"baz\") # http://example.com/foo/bar/baz\nurl.path.append(\"one/two\") # http://example.com/foo/bar/baz/one/two\nurl.path.pop_last() # http://example.com/foo/bar/baz/one\nurl.path.pop_last() # http://example.com/foo/bar/baz\nurl.path.pop_last() # http://example.com/foo/bar\nurl.path.append([\"baz\", \"one\", \"two\"]) # http://example.com/foo/bar/baz/one/two\n```\n\n## Explicitly Non-Supported Features\n\n#### Multiple Query Parameters With Same Key\n\nURLs are old. They have a _lot_ of cruft, and it can make them difficult to work with. For example, many implementations, such as `urllib`, allow a query parameter to appear multiple times. So if you were to use the url `http://example.com/?param=1&param=2` and then tried to get the result for `param` you would get a list back: `[\"1\", \"2\"]`. This can be nice. The downside though is that it means that every time you query for a parameter, even though they almost always appear just once, you get a list. i.e. `https://example.com/?param=1` returns `[\"1\"]`.\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Working with URLs using urllib is a bit of a pain. urlkit makes everything much easier.",
    "version": "0.2.2",
    "project_urls": null,
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "080df30fe98055edb1bc75d6058a8d8c94a80b80321730b6354e0e0784ff5976",
                "md5": "eaf20afe39d50b03d2cb4f3a25d9235e",
                "sha256": "e101d74d07309f8948e10924cfaaf167129b362093a05422040ac6effe434229"
            },
            "downloads": -1,
            "filename": "urlkit-0.2.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "eaf20afe39d50b03d2cb4f3a25d9235e",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0,>=3.9",
            "size": 11217,
            "upload_time": "2024-09-30T17:31:29",
            "upload_time_iso_8601": "2024-09-30T17:31:29.591413Z",
            "url": "https://files.pythonhosted.org/packages/08/0d/f30fe98055edb1bc75d6058a8d8c94a80b80321730b6354e0e0784ff5976/urlkit-0.2.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "48be5a62eca908a94e39033f414af73ae8267d5ca1b4da873adedca36604176f",
                "md5": "a3cf5f966de62e445ed09feba394ede6",
                "sha256": "30274c1b2e9b95edb0043dcb7ce4dec67c79ec9fb42c141ccfaa32717d304ed0"
            },
            "downloads": -1,
            "filename": "urlkit-0.2.2.tar.gz",
            "has_sig": false,
            "md5_digest": "a3cf5f966de62e445ed09feba394ede6",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0,>=3.9",
            "size": 10831,
            "upload_time": "2024-09-30T17:31:31",
            "upload_time_iso_8601": "2024-09-30T17:31:31.487243Z",
            "url": "https://files.pythonhosted.org/packages/48/be/5a62eca908a94e39033f414af73ae8267d5ca1b4da873adedca36604176f/urlkit-0.2.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-09-30 17:31:31",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "urlkit"
}