buku module

class buku.BookmarkVar(id: int, url: str, title: str | None = None, tags_raw: str = '', desc: str = '', flags: int = 0)[source]

Bases: NamedTuple

Bookmark data named tuple

desc: str

Alias for field number 4

flags: int

Alias for field number 5

id: int

Alias for field number 0

property immutable: bool
property netloc: str
property taglist: List[str]
property tags: str
tags_raw: str

Alias for field number 3

title: str | None

Alias for field number 2

url: str

Alias for field number 1

class buku.BukuCrypt(iterations=8, dbfile=None, encfile=None, password=None, replace=True)[source]

Bases: object

Class to handle encryption and decryption of the database file. Functionally a separate entity.

Involves late imports in the static functions but it saves ~100ms each time. Given that encrypt/decrypt are not done automatically and any one should be called at a time, this doesn’t seem to be an outrageous approach.

BLOCKSIZE = 65536
CHUNKSIZE = 524288
SALT_SIZE = 32
static decrypt_file(iterations=8, dbfile=None, encfile=None, password=None, replace=True)[source]

Decrypt the bookmarks database file.

Parameters:

  • iterations (int) – Number of iterations for key generation. (Defaults to 8)

  • dbfile (str, optional) – Custom database file path (including filename). The ‘.enc’ suffix must be omitted.

  • encfile (str, optional) – Encoded dbfile. (Defaults to dbfile + ‘.enc’)

  • password (str, optional) – Password to use (if not provided, will be prompted from the user).

  • replace (bool) – If True (default), the original file will be removed on success.

static encrypt_file(iterations=8, dbfile=None, encfile=None, password=None, replace=True)[source]

Encrypt the bookmarks database file.

Parameters:

  • iterations (int) – Number of iterations for key generation. (Defaults to 8)

  • dbfile (str, optional) – Custom database file path (including filename). Fallback value is the default DB.

  • encfile (str, optional) – Encoded dbfile. (Defaults to dbfile + ‘.enc’)

  • password (str, optional) – Password to use (if not provided, will be prompted from the user).

  • replace (bool) – If True (default), the original file will be removed on success.

static get_filehash(filepath)[source]

Get the SHA256 hash of a file.

Parameters:

filepath (str) – Path to the file.

Returns:

hash – Hash digest of file.

Return type:

bytes

class buku.BukuDb(json: str | None = None, field_filter: int = 0, chatty: bool = False, dbfile: str | None = None, colorize: bool = True, default_scheme: str = 'http')[source]

Bases: object

Abstracts all database operations.

conn
Type:

sqlite database connection.

cur
Type:

sqlite database cursor.

json

Empty string if results should be printed in JSON format to stdout. Nonempty string if results should be printed in JSON format to file. The string has to be a valid path. None if the results should be printed as human-readable plaintext.

Type:

string

field_filter

Indicates format for displaying bookmarks. Default is 0.

Type:

int

chatty

Sets the verbosity of the APIs. Default is False.

Type:

bool

add_rec(url: str, title_in: str | None = None, tags_in: str | None = None, desc: str | None = None, immutable: bool = False, delay_commit: bool = False, fetch: bool = True, url_redirect: bool = False, tag_redirect: bool | str = False, tag_error: bool | str = False, del_error: Set[int] | range | None = None, tags_fetch: bool = True, tags_except: str | None = None) → int[source]

Add a new bookmark.

Parameters:

  • url (str) – URL to bookmark.

  • title_in (str, optional) – Title to add manually. Default is None.

  • tags_in (str, optional) – Comma-separated tags to add manually, instead of fetching them. Default is None.

  • tags_except (str, optional) – These are removed from the resulting tags list. Default is None.

  • tags_fetch (bool) – True if tags parsed from the fetched page should be included. Default is True.

  • desc (str, optional) – Description of the bookmark. Default is None.

  • immutable (bool) – Indicates whether to disable title fetch from web. Default is False.

  • delay_commit (bool) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.

  • fetch (bool) – Fetch page from web and parse for data. Required fetch-status params to take effect.

  • url_redirect (bool) – Bookmark the URL produced after following all PERMANENT redirects.

  • tag_redirect (bool | str) – Adds a tag by the given pattern if the url resolved to a PERMANENT redirect. (True means the default pattern ‘http:{}’.)

  • tag_error (bool | str) – Adds a tag by the given pattern if the url resolved to a HTTP error. (True means the default pattern ‘http:{}’.)

  • del_error (int{} | range, optional) – Do not add the bookmark if HTTP response status is in the given set or range. Also prevents the bookmark from being added on a network error.

Returns:

DB index of new bookmark on success, None on failure.

Return type:

int

append_tag_at_index(index, tags_in, delay_commit=False)[source]

Append tags to bookmark tagset at index.

Parameters:

  • index (int | int[] | int{} | range, optional) – DB index of the record. 0 or empty indicates all records.

  • tags_in (str) – Comma-separated tags to add manually.

  • delay_commit (bool) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.

Returns:

True on success, False on failure.

Return type:

bool

auto_import_from_browser(firefox_profile=None)[source]

Import bookmarks from a browser default database file.

Supports Firefox, Google Chrome, Chromium, Vivaldi, Brave, and MS Edge.

Returns:

True on success, False on failure.

Return type:

bool

browse_by_index(index=0, low=0, high=0, is_range=False)[source]

Open URL at index or range of indices in browser.

Parameters:

  • index (int) – Index to browse. 0 opens a random bookmark.

  • low (int) – Actual lower index of range.

  • high (int) – Higher index of range.

  • is_range (bool) – A range is passed using low and high arguments. If True, index is ignored. Default is False.

Returns:

True on success, False on failure.

Return type:

bool

browse_cached_url(arg)[source]

Open URL at index or URL.

Parameters:

arg (str) – Index or url to browse

Returns:

Wayback Machine URL, None if not cached

Return type:

str

cleardb(confirm=True)[source]

Drops the bookmark table if it exists.

Parameters:

confirm (bool) – False if confirmation prompt is required. Default is True.

Returns:

True on success, False on failure.

Return type:

bool

close()[source]

Close a DB connection.

close_quit(exitval=0)[source]

Close a DB connection and exit.

Parameters:

exitval (int) – Program exit value.

commit_delete(apply: bool = True, retain_order: bool = False)[source]

Commit delayed delete commands.

compactdb(index: int, delay_commit: bool = False, upto: int | None = None, retain_order: bool = False)[source]

When an entry at index is deleted, move the last entry in DB to index, if index is lesser.

Parameters:

  • index (int) – DB index of deleted entry.

  • delay_commit (bool) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.

  • upto (int, optional) – If specified, multiple indices are moved at once.

  • retain_order (bool) – Shift indices of multiple records by 1 instead of replacing the deleted record with the last one. Default is False.

property dbfile: str
property dbname: str
delete_rec(index: int = None, low: int = 0, high: int = 0, is_range: bool = False, delay_commit: bool = False, chatty: bool | None = None, retain_order: bool = False) → bool[source]

Delete a single record or remove the table if index is 0.

Parameters:

  • index (int, optional) – DB index of deleted entry.

  • low (int) – Actual lower index of range.

  • high (int) – Actual higher index of range.

  • is_range (bool) – A range is passed using low and high arguments. An index is ignored if is_range is True.

  • delay_commit (bool) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.

  • chatty (Optional[bool]) – Override for self.chatty

  • retain_order (bool) – Shift indices of multiple records instead of replacing the deleted record with the last one. Default is False.

Raises:

TypeError – If any of index, low, or high variable is not integer.

Returns:

True on success, False on failure.

Return type:

bool

Examples

>>> from tempfile import NamedTemporaryFile
>>> import buku
>>> sdb = buku.BukuDb(dbfile=NamedTemporaryFile().name)  # single record database
>>> sdb.add_rec('https://example.com')
1
>>> sdb.delete_rec(1)
Index 1 deleted
True

Delete record with default range.

>>> sdb = buku.BukuDb(dbfile=NamedTemporaryFile().name)
>>> sdb.add_rec('https://example.com')
1
>>> sdb.delete_rec(is_range=True)
Remove ALL bookmarks? (y/n): y
All bookmarks deleted
True

Running the function without any parameter will raise TypeError.

>>> sdb = buku.BukuDb(dbfile=NamedTemporaryFile().name)
>>> sdb.add_rec('https://example.com')
1
>>> sdb.delete_rec()
Traceback (most recent call last):
...
TypeError: index, low, or high variable is not integer

Negative number on high and low parameters when is_range is True will log error and return False

>>> edb = buku.BukuDb(dbfile=NamedTemporaryFile().name)
>>> edb.delete_rec(low=-1, high=-1, is_range=True)
False

Remove the table

>>> sdb = buku.BukuDb(dbfile=NamedTemporaryFile().name)
>>> sdb.delete_rec(0)
Remove ALL bookmarks? (y/n): y
All bookmarks deleted
True
delete_rec_all(delay_commit=False)[source]

Removes all records in the Bookmarks table.

Parameters:

delay_commit (bool) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.

Returns:

True on success, False on failure.

Return type:

bool

delete_resultset(results, retain_order=False)[source]

Delete search results in descending order of DB index.

Indices are expected to be unique and in ascending order.

Notes

This API forces a delayed commit.

Parameters:

  • results (list of tuples) – List of results to delete from DB.

  • retain_order (bool) – Shift indices of multiple records instead of replacing the deleted record with the last one. Default is False.

Returns:

True on success, False on failure.

Return type:

bool

delete_tag_at_index(index, tags_in, delay_commit=False, chatty=True)[source]

Delete tags from bookmark tagset at index.

Parameters:

  • index (int | int[] | int{} | range, optional) – DB index of bookmark record. 0 or empty indicates all records.

  • tags_in (str) – Comma-separated tags to delete manually.

  • delay_commit (bool) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.

  • chatty (bool) – Skip confirmation when set to False.

Returns:

True on success, False on failure.

Return type:

bool

edit_update_rec(index, immutable=None)[source]

Edit in editor and update a record.

Parameters:

  • index (int) – DB index of the record. Last record, if index is -1.

  • immutable (bool, optional) – Disable title fetch from web if True. Default is None (no change).

Returns:

True if updated, else False.

Return type:

bool

Excludes records that match keyword search using without parameters

Parameters:

  • search_results (list) – List of search results.

  • without (list of str) – Keywords to exclude. If empty, returning search_results unchanged.

  • deep (bool) – True to search for matching substrings. Default is False.

  • markers (bool) – True to use prefix markers for different fields. Default is False.

Returns:

List of search results.

Return type:

list

exportdb(filepath: str, resultset: List[BookmarkVar] | None = None, order: List[str] = ['id'], pick: int | None = None) → bool[source]

Export DB bookmarks to file. Exports full DB, if resultset is None. Additionally, if run after a (batch) update with export_on, only export those records.

If destination file name ends with ‘.db’, bookmarks are exported to a buku database file. If destination file name ends with ‘.md’, bookmarks are exported to a Markdown file. If destination file name ends with ‘.org’ bookmarks are exported to an org file. If destination file name ends with ‘.xbel’ bookmarks are exported to a XBEL file. If destination file name ends with ‘.rss’/’.atom’ bookmarks are exported to an RSS file. Otherwise, bookmarks are exported to a Firefox bookmarks.html formatted file.

Parameters:

  • filepath (str) – Path to export destination file.

  • resultset (list of tuples) – List of results to export. Use None to get current DB. Ignored if run after a (batch) update with export_on.

  • order (list of str) – Order description (fields from JSON export or DB, prepended with ‘+’/’-’ for ASC/DESC).

  • pick (int, optional) – Reduce the export to a random subset of up to given (positive) size. Default is None.

Returns:

True on success, False on failure.

Return type:

bool

fixtags()[source]

Undocumented API to fix tags set in earlier versions.

Functionalities:

  1. Remove duplicate tags

  2. Sort tags

  3. Use lower case to store tags

static get_default_dbdir()[source]

Determine the directory path where dbfile will be stored.

If $BUKU_DEFAULT_DBDIR is specified, use it else if $XDG_DATA_HOME is defined, use $XDG_DATA_HOME/buku else if $HOME exists, use $HOME/.local/share/buku else if the platform is Windows and %APPDATA% exists, use %APPDATA%buku else use the current directory.

Returns:

Path to database file.

Return type:

str

get_max_id(*, lock: bool = True) → int[source]

Fetch the ID of the last record.

Parameters:

lock (bool) – Whether to restrict concurrent access (True by default).

Returns:

ID of the record if any record exists, else None.

Return type:

int

get_rec_all(*, lock: bool = True, order: List[str] = ['id'], ignore_case: bool = True)[source]

Get all the bookmarks in the database.

Parameters:

  • lock (bool) – Whether to restrict concurrent access (True by default).

  • order (list of str) – Order description (fields from JSON export or DB, prepended with ‘+’/’-’ for ASC/DESC).

  • ignore_case (bool) – Whether to ignore case when applying order (True by default).

Returns:

A list of tuples representing bookmark records.

Return type:

list

get_rec_all_by_ids(indices: Sequence[int] | Set[int] | range, *, lock: bool = True, order: List[str] = ['id'])[source]

Get all the bookmarks in the database.

Parameters:

  • indices (int[] | int{} | range) – DB indices of bookmark records.

  • lock (bool) – Whether to restrict concurrent access (True by default).

  • order (list of str) – Order description (fields from JSON export or DB, prepended with ‘+’/’-’ for ASC/DESC).

Returns:

A list of tuples representing bookmark records.

Return type:

list

get_rec_by_id(index: int, *, lock: bool = True) → BookmarkVar | None[source]

Get a bookmark from database by its ID.

Parameters:

  • index (int) – DB index of bookmark record.

  • lock (bool) – Whether to restrict concurrent access (True by default).

Returns:

Bookmark data, or None if index is not found.

Return type:

BookmarkVar or None

get_rec_id(url: str, *, lock: bool = True)[source]

Check if URL already exists in DB.

Parameters:

  • url (str) – A URL to search for in the DB.

  • lock (bool) – Whether to restrict concurrent access (True by default).

Returns:

DB index, or None if URL not found in DB.

Return type:

int

get_rec_ids(urls: Sequence[str] | Set[str], *, lock: bool = True)[source]

Check if URL already exists in DB.

Parameters:

  • urls (str[] | str{}) – URLs to search for in the DB.

  • lock (bool) – Whether to restrict concurrent access (True by default).

Returns:

A list of DB indices.

Return type:

list

get_tag_all()[source]

Get list of tags in DB.

Returns:

(list of unique tags sorted alphabetically,

dictionary of {tag: usage_count}).

Return type:

tuple

get_tagstr_from_taglist(id_list, taglist)[source]

Get a string of delimiter-separated (and enclosed) string of tags from a dictionary of tags by matching ids.

The inputs are the outputs from BukuDb.get_tag_all().

Parameters:

  • id_list (list) – List of ids.

  • taglist (list) – List of tags.

Returns:

Delimiter separated and enclosed list of tags.

Return type:

str

importdb(filepath, tacit=False)[source]

Import bookmarks from an HTML or a Markdown file.

Supports Firefox, Google Chrome, and IE exported HTML bookmarks. Supports XBEL standard bookmarks. Supports RSS files with extension ‘.rss’, ‘.atom’. Supports Markdown files with extension ‘.md’, ‘.org’. Supports importing bookmarks from another buku database file.

Parameters:

  • filepath (str) – Path to file to import.

  • tacit (bool) – If True, no questions asked and folder names are automatically imported as tags from bookmarks HTML. If True, automatic timestamp tag is NOT added. Default is False.

Returns:

True on success, False on failure.

Return type:

bool

static initdb(dbfile: str | None = None, chatty: bool = False) → Tuple[Connection, Cursor][source]

Initialize the database connection.

Create DB file and/or bookmarks table if they don’t exist. Alert on encryption options on first execution.

Parameters:

  • dbfile (str, optional) – Custom database file path (including filename).

  • chatty (bool) – If True, shows informative message on DB creation.

Returns:

(connection, cursor).

Return type:

tuple

list_using_id(ids=[], order=['+id'])[source]

List entries in the DB using the specified id list.

Parameters:

  • ids (list of ids/ranges in string form)

  • order (list of strings) – Order description (fields from JSON export or DB, prepended with ‘+’/’-’ for ASC/DESC).

Return type:

list

load_chrome_database(path, unique_tag, add_parent_folder_as_tag)[source]

Open Chrome Bookmarks JSON file and import data.

Parameters:

  • path (str) – Path to Google Chrome bookmarks file.

  • unique_tag (str) – Timestamp tag in YYYYMonDD format.

  • add_parent_folder_as_tag (bool) – True if bookmark parent folders should be added as tags else False.

load_edge_database(path, unique_tag, add_parent_folder_as_tag)[source]

Open Edge Bookmarks JSON file and import data.

Parameters:

  • path (str) – Path to Microsoft Edge bookmarks file.

  • unique_tag (str) – Timestamp tag in YYYYMonDD format.

  • add_parent_folder_as_tag (bool) – True if bookmark parent folders should be added as tags else False.

load_firefox_database(path, unique_tag, add_parent_folder_as_tag)[source]

Connect to Firefox sqlite db and import bookmarks into BukuDb.

Parameters:

  • path (str) – Path to Firefox bookmarks sqlite database.

  • unique_tag (str) – Timestamp tag in YYYYMonDD format.

  • add_parent_folder_as_tag (bool) – True if bookmark parent folders should be added as tags else False.

mergedb(path)[source]

Merge bookmarks from another buku database file.

Parameters:

path (str) – Path to DB file to merge.

Returns:

True on success, False on failure.

Return type:

bool

print_rec(index: int | Sequence[int] | Set[int] | range | None = 0, low: int = 0, high: int = 0, is_range: bool = False, order: List[str] = []) → bool[source]

Print bookmark details at index or all bookmarks if index is 0.

A negative index behaves like tail, if title is blank show “Untitled”.

Empty database check will run when index < 0 and is_range is False.

Parameters:

  • index (int | int[] | int{} | range, optional) – DB index(es) of record(s) to print. 0 or empty prints all records. Negative value prints out last index rows.

  • low (int) – Actual lower index of range.

  • high (int) – Actual higher index of range.

  • is_range (bool) – A range is passed using low and high arguments. An index is ignored if is_range is True.

  • order (list of str) – Order description (fields from JSON export or DB, prepended with ‘+’/’-’ for ASC/DESC).

Returns:

True on success, False on failure.

Return type:

bool

Examples

>>> import buku
>>> from tempfile import NamedTemporaryFile
>>> edb = buku.BukuDb(dbfile=NamedTemporaryFile().name)  # empty database
>>> edb.print_rec()
True

Print negative index on empty database will log error and return False

>>> edb.print_rec(-3)
False

print non empty database with default argument.

>>> sdb = buku.BukuDb(dbfile=NamedTemporaryFile().name)  # single record database
>>> sdb.add_rec('https://example.com')
1
>>> assert sdb.print_rec()
1. Example Domain
   > https://example.com

Negative number on high and low parameters when is_range is True will log error and return False

>>> sdb.print_rec(low=-1, high=-1, is_range=True)
False
>>> edb.print_rec(low=-1, high=-1, is_range=True)
False
refreshdb(index: int | Sequence[int] | Set[int] | range | None, threads: int, url_redirect: bool = False, tag_redirect: bool | str = False, tag_error: bool | str = False, del_error: Set[int] | range | None = None, export_on: Set[int] | range | None = None, update_title: bool = True, custom_url: str | None = None, custom_tags: str | None = None, delay_delete: bool = False, retain_order: bool = False) → bool[source]

Refresh ALL (or specified) records in the database.

Fetch title for each bookmark from the web and update the records. Doesn’t update the title if fetched title is empty.

Notes

This API doesn’t change DB index, URL or tags of a bookmark. (Unless one or more fetch-status parameters are supplied.) This API is verbose.

Parameters:

  • index (int | int[] | int{} | range, optional) – DB index(es) of record(s) to update. 0 or empty value indicates all records.

  • threads (int) – Number of threads to use to refresh full DB. Default is 4.

  • url_redirect (bool) – Update the URL to one produced after following all PERMANENT redirects. (This could fail if the new URL is bookmarked already.)

  • tag_redirect (bool | str) – Adds a tag by the given pattern if the url resolved to a PERMANENT redirect. (True means the default pattern ‘http:{}’.)

  • tag_error (bool | str) – Adds a tag by the given pattern if the url resolved to a HTTP error. (True means the default pattern ‘http:{}’.)

  • del_error (int{} | range, optional) – Delete the bookmark if HTTP response status is in the given set or range.

  • export_on (int{} | range, optional) – Limit the export to URLs returning one of given HTTP codes; store old URLs.

  • update_title (bool) – Update titles/descriptions. (Can be turned off for network testing.)

  • custom_url (str, optional) – Override URL to fetch. (Use for network testing of a single record before updating it.)

  • custom_tags (str, optional) – Overwrite all tags. (Use to combine network testing with tags overwriting.)

  • delay_delete (bool) – Delay scheduled deletions by del_error. (Use for network testing during update.)

  • retain_order (bool) – If True, bookmark deletion will not result in their order being changed (multiple indices will be updated instead).

Returns:

True on success, False on failure. (Deletion by del_error counts as success.)

Return type:

bool

reorder(order: List[str], *, ignore_case=True)[source]

Change indices of all records in DB to match the specified order.

Parameters:

  • order (list of str) – Order description (fields from JSON export or DB, prepended with ‘+’/’-’ for ASC/DESC).

  • ignore_case (bool) – Whether to ignore case when applying order (True by default).

replace_tag(orig: str, new: List[str] = [])[source]

Replace original tag by new tags in all records.

Remove original tag if new tag is empty.

Parameters:

  • orig (str) – Original tag.

  • new (list) – Replacement tags.

Raises:

  • ValueError – Invalid input(s) provided.:

  • RuntimeError – Tag deletion failed.:

search_by_tag(tags: str | None, order: List[str] = ['+id']) → List[BookmarkVar][source]

Search bookmarks for entries with given tags.

Parameters:

  • tags (str) – String of tags to search for. Retrieves entries matching ANY tag if tags are delimited with ‘,’. Retrieves entries matching ALL tags if tags are delimited with ‘+’.

  • order (list of str) – Order description (fields from JSON export or DB, prepended with ‘+’/’-’ for ASC/DESC). Note: this applies to fields with the same number of matched tags.

Returns:

List of search results.

Return type:

list

search_keywords_and_filter_by_tags(keywords: List[str], all_keywords: bool = False, deep: bool = False, regex: bool = False, stag: List[str] | None = None, without: List[str] | None = None, markers: bool = False, order: List[str] = ['+id']) → List[BookmarkVar][source]

Search bookmarks for entries with keywords and specified criteria while filtering out entries with matching tags.

Parameters:

  • keywords (list of str) – Keywords to search.

  • without (list of str) – Keywords to exclude; ignored if empty. Default is None.

  • all_keywords (bool) – True to return records matching ALL keywords. False to return records matching ANY keyword. (This is the default.)

  • deep (bool) – True to search for matching substrings. Default is False

  • markers (bool) – True to use prefix markers for different fields. Default is False.

  • regex (bool) – Match a regular expression if True. Default is False.

  • stag (list of str) – Strings of tags to search for. Default is None. Retrieves entries matching ANY tag if tags are delimited with ‘,’. Retrieves entries matching ALL tags if tags are delimited with ‘+’.

Returns:

List of search results.

Return type:

list

searchdb(keywords: List[str], all_keywords: bool = False, deep: bool = False, regex: bool = False, markers: bool = False, order: List[str] = ['+id']) → List[BookmarkVar][source]

Search DB for entries where tags, URL, or title fields match keywords.

Parameters:

  • keywords (list of str) – Keywords to search.

  • order (list of str) – Order description (fields from JSON export or DB, prepended with ‘+’/’-’ for ASC/DESC). Note: this applies to fields with the same number of matched keywords.

  • all_keywords (bool) – False (default value) to return records matching ANY keyword. True to return records matching ALL keywords. This also enables special behaviour when keywords in ([‘blank’], [‘immutable’]).

  • deep (bool) – True to search for matching substrings. Default is False.

  • markers (bool) – True to use prefix markers for different fields. Default is False.

  • regex (bool) – Match a regular expression if True. Default is False. Overrides deep, all_keywords, and comma matching in tags with markers.

Returns:

List of search results.

Return type:

list

set_tag(cmdstr, taglist)[source]

Append, overwrite, remove tags using the symbols >>, > and << respectively.

Parameters:

  • cmdstr (str) – Command pattern.

  • taglist (list) – List of tags.

Returns:

Number of indices updated on success, -1 on failure, -2 on no symbol found.

Return type:

int

suggest_similar_tag(tagstr)[source]

Show list of tags those go together in DB.

Parameters:

tagstr (str) – Original tag string.

Returns:

DELIM separated string of tags.

Return type:

str

swap_recs(index1: int, index2: int, *, lock: bool = True, delay_commit: bool = False)[source]

Swaps two records with given indices

Parameters:

  • index1 (int) – Index of the 1st record to be exchanged.

  • index2 (int) – Index of the 2nd record to be exchanged.

  • lock (bool) – Whether to restrict concurrent access (True by default).

  • delay_commit (bool) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.

Returns:

True on success, False on failure.

Return type:

bool

tnyfy_url(index: int | None = None, url: str | None = None, shorten: bool = True) → str | None[source]

Shorten/expand a URL using the tny.im service.

Tny.im is no longer available; don’t use this method.

traverse_bm_folder(sublist, unique_tag, folder_name, add_parent_folder_as_tag)[source]

Traverse bookmark folders recursively and find bookmarks.

Parameters:

  • sublist (list) – List of child entries in bookmark folder.

  • unique_tag (str) – Timestamp tag in YYYYMonDD format.

  • folder_name (str) – Name of the parent folder.

  • add_parent_folder_as_tag (bool) – True if bookmark parent folders should be added as tags else False.

Returns:

Bookmark record data.

Return type:

tuple

update_rec(index: int | Sequence[int] | Set[int] | range | None, url: str | None = None, title_in: str | None = None, tags_in: str | None = None, desc: str | None = None, immutable: bool | None = None, threads: int = 4, url_redirect: bool = False, tag_redirect: bool | str = False, tag_error: bool | str = False, del_error: Set[int] | range | None = None, export_on: Set[int] | range | None = None, retain_order: bool = False) → bool[source]

Update an existing record at (each) index.

Update all records if index is 0 or empty, and url is not specified. URL is an exception because URLs are unique in DB.

Parameters:

  • index (int | int[] | int{} | range, optional) – DB index(es) of record(s). 0 or empty value indicates all records.

  • url (str, optional) – Bookmark address.

  • title_in (str, optional) – Title to add manually.

  • tags_in (str, optional) – Comma-separated tags to add manually. Must start and end with comma. Prefix with ‘+,’ to append to current tags. Prefix with ‘-,’ to delete from current tags.

  • desc (str, optional) – Description of bookmark.

  • immutable (bool, optional) – Disable title fetch from web if True. Default is None (no change).

  • threads (int) – Number of threads to use to refresh full DB. Default is 4.

  • url_redirect (bool) – Update the URL to one produced after following all PERMANENT redirects. (This could fail if the new URL is bookmarked already.)

  • tag_redirect (bool | str) – Adds a tag by the given pattern if the url resolved to a PERMANENT redirect. (True means the default pattern ‘http:{}’.)

  • tag_error (bool | str) – Adds a tag by the given pattern if the url resolved to a HTTP error. (True means the default pattern ‘http:{}’.)

  • del_error (int{} | range, optional) – Delete the bookmark if HTTP response status is in the given set or range. Does NOT cause deletion of the bookmark on a network error.

  • export_on (int{} | range, optional) – Limit the export to URLs returning one of given HTTP codes; store old URLs.

  • retain_order (bool) – If True, bookmark deletion will not result in their order being changed (multiple indices will be updated instead).

Returns:

True on success, False on failure. (Deletion by del_error counts as success.)

Return type:

bool

class buku.ExtendedArgumentParser(*args, **kwargs)[source]

Bases: ArgumentParser

Extend classic argument parser.

add_argument(dest, ..., name=value, ...)[source]
add_argument(option_string, option_string, ..., name=value, ...)
add_argument_group(*args, **kwargs)[source]
static is_colorstr(arg)[source]

Check if a string is a valid color string.

Parameters:

arg (str) – Color string to validate.

Returns:

Same color string that was passed as an argument.

Return type:

str

Raises:

ArgumentTypeError – If the arg is not a valid color string.

parse_args(*args, **kwargs)[source]
print_help(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)[source]

Print help prompt.

Parameters:

file (file) – File to write program info to. Default is sys.stdout.

static program_info(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)[source]

Print program info.

Parameters:

file (file) – File to write program info to. Default is sys.stdout.

static prompt_help(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)[source]

Print prompt help.

Parameters:

file (file) – File to write program info to. Default is sys.stdout.

class buku.FetchResult(url, title, desc, keywords, mime, bad, fetch_status)[source]

Bases: NamedTuple

bad: bool

Alias for field number 5

desc: str

Alias for field number 2

fetch_status: int | None

Alias for field number 6

keywords: str

Alias for field number 3

mime: bool

Alias for field number 4

tag_error(pattern: str = None) → str[source]
tag_redirect(pattern: str = None) → str[source]
tags(*, keywords: bool = True, redirect: bool | str = False, error: bool | str = False) → str[source]
title: str

Alias for field number 1

url: str

Alias for field number 0

class buku.SortKey(value, ascending=True)[source]

Bases: object

buku.bookmark_vars(xs)
buku.browse(url, default_scheme='http')[source]

Duplicate stdin, stdout and open URL in default browser.

Note

Duplicates stdin and stdout in order to suppress showing errors on the terminal.

Parameters:

  • url (str) – URL to open in browser.

  • default_scheme (str) – Scheme to assume if missing from URL. Default is http.

buku.suppress_browser_output

True if a text based browser is detected. Must be initialized (as applicable) to use the API.

Type:

bool

buku.override_text_browser

If True, tries to open links in a GUI based browser.

Type:

bool

buku.check_stdout_encoding()[source]

Make sure stdout encoding is utf-8.

If not, print error message and instructions, then exit with status 1.

This function is a no-op on win32 because encoding on win32 is messy, and let’s just hope for the best. /s

buku.check_upstream_release()[source]

Check and report the latest upstream release version.

buku.convert_bookmark_set(bookmark_set: List[BookmarkVar], export_type: str, old: Dict[str, str | BookmarkVar] | None = None) → Dict[str, Any][source]

Convert list of bookmark set into multiple data format.

Parameters:

  • bookmark_set (bookmark set)

  • export_type (one of supported type: markdown, html, org, XBEL)

  • old (cached values of deleted records/replaced URLs to save)

Return type:

converted data and count of converted bookmark set

buku.convert_tags_to_org_mode_tags(tags: str) → str[source]

convert buku tags to org-mode compatible tags.

buku.copy_to_clipboard(content)[source]

Copy content to clipboard

Parameters:

content (str) – Content to be copied to clipboard

buku.delim_wrap(token)[source]

Returns token string wrapped in delimiters.

Parameters:

token (str) – String item to wrap with DELIM.

Returns:

Token string wrapped by DELIM.

Return type:

str

buku.disable_sigint_handler()[source]

Disable signint handler.

buku.edit_at_prompt(obj, nav, suggest=False)[source]

Edit and add or update a bookmark.

Parameters:

  • obj (BukuDb instance) – A valid instance of BukuDb class.

  • nav (str) – Navigation command argument passed at prompt by user.

  • suggest (bool) – If True, suggest similar tags on new bookmark addition.

buku.edit_rec(editor, url, title_in, tags_in, desc)[source]

Edit a bookmark record.

Parameters:

  • editor (str) – Editor to open.

  • URL (str) – URL to open.

  • title_in (str) – Title to add manually.

  • tags_in (str) – Comma-separated tags to add manually.

  • desc (str) – Bookmark description.

Returns:

Parsed results from parse_temp_file_content().

Return type:

tuple

buku.enable_sigint_handler()[source]

Enable sigint handler.

buku.extract_auth(url)[source]

Convert an url into an (auth, url) tuple [the returned URL will contain no auth part].

buku.fetch_data(url: str, http_head: bool = False) → FetchResult[source]

Handle server connection and redirections.

Parameters:

  • url (str) – URL to fetch.

  • http_head (bool) – If True, send only HTTP HEAD request. Default is False.

Returns:

(url, title, desc, keywords, mime, bad, fetch_status)

Return type:

FetchResult

buku.filter_from(values, subset, *, exclude=False)[source]
buku.format_json(resultset, single_record=False, field_filter=0)[source]

Return results in JSON format.

Parameters:

  • resultset (list) – Search results from DB query.

  • single_record (bool) – If True, indicates only one record. Default is False.

  • field_filter (int) – Indicates format for displaying bookmarks. Default is 0 (“all fields”).

Returns:

Record(s) in JSON format.

Return type:

json

buku.gen_auto_tag()[source]

Generate a tag in Year-Month-Date format.

Returns:

New tag as YYYYMonDD.

Return type:

str

buku.gen_headers()[source]

Generate headers for network connection.

buku.get_PoolManager()[source]

Creates a pool manager with proxy support, if applicable.

Returns:

ProxyManager if https_proxy is defined, PoolManager otherwise.

Return type:

ProxyManager or PoolManager

buku.get_data_from_page(resp)[source]

Detect HTTP response encoding and invoke parser with decoded data.

Parameters:

resp (HTTP response) – Response from GET request.

Returns:

(title, description, keywords).

Return type:

tuple

buku.get_firefox_db_paths(default_ff_folder, specified=None)[source]
buku.get_firefox_profile_names(path)[source]

List folder and detect default Firefox profile names for all installs.

Returns:

profiles – All default Firefox profile names.

Return type:

[str]

buku.get_netloc(url)[source]

Get the netloc token, or None.

buku.get_system_editor()[source]

Returns default system editor is $EDITOR is set.

buku.import_firefox_json(json, add_bookmark_folder_as_tag=False, unique_tag=None)[source]

Open Firefox JSON export file and import data. Ignore ‘SmartBookmark’ and ‘Separator’ entries.

Needed/used fields out of the JSON schema of the bookmarks:

title : the name/title of the entry tags : ‘,’ separated tags for the bookmark entry typeCode : 1 - uri, 2 - subfolder, 3 - separator annos/{name,value} : following annotation entries are used

name : Places/SmartBookmark : identifies smart folder, ignored name : bookmarkPropereties/description : detailed bookmark entry description

children : for subfolders, recurse into the child entries

Parameters:

  • path (str) – Path to Firefox JSON bookmarks file.

  • unique_tag (str) – Timestamp tag in YYYYMonDD format.

  • add_bookmark_folder_as_tag (bool) – True if bookmark parent folder should be added as tags else False.

buku.import_html(html_soup: BeautifulSoup, add_parent_folder_as_tag: bool, newtag: str, use_nested_folder_structure: bool = False)[source]

Parse bookmark HTML.

Parameters:

  • html_soup (BeautifulSoup object) – BeautifulSoup representation of bookmark HTML.

  • add_parent_folder_as_tag (bool) – True if bookmark parent folders should be added as tags else False.

  • newtag (str) – A new unique tag to add to imported bookmarks.

  • use_nested_folder_structure (bool) – True if all bookmark parent folder should be added, not just direct parent else False add_parent_folder_as_tag must be True for this flag to have an effect

Returns:

Parsed result.

Return type:

tuple

buku.import_md(filepath: str, newtag: str | None)[source]

Parse bookmark Markdown file.

Parameters:

  • filepath (str) – Path to Markdown file.

  • newtag (str, optional) – New tag for bookmarks in Markdown file.

Returns:

Parsed result.

Return type:

tuple

buku.import_org(filepath: str, newtag: str | None)[source]

Parse bookmark org file.

Parameters:

  • filepath (str) – Path to org file.

  • newtag (str, optional) – New tag for bookmarks in org file.

Returns:

Parsed result.

Return type:

tuple

buku.import_rss(filepath: str, newtag: str | None)[source]

Parse bookmark RSS file.

Parameters:

  • filepath (str) – Path to RSS file.

  • newtag (str, optional) – New tag for bookmarks in RSS file.

  • Returns

  • tuple – Parsed result.

buku.import_xbel(html_soup: BeautifulSoup, add_parent_folder_as_tag: bool, newtag: str, use_nested_folder_structure: bool = False)[source]

Parse bookmark XBEL.

Parameters:

  • html_soup (BeautifulSoup object) – BeautifulSoup representation of bookmark HTML.

  • add_parent_folder_as_tag (bool) – True if bookmark parent folders should be added as tags else False.

  • newtag (str) – A new unique tag to add to imported bookmarks.

  • use_nested_folder_structure (bool) – True if all bookmark parent folder should be added, not just direct parent else False add_parent_folder_as_tag must be True for this flag to have an effect

Returns:

Parsed result.

Return type:

tuple

buku.is_bad_url(url)[source]

Check if URL is malformed.

Note

This API is not bulletproof but works in most cases.

Parameters:

url (str) – URL to scan.

Returns:

True if URL is malformed, False otherwise.

Return type:

bool

buku.is_editor_valid(editor)[source]

Check if the editor string is valid.

Parameters:

editor (str) – Editor string.

Returns:

True if string is valid, else False.

Return type:

bool

buku.is_ignored_mime(url)[source]

Check if URL links to ignored MIME.

Note

Only a ‘HEAD’ request is made for these URLs.

Parameters:

url (str) – URL to scan.

Returns:

True if URL links to ignored MIME, False otherwise.

Return type:

bool

buku.is_int(string)[source]

Check if a string is a digit.

stringstr

Input string to check.

Returns:

True on success, False on exception.

Return type:

bool

buku.is_nongeneric_url(url)[source]

Returns True for URLs which are non-http and non-generic.

Parameters:

url (str) – URL to scan.

Returns:

True if URL is a non-generic URL, False otherwise.

Return type:

bool

buku.is_unusual_tag(tagstr)[source]

Identify unusual tags with word to comma ratio > 3.

Parameters:

tagstr (str) – tag string to check.

Returns:

True if valid tag else False.

Return type:

bool

buku.like_escape(s, c='`')
buku.main(argv=['-T', '-b', 'html', '-d', '_build/doctrees', '-D', 'language=en', '.', '/home/docs/checkouts/readthedocs.org/user_builds/buku/checkouts/stable/_readthedocs//html'], *, program_name='__main__.py')[source]

Main.

buku.monkeypatch_textwrap_for_cjk()[source]

Monkeypatch textwrap for CJK wide characters.

buku.network_handler(url: str, http_head: bool = False) → Tuple[str, str, str, int, int][source]

Handle server connection and redirections.

Deprecated; use fetch_data() instead.

Returns:

(title, description, tags, recognized mime, bad url)

Return type:

tuple

buku.parse_decoded_page(page)[source]

Fetch title, description and keywords from decoded HTML page.

Parameters:

page (str) – Decoded HTML page.

Returns:

(title, description, keywords).

Return type:

tuple

buku.parse_order(order)
buku.parse_range(tokens: str | Sequence[str] | Set[str] | None, valid: Callable[[int], bool] | None = None, maxidx: int = None) → Set[int] | None[source]

Convert a token or sequence/set of token into a set of indices.

Raises a ValueError on invalid token. Returns None if passed None as tokens.

Parameters:

  • tokens (str | str[] | str{}, optional) – String(s) containing an index (#), or a range (#-#), or a comma-separated list thereof.

  • valid ((int) -> bool, optional) – Additional check for invalid indices (default is None).

  • maxidx (int, optional) – When specified, negative indices are valid and parsed as tail-ranges.

Returns:

None if tokens is None, otherwise parsed indices as unordered set.

Return type:

Optional[Set[int]]

buku.parse_tags(keywords=[], *, edit_input=False)[source]

Format and get tag string from tokens.

Parameters:

  • keywords (list) – List of tags to parse. Default is empty list.

  • edit_input (bool) – Whether the taglist is an edit input (i.e. may start with ‘+’/’-‘). Defaults to False.

Returns:

  • str – Comma-delimited string of tags.

  • DELIM (str) – If no keywords, returns the delimiter.

  • None – If keywords is None.

buku.parse_temp_file_content(content)[source]

Parse and return temporary file content.

Parameters:

content (str) – String of content.

Returns:

(url, title, tags, comments)

url: URL to open title: string title to add manually tags: string of comma-separated tags to add manually comments: string description

Return type:

tuple

buku.piped_input(argv, pipeargs=None)[source]

Handle piped input.

Parameters:

pipeargs (str)

Prepare list of tags to search and determine search operator.

Parameters:

tags (str) – String list of tags to search.

Returns:

(list of formatted tags to search,

a string indicating query search operator (either OR or AND), a regex string of tags or None if ‘ - ‘ delimiter not in tags).

Return type:

tuple

buku.print_json_safe(resultset, single_record=False, field_filter=0)[source]

Prints json results and handles IOError

Parameters:

  • resultset (list) – Search results from DB query.

  • single_record (bool) – If True, indicates only one record. Default is False.

  • field_filter (int) – Indicates format for displaying bookmarks. Default is 0 (“all fields”).

Return type:

None

buku.print_rec_with_filter(records, field_filter=0)[source]

Print records filtered by field.

User determines which fields in the records to display by using the –format option.

Parameters:

  • records (list or sqlite3.Cursor object) – List of bookmark records to print

  • field_filter (int) – Integer indicating which fields to print. Default is 0 (“all fields”).

buku.print_single_rec(row: BookmarkVar, idx: int = 0, columns: int = 0)[source]

Print a single DB record.

Handles both search results and individual record.

Parameters:

  • row (tuple) – Tuple representing bookmark record data.

  • idx (int) – Search result index. If 0, print with DB index. Default is 0.

  • columns (int) – Number of columns to wrap comments to. Default is 0.

buku.prompt(obj, results, noninteractive=False, deep=False, listtags=False, suggest=False, num=10, markers=False, order=['+id'])[source]

Show each matching result from a search and prompt.

Parameters:

  • obj (BukuDb instance) – A valid instance of BukuDb class.

  • results (list) – Search result set from a DB query.

  • noninteractive (bool) – If True, does not seek user input. Shows all results. Default is False.

  • deep (bool) – Use deep search. Default is False.

  • markers (bool) – Use search-with-markers. Default is False.

  • listtags (bool) – If True, list all tags.

  • suggest (bool) – If True, suggest similar tags on edit and add bookmark.

  • order (list of str) – Order description (fields from JSON export or DB, prepended with ‘+’/’-’ for ASC/DESC).

  • num (int) – Number of results to show per page. Default is 10.

buku.read_in(msg)[source]

A wrapper to handle input() with interrupts disabled.

Parameters:

msg (str) – String to pass to to input().

buku.regexp(expr, item)[source]

Perform a regular expression search.

Parameters:

  • expr (regex) – Regular expression to search for.

  • item (str) – Item on which to perform regex search.

Returns:

True if result of search is not None, else False.

Return type:

bool

buku.setcolors(args)[source]

Get colors from user and separate into ‘result’ list for use in arg.colors.

Parameters:

args (str) – Color string.

buku.setup_logger(LOGGER)[source]

Setup logger with color.

Parameters:

LOGGER (logger object) – Logger to colorize.

buku.show_taglist(obj)[source]

Additional prompt to show unique tag list.

Parameters:

obj (BukuDb instance) – A valid instance of BukuDb class.

buku.sigint_handler(signum, frame)[source]

Custom SIGINT handler.

Note

Neither signum nor frame are used in this custom handler. However, they are required parameters for signal handlers.

Parameters:

  • signum (int) – Signal number.

  • frame (frame object or None.)

buku.split_by_marker(s)
buku.strip_delim(s, delim=',', sub=' ')
buku.taglist(ss)
buku.taglist_str(tag_str, convert=None)[source]
buku.to_temp_file_content(url, title_in, tags_in, desc)[source]

Generate temporary file content string.

Parameters:

  • url (str) – URL to open.

  • title_in (str) – Title to add manually.

  • tags_in (str) – Comma-separated tags to add manually.

  • desc (str) – String description.

Returns:

Lines as newline separated string.

Return type:

str

Raises:

AttributeError – when tags_in is None.

buku.unwrap(text)[source]

Unwrap text.

buku.walk(root)[source]

Recursively iterate over JSON.

Parameters:

root (JSON element) – Base node of the JSON data.

buku.write_string_to_file(content: str, filepath: str)[source]

Writes given content to file

Parameters:

  • content (str)

  • filepath (str)

Return type:

None