www

Internet-related functions.

deltona.www.BookmarksDataset

Bookmark top structure.

alias of list[BookmarksHTMLFolder | BookmarksHTMLLink]

class deltona.www.BookmarksHTMLAnchorAttributes

Bases: TypedDict

Attributes of a bookmark link.

add_date : str

Date the bookmark was added.

href : str

URL of the bookmark.

icon : NotRequired[str]

Icon data URI.

class deltona.www.BookmarksHTMLFolder

Bases: TypedDict

A bookmark folder.

attrs : BookmarksHTMLFolderAttributes

Folder attributes.

children : list[BookmarksHTMLLink | BookmarksHTMLFolder]

Child items.

name : str

Folder name.

type : Literal['folder']

Type discriminator.

class deltona.www.BookmarksHTMLFolderAttributes

Bases: TypedDict

Attributes of a bookmark folder.

add_date : str

Date the folder was added.

last_modified : str

Date the folder was last modified.

personal_toolbar_folder : NotRequired[Literal['true']]

Whether this is the personal toolbar folder.

Bases: TypedDict

A bookmark link.

attrs : BookmarksHTMLAnchorAttributes

Link attributes.

title : str

Link title.

type : Literal['link']

Type discriminator.

deltona.www.RecurseBookmarksHTMLCallback

Callback for recurse_bookmarks_html() to call for each link.

alias of Callable[[BookmarksHTMLAnchorAttributes, str, Sequence[tuple[str, BookmarksHTMLFolderAttributes]]], None]

async deltona.www.check_bookmarks_html_urls(html_content: str) → tuple[list[BookmarksHTMLFolder | BookmarksHTMLLink], list[BookmarksHTMLFolder | BookmarksHTMLLink], list[BookmarksHTMLFolder | BookmarksHTMLLink]]

Check a browser’s exported bookmarks.html URLs.

Checks for URLs that are not valid any more (status 404) or have changed (statuses 301 and 302). URLs are checked concurrently.

Parameters:
html_content : str

Raw HTML string of the bookmarks file.

Returns:

A tuple of (all_data, changed, not_found) bookmark datasets.

Return type:

tuple[BookmarksDataset, BookmarksDataset, BookmarksDataset]

deltona.www.generate_html_dir_tree(start_dir: StrPath, *, follow_symlinks: bool = False, depth: int = 2) → str

Generate an HTML directory listing.

Parameters:
start_dir : StrPath

Root directory for the listing.

If True, follow symbolic links.

depth : int

Maximum recursion depth.

Returns:

Complete HTML document string.

Return type:

str

deltona.www.parse_bookmarks_html(html_content: str) → list[BookmarksHTMLFolder | BookmarksHTMLLink]

Parse a browser’s exported bookmarks.html.

Parameters:
html_content : str

Raw HTML string.

Returns:

Parsed bookmark tree.

Return type:

BookmarksDataset

deltona.www.recurse_bookmarks_html(soup: Tag, callback: RecurseBookmarksHTMLCallback) → None

Traverse the bookmarks.html tree and call the callback for each link.

Parameters:
soup : Tag

Parsed HTML tag to traverse.

callback : RecurseBookmarksHTMLCallback

Function called for each link found.

async deltona.www.upload_to_imgbb(path: StrPath, *, api_key: str | None = None, keyring_username: str | None = None, http_timeout: float = 5) → Response

Upload an image to ImgBB.

Get an API key at https://api.imgbb.com/ and set it with keyring set imgbb keyring_username.

Parameters:
path : StrPath

Path to the image file.

api_key : str | None

API key. If None, the key is retrieved from the keyring.

keyring_username : str | None

Username for the keyring lookup. Defaults to the current user.

http_timeout : float

HTTP timeout in seconds.

Returns:

The response from the ImgBB API.

Return type:

Response

deltona.www.where_from(file: FileDescriptorOrPath, *, webpage: bool = False) → str | None

Determine where a file came from based on metadata in extended attributes.

Parameters:
file : FileDescriptorOrPath

File to inspect.

webpage : bool

If True, return the webpage URL instead of the direct download URL (macOS only).

Returns:

The URL the file was downloaded from, or None if not available.

Return type:

str | None