buku module

class buku.BukuCrypt[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: 64 KB blocks

CHUNKSIZE: Read/write 512 KB chunks

BLOCKSIZE = 65536

CHUNKSIZE = 524288

SALT_SIZE = 32

static decrypt_file(iterations, dbfile=None)[source]

Decrypt the bookmarks database file.

Parameters

iterations (int) – Number of iterations for key generation.
dbfile (str, optional) – Custom database file path (including filename). The ‘.enc’ suffix must be omitted.

static encrypt_file(iterations, dbfile=None)[source]

Encrypt the bookmarks database file.

Parameters

iterations (int) – Number of iterations for key generation.
dbfile (str, optional) – Custom database file path (including filename).

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: Optional[str] = None, field_filter: Optional[int] = 0, chatty: Optional[bool] = False, dbfile: Optional[str] = None, colorize: Optional[bool] = True)[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: Optional[str] = None, tags_in: Optional[str] = None, desc: Optional[str] = None, immutable: Optional[int] = 0, delay_commit: Optional[bool] = False, fetch: Optional[bool] = True) → 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. Must start and end with comma. Default is None.
desc (str, optional) – Description of the bookmark. Default is None.
immutable (int, optional) – Indicates whether to disable title fetch from web. Default is 0.
delay_commit (bool, optional) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.
fetch (bool, optional) – Fetch page from web and parse for data

Returns

DB index of new bookmark on success, -1 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) – DB index of the record. 0 indicates all records.
tags_in (str) – Comma-separated tags to add manually.
delay_commit (bool, optional) – 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()[source]

Import bookmarks from a browser default database file.

Supports Firefox and Google Chrome.

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()[source]

Drops the bookmark table if it exists.

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, optional) – Program exit value.

compactdb(index: int, delay_commit: 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, optional) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.

delete_rec(index: Optional[int] = None, low: int = 0, high: int = 0, is_range: bool = False, delay_commit: 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, optional) – Actual lower index of range.
high (int, optional) – Actual higher index of range.
is_range (bool, optional) – A range is passed using low and high arguments. An index is ignored if is_range is True.
delay_commit (bool, optional) – True if record should not be committed to the DB, leaving commit responsibility to caller. 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 paramaters 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, optional) – 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)[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.
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) – DB index of bookmark record. 0 indicates all records.
tags_in (str) – Comma-separated tags to delete manually.
delay_commit (bool, optional) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.
chatty (bool, optional) – Skip confirmation when set to False.

Returns

True on success, False on failure.

Return type

bool

edit_update_rec(index, immutable=- 1)[source]

Edit in editor and update a record.

Parameters

index (int) – DB index of the record. Last record, if index is -1.
immutable (int, optional) – Diable title fetch from web if 1. Default is -1.

Returns

True if updated, else False.

Return type

bool

exclude_results_from_search(search_results, without, deep)[source]

Excludes records that match keyword search using without parameters

Parameters

search_results (list) – List of search results
without (list of str) – Keywords to search.
deep (bool, optional) – True to search for matching substrings.

Returns

List of search results, or None if no matches.

Return type

list or None

exportdb(filepath: str, resultset: Optional[List[Tuple[int, str, Optional[str], str, str, int]]] = None) → bool[source]

Export DB bookmarks to file. Exports full DB, if resultset is None

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 a org 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.

Returns

True on success, False on failure.

Return type

bool

fixtags()[source]

Undocumented API to fix tags set in earlier versions.

Functionalities:

Remove duplicate tags
Sort tags
Use lower case to store tags

static get_default_dbdir()[source]

Determine the directory path where dbfile will be stored.

If the platform is Windows, use %APPDATA% else if $XDG_DATA_HOME is defined, use it else if $HOME exists, use it else use the current directory.

Returns: Path to database file.
Return type: str

get_max_id() → int[source]

Fetch the ID of the last record.

Returns: ID of the record if any record exists, else -1.
Return type: int

get_rec_all()[source]

Get all the bookmarks in the database.

Returns: A list of tuples representing bookmark records.
Return type: list

get_rec_by_id(index: int) → Optional[Tuple[int, str, Optional[str], str, str, int]][source]

Get a bookmark from database by its ID.

Parameters: index (int) – DB index of bookmark record.
Returns: Bookmark data, or None if index is not found.
Return type: tuple or None

get_rec_id(url)[source]

Check if URL already exists in DB.

Parameters: url (str) – A URL to search for in the DB.
Returns: DB index, or -1 if URL not found in DB.
Return type: int

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 a HTML or a Markdown file.

Supports Firefox, Google Chrome, and IE exported HTML bookmarks. 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, optional) – 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: Optional[str] = None, chatty: Optional[bool] = False) → Tuple[sqlite3.Connection, sqlite3.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=[])[source]

List entries in the DB using the specified id list.

Parameters: ids (list of ids in string form) –
Returns
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_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 = 0, low: int = 0, high: int = 0, is_range: bool = False) → 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, optional) – DB index of record to print. 0 prints all records.
low (int, optional) – Actual lower index of range.
high (int, optional) – Actual higher index of range.
is_range (bool, optional) – A range is passed using low and high arguments. An index is ignored if is_range is True.

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 paramaters 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, threads: int) → bool[source]

Refresh ALL records in the database.

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

Notes

This API doesn’t change DB index, URL or tags of a bookmark. This API is verbose.

Parameters

index (int) – DB index of record to update. 0 indicates all records.
threads (int) – Number of threads to use to refresh full DB. Default is 4.

replace_tag(orig: str, new: Optional[List[str]] = None) → bool[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.

Returns

True on success, False on failure.

Return type

bool

search_by_tag(tags: Optional[str]) → Optional[List[Tuple[int, str, Optional[str], str, str, int]]][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 ‘+’.
Returns: List of search results, or None if no matches.
Return type: list or None

search_keywords_and_filter_by_tags(keywords: List[str], all_keywords: bool, deep: bool, regex: bool, stag: str) → Optional[List[Tuple[int, str, Optional[str], str, str, int]]][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.
all_keywords (bool, optional) – True to return records matching ALL keywords. False to return records matching ANY keyword.
deep (bool, optional) – True to search for matching substrings.
regex (bool, optional) – Match a regular expression if True.
stag (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 ‘+’.

Returns

List of search results, or None if no matches.

Return type

list or None

searchdb(keywords: List[str], all_keywords: Optional[bool] = False, deep: Optional[bool] = False, regex: Optional[bool] = False) → Optional[Iterable[Any]][source]

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

Parameters

keywords (list of str) – Keywords to search.
all_keywords (bool, optional) – True to return records matching ALL keywords. False (default value) to return records matching ANY keyword.
deep (bool, optional) – True to search for matching substrings. Default is False.
regex (bool, optional) – Match a regular expression if True. Default is False.

Returns

List of search results, or None if no matches.

Return type

list or None

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

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

Shorten a URL using Google URL shortener.

Parameters

index (int, optional (if URL is provided)) – DB index of the bookmark with the URL to shorten. Default is 0.
url (str, optional (if index is provided)) – URL to shorten.
shorten (bool, optional) – True to shorten, False to expand. Default is False.

Returns

Shortened url on success, None on failure.

Return type

str

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, url: Optional[str] = None, title_in: Optional[str] = None, tags_in: Optional[str] = None, desc: Optional[str] = None, immutable: Optional[int] = - 1, threads: int = 4) → bool[source]

Update an existing record at index.

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

Parameters

index (int) – DB index of record. 0 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 (int, optional) – Disable title fetch from web if 1. Default is -1.
threads (int, optional) – Number of threads to use to refresh full DB. Default is 4.

Returns

True on success, False on Failure.

Return type

bool

class buku.ConverterResult(*args, **kwargs)

Bases: dict

count: int

data: str

class buku.ExtendedArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)[source]

Bases: argparse.ArgumentParser

Extend classic argument parser.

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.

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

Print help prompt.

Parameters: file (file, optional) – 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, optional) – 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, optional) – File to write program info to. Default is sys.stdout.

buku.browse(url)[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.

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[Tuple[int, str, Optional[str], str, str, int]], export_type: str) → buku.ConverterResult[source]

Convert list of bookmark set into multiple data format.

Parameters

bookmark_set (bookmark set) –
type (export) –

Returns

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, optional) – 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.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, optional) – If True, indicates only one record. Default is False.
field_filter (int, optional) – Indicates format for displaying bookmarks. Default is 0.

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_profile_name(path)[source]

List folder and detect default Firefox profile name.

Returns: profile – Firefox profile name.
Return type: str

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: bs4.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: Optional[str])[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: Optional[str])[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.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.main()[source]: Main.

buku.monkeypatch_textwrap_for_cjk()[source]: Monkeypatch textwrap for CJK wide characters.

buku.network_handler(url: str, http_head: Optional[bool] = False) → Tuple[Optional[str], Optional[str], Optional[str], int, int][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

(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_tags(keywords=[])[source]

Format and get tag string from tokens.

Parameters

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

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) –

buku.prep_tag_search(tags: str) → Tuple[List[str], Optional[str], Optional[str]][source]

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, optional) – If True, indicates only one record. Default is False.
field_filter (int, optional) – Indicates format for displaying bookmarks. Default is 0.

Returns

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.

buku.print_single_rec(row: Tuple[int, str, Optional[str], str, str, int], idx: Optional[int] = 0, columns: Optional[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, optional) – Search result index. If 0, print with DB index. Default is 0.
columns (int, optional) – Number of columns to wrap comments to. Default is 0.

buku.prompt(obj, results, noninteractive=False, deep=False, listtags=False, suggest=False, num=10)[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, optional) – If True, does not seek user input. Shows all results. Default is False.
deep (bool, optional) – Use deep search. Default is False.
listtags (bool, optional) – If True, list all tags.
suggest (bool, optional) – If True, suggest similar tags on edit and add bookmark.
num (int, optional) – 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.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) –

Returns

Return type

None